TIBCO €¦ · 1. the module of the licensor software called tibco formvine® project tools allows licensor to create and manage tibco formvine® projects,

Two-Second Adv

TIBCO Formvine®

Implementation GuideSoftware Release 3.3.1June 2013

antage®

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME. FOR THE AFOREMENTIONED LICENSES "NAMED USERS" SHALL MEAN IDENTIFIABLE INDIVIDUALS DESIGNATED AS AN 'OWNER', 'DESIGNER', OR 'DATA EDITOR' ASSOCIATED WITH A CURRENT PROJECT LISTED IN THE 'ADMIN REPORT' AS MORE FULLY DESCRIBED IN THE DOCUMENTATION FOR THIS PRODUCT. THE FOLLOWING USAGE RESTRICTIONS APPLY TO YOUR USE OF THE LICENSOR SOFTWARE:1. THE MODULE OF THE LICENSOR SOFTWARE CALLED TIBCO FORMVINE® PROJECT TOOLS ALLOWS LICENSOR TO CREATE AND MANAGE TIBCO FORMVINE® PROJECTS, AND TO VIEW, EDIT AND EXPORT THE DATA HANDLED AND PROCESSED BY TIBCO FORMVINE® SERVER SOFTWARE. ONLY THE NUMBER OF NAMED USERS LISTED IN ACCEPTED ORDER FORMS WHICH INCLUDE TIBCO FORMVINE® PROJECT TOOLS SHALL HAVE RIGHTS TO USE THE "PROJECT TOOLS" AS DEFINED IN THE DOCUMENTATION. 2. THE MODULE OF THE LICENSOR SOFTWARE CALLED TIBCO FORMVINE® INTEGRATION ADD-ON ALLOWS SOFTWARE OTHER THAN TIBCO FORMVINE® PROJECT TOOLS TO EXCHANGE INFORMATION WITH THE TIBCO FORMVINE® SERVER BY WAY OF TIBCO FORMVINE® SERVER'S APPLICATION PROGRAMMING INTERFACES ("FORMVINE® APIs"). ONLY TO THE EXTENT THAT ACCEPTED ORDER FORMS INCLUDE RIGHTS TO USE TIBCO FORMVINE® INTEGRATION ADD-ON, SHALL LICENSEE HAVE RIGHTS TO USE SOFTWARE OTHER THAN THE LICENSED TIBCO FORMVINE® PROJECT TOOLS IN CONJUNCTION WITH THE FORMVINE® APIs.This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc.

TIBCO, The Power of Now, Two-Second Advantage, and TIBCO Formvine® are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only.THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.

THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.Copyright © 2013 TIBCO Software Inc. ALL RIGHTS RESERVED.TIBCO Software Inc. Confidential Information6/24/13

Contents | 4

Contents

Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Related documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Typographical conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

How to contact TIBCO support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Chapter 1 Customize your Formvine implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Why customize?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Who does the work? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

About the customization process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Chapter 2 Branding your Formvine implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Why brand your implementation? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

The Formvine brand. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Where is the Formvine brand displayed? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Recommendations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Implementing a customized Formvine brand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Branding the form footer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Branding Formvine forms with a visual style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Creating a new visual style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Chapter 3 Customizing voice and style for Formvine communications. . . . . . . . . . . . . . . . . . 27

Why customize communications? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Customizing the launch page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29How to customize the launch page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Customizing the confirmation page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Customizing the thank you page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Chapter 4 Advanced configuration options for the Formvine application . . . . . . . . . . . . . . . . 37

About the advanced options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

TIBCO Formvine Implementation Guide

Contents | 5

Usage limit properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

User registration properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

User session properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Security properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Challenge-response properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Space creation properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Audit log display property. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Additional properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Chapter 5 Customizing controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Formvine controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

What is customizable? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Adding and removing controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Simple controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Validated controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Changing validation for a control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

File Upload control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Customizing the File Upload control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Compound controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Anatomy of a compound control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Creating a new compound control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Example: Australian address compound control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74


Preface | 6

Preface

This document is for the people responsible for configuring and customizing TIBCO Formvine® after it has been installed at your site. All the team members working on the implementation should read this guide.

In addition, team members should read the TIBCO Formvine Email Customization Guide. This guide outlines the customizations you can apply to all email generated by Formvine®.

Topics

• Related documentation, page 7

• Typographical conventions, page 9

• How to contact TIBCO support, page 10

For the latest version of this document, go to: https://docs.tibco.com/products/tibco-formvine


Preface | 7

Related documentation

The following are included in the Formvine documentation set, which is available at: https://docs.tibco.com/products/tibco-formvine

• TIBCO Formvine Concepts Guide—Describes how Formvine addresses business needs and explains the characteristics of the people who use Formvine.

• TIBCO Formvine Installation and Implementation Checklists—Provides requirements checklists for installing and customizing Formvine.

• TIBCO Formvine Installation Guide—Provides installation instructions.

• TIBCO Formvine Implementation Guide (this document)—Explains options for customizing branding, the Formvine application, and Formvine controls. Provides instructions for implementing the customizations.

• TIBCO Formvine Email Customization Guide—Explains options for customizing messaging and provides instructions for implementing the customizations.

• TIBCO Formvine Administration Guide—Provides information on reporting, troubleshooting, and adding templates to your implementation

• TIBCO Formvine Application Programming Interface Reference Guide—Describes the TIBCO Formvine application programming interface (API).

• TIBCO Formvine External User Group Source Programming Interface Reference Guide—Describes the service provider interface to an external user group source.

Additional information about Formvine is available here:

• For the latest updates on Formvine installation and configuration requirements, see the readme file on the Formvine Documents page.

• For information on the current Formvine release, including closed and known issues, see the product release notes on the Formvine Documents page.

The Formvine Resource Center at resources.formvine.com hosts:

• Quick Start—Helps your project owners get started with Formvine.

• Help—Gives instructions on all aspects of using Formvine, and includes descriptions of all the Formvine templates.

• Videos—Links to the Formvine video channel, where you can see videos about using Formvine and integrating Formvine with other systems.


http://resources.formvine.com

Preface | 8

• TIBCOmmunity—Links to the Formvine TIBCOmmunity page, where you can get even more information about Formvine, ask questions, and participate in conversations to make the most of your Formvine installation.

• Tech Docs—Links to the Formvine documentation page at: https://docs.tibco.com/products/tibco-formvine

• Contact Us—Let us know how we can help.


https://docs.tibco.com/products/tibco-formvine

Preface | 9

Typographical conventions

The following typographical conventions are used in this manual.

Table 1 General typographical conventions

Convention Use

install_directory The directory where Formvine is installed.

TIBCO_FV_HOME The Formvine home directory: install_directory/fv/3.3

formvine_url URL for project owners to access Formvine, specified at installation:http://host:port/fv

italic font Italic font is used for new terms and variables in email text.

code font italic Variable name.

code font Commands, filenames, pathnames, property names and value, code examples, and command output.

bold code font Code that you type in a command window or a properties file.

Information that is of special interest or importance, for example, an additional action required only in certain circumstances.

An idea that could be useful, for example, a way to apply the information provided in the current section to achieve a specific result.

Potential for a damaging situation, for example, data loss or corruption if certain steps are taken or not taken.

Security consideration. Check with your IT department and/or database administrator.


Preface | 10

How to contact TIBCO support

For comments or problems with this manual or the software it addresses, please contact TIBCO Support as follows:

• For an overview of TIBCO Support, and information about getting started with TIBCO Support, visit this site:http://www.tibco.com/services/support

• If you already have a valid maintenance or support contract, visit this site:https://support.tibco.com

— Entry to this site requires a username and password. If you do not have a username, you can request one.


http://www.tibco.com/services/support

https://support.tibco.com

Customize your Formvine implementation | 11

Chapter 1 Customize your Formvine implementation

You can customize your TIBCO Formvine® implementation in a variety of ways, from visual branding to style and content. What you choose to customize depends on your Formvine® use case. This chapter introduces you to the customization process.

Topics

• Why customize?, page 12

• Who does the work?, page 13

• Examples, page 14

• About the customization process, page 15


Why customize? | 12

Why customize?

Formvine is a flexible application that can be tailored specifically for your use case. In addition to options available at installation, you can change a number of things after you’ve installed Formvine. Changes fall into two categories: customization changes and configuration changes.

Customization changes are changes to files that create the Formvine web application. These changes are not carried forward when you upgrade. Configuration changes are changes to properties files. These types of changes are carried forward on upgrade. See About the customization process, page 15 for more information.

Customization options include:

• How the application and forms are branded.

• The voice and tone of messaging.

• What controls are available for designing Formvine forms.

• The visual styles available for Formvine forms.

• The voice used in all communications, including user account emails, system emails, and notification emails to submitters and task assignees.

Configuration options include settings such as:

• The domains allowed for registration.

• The number of projects allowed per user account.

• What file types can be uploaded and the maximum file size.

• How long the user sign-in cookie is remembered.

This document explains the customization and configuration possibilities and make you aware of the options available to you. We don’t want to suggest that you should make sweeping changes to the generic Formvine application.


Who does the work? | 13

Who does the work?

To implement Formvine customization and configuration changes, you may need a visual designer, a copywriter, and a web designer who is experienced with CSS, XML, and HTML. Your implementation engineer will most likely implement the changes. Be sure to thoroughly test your implementation, including the launch page, the Project Tools, forms, tasks, and emails and notifications, before you roll out to project owners.


Examples | 14

Examples

This document uses these different implementations of Formvine as examples:

• The generic implementation of Formvine contains content, templates and visuals with no additional customization or configuration changes.

• The reference implementations have been customized to meet specific requirements. We use the following reference implementations to illustrate variations in the available customizations.

— The TIBCO implementation is the one used by TIBCO for employees to build projects and collect results from other employees, contractors, customers, prospects and partners.

— The Formvine.com implementation is a free, hosted Formvine service, available for anyone to use.


About the customization process | 15

About the customization process

When you customize Formvine, it is important to note that not all changes are carried forward when you upgrade to a new release.Customization changes are edits made to files in the TIBCO_FV_HOME/WebContent folder. These edits are not carried forward when you upgrade. After upgrading, you need to reimplement any changes made to files in this folder.Before editing any file, back up the default files shipped with Formvine. Before upgrading, back up any files you have edited. This is because reapplying customizations after an upgrade is not a matter of copying the customized file from before the upgrade. In some cases, the underlying file may have been changed in the upgrade and actual customizations will have to be applied directly to the new file after the upgrade. Configuration changes are the changes applied to configuration property files in the TIBCO_FV_HOME/config folder, such as features.properties. These changes are migrated during the upgrade process. You do not have to reapply them after an upgrade. Most of the changes described in Advanced configuration options for the Formvine application, page 37 apply to configuration changes that are autmatically upgraded.

If you are running Formvine on an application server other than the embedded Tomcat, you need to make the corresponding changes to the WAR file and redeploy.


Branding your Formvine implementation | 16

Chapter 2 Branding your Formvine implementation

You can brand your TIBCO Formvine® implementation so that it meets the needs of your audience. How you brand Formvine® depends on your use case. This chapter explains the branding process.

Topicss

• Why brand your implementation?, page 17

• The Formvine brand, page 18

• Implementing a customized Formvine brand, page 21

• Branding the form footer, page 24

• Branding Formvine forms with a visual style, page 25


Why brand your implementation? | 17

Why brand your implementation?

Brands help create familiarity, loyalty and comfort with a product. How the various players associated with your Formvine instance see the brand can directly affect the success of the project.

The Formvine brand helps orient your project owners. It provides a reference point for stakeholders in your organization and connects the application with the online community services at the Formvine Resource Center.

When you’re thinking about branding your implementation, consider your users:

• Will all project owners be employees? If so, you can use the brand to unify the Formvine product with other applications used in-house by employees.

• Will project owners be outside your organization? If project owners are not employees, you can use this opportunity to promote your customized Formvine brand that includes your company name.

• Will form submitters be outside your organization? If so, you might want to use a customized Formvine brand with your company name for orientation.


The Formvine brand | 18

The Formvine brand

The standard Formvine brand consists of the word “Formvine,” in the Frutiger Light font.

Figure 1 Formvine brand

You can augment this standard brand for your enterprise. For example, in the Formvine at TIBCO and Formvine.com reference implementations, we used different variations of the standard brand to show the context of the installation.

When deciding to install Formvine for TIBCO employees to use for company business, we could have used the name of our intranet, “Inside TIBCO,” to draw a connection between Formvine and the other intranet services. Instead, we decided to add text to the standard Formvine brand so that anyone logged in would know they were using Formvine at TIBCO. The following figure illustrates the Formvine at TIBCO brand.

Figure 2 Formvine at TIBCO brand

The Formvine.com implementation is a free hosted service that is available for anyone to use. It demonstrates the power and utility of Formvine. In that implementation, we use a Formvine.com mark, another variation on the standard Formvine brand. The following figure illustrates the Formvine.com brand.

Figure 3 Formvine.com brand

The Formvine Resource Center was created to allow users of Formvine to get help from community members, including the product developers. The Formvine logo creates a connection between your instance and this helpful, public website. The following figure shows the Formvine Resource Center brand:

Figure 4 Formvine Resource Center brand



Formvine customers have implemented the Formvine brand in a variety of ways, according to their specific use case. Some customers have integrated their company name into the brand, as we do with our implementation at TIBCO. Some customers use their company logo in place of the Formvine logo. Others completely replace the Formvine logo by designing their own logo for Formvine.

ExamplesThe following figure shows the generic implementation of the Formvine brand.

Figure 5 Formvine brand - generic implementation

The following figure shows the Formvine at TIBCO reference implementation of the Formvine brand.

Figure 6 Formvine brand - reference implementation



And this figure shows the Formvine.com brand.


Here’s an example of an online form for a rental car company. The Formvine logo has been replaced with the company logo, so that customers or insurance adjustors in the field know where the form originated.


Where is the Formvine brand displayed? The Formvine brand is displayed on the launch page, on the registration and sign in pages, in the Project Tools, on forms that submitters fill out, in tasks completed by task assignees, and in all email messages that are sent out for administrative and notification purposes.



RecommendationsWe recommend the following:

• Keep the Formvine brand but append text, for example, the name of your enterprise or division, that is familiar to your project owners.

• Use your company brand in places where those unfamiliar with Formvine might be confused, for example in notifications to outside recipients.

• Check with your Legal department before removing or altering any Formvine or TIBCO brands and messages.

• If your users have access to more than one Formvine implementation, clearly identify each to avoid confusion.

The important thing to consider is how you want your own brand to interact with the Formvine brand for optimal recognition for project owners, management, submitters, IT, and support.

Implementing a customized Formvine brandThere are several ways to implement the customized Formvine brand:

• To add text to the existing logo, for example, "AT COMPANY NAME," use the Admin Tool. Follow the instructions in the section called Implement the brand with the Admin tool, page 22.

• To point to an existing company brand at an existing URL, use the Admin Tool. Follow the instructions in the section called Implement the brand with the Admin tool, page 22.

• To completely replace the existing Formvine logo with your own, follow the instructions in the procedure called Implement the brand using your own logo, page 22.

When you’re done with the implementation, review your changes in different browsers and on mobile devices.

You need to shut down the Formvine server before implementing these changes.



Implement the brand with the Admin tool

To add text to the existing logo, or point to an existing logo at a URL, follow the instructions below.

1. Open the Admin Tool at: formvine_url/secure

You must be authorized; if you are not an authorized user, you will see an error page. Contact your Formvine Administrator.

2. Click the Settings tab.

3. Scroll to the Brand section on the page.

4. To change the brand, do one of the following:

— Click the Formvine button to add text to the existing logo.

In the input field leave the word at, but replace the braces and the text [YOUR COMPANY NAME] with the name of your company, for example: EXAMPLE COMPANY

— Click the URL to your company logo option to use an existing logo at a URL.

Enter the URL to the logo. The existing logo should be 41 pixels high or smaller. If it is taller, it will be truncated.

5. Click Save settings. You’ll see the change immediately at the top of the Admin Tool. You don’t need to restart Formvine or clear the cache.

Implement the brand using your own logo

These instructions outline how to completely replace the Formvine brand with your own logo. Before you begin, you need the new logo that is 41 pixels high and 159 pixels wide.

This customization is not carried forward on upgrade. See About the customization process, page 15 for more information.

1. Navigate to the following folder in your Formvine installation:TIBCO_FV_HOME/WebContent/versionedfiles/images/logos/

2. Make a backup copy of the file: fv_159x41.png This file contains the default Formvine logo. You are overwriting this file in the next step.

3. Copy your logo that is 41 pixels high and 159 pixels in width, to the logos folder. Change the name to: fv_159x41.png



4. Repeat Steps 2 and 3 for the high resolution version of the brand: fv_159x41_r.png

5. Reload Formvine to see your brand displayed. (Your browser might require that you clear the cache before seeing the updated brand.) Make sure you look at it on mobile devices as well.


Branding the form footer | 24

Branding the form footer

If you choose not to create a visual style for your forms, you can just add your company logo to the footer on forms that submitters fill out. The following figure shows the generic implementation of the Formvine footer. You cannot change or remove any of the text or graphics you see in this figure; your license requires that you keep the default, generic footer implementation.

Figure 9 Formvine form footer - generic implementation

The example below shows the same footer with the TIBCO logo.

Figure 10 Formvine form footer with additional logo

Brand the footer

Edits to the footer are not carried forward on upgrade. See About the customization process, page 15 for more information.

1. Place your company logo in the following folder:TIBCO_FV_HOME/WebContent/versionedfiles/images/logos

2. Navigate to the TIBCO_FV_HOME/WebContent/WEB-INF/classes/ folder.

3. Open Runtime.properties in a text editor and locate the footer property at the top of the file. Note: By your license agreement, you cannot remove the existing footer contents, but you may append to it.

4. Add an image tag pointing to your company logo.

5. Save the file.

6. Reload Formvine and open an online form to see your company logo displayed in the footer. (Your browser might require that you clear the cache before seeing the updated footer.) You may have to experiment with placement.


Branding Formvine forms with a visual style | 25

Branding Formvine forms with a visual style

Many people may be exposed to your Formvine implementation exclusively as submitters (people who fill out forms). If needed, You can customize the visual style to extend your company branding and messaging out to submitters.

A visual style is a specific color scheme and text style that can be applied to a project. The generic implementation of Formvine has several default visual styles that a project owner can choose from. A total of nine styles are available:

• The four standard styles are sized for readability.

• The four compact styles are sized to minimize scrolling.

• The solitary narrow style is sized to fit into a web page.

The visual style is applied to all pages of a form, including the project’s confirmation page and the project’s thank you page. The visual style also controls the form’s header and footer.

You can change the look and feel of the default visual styles by updating or adding CSS files. You can also create a specific visual style for an individual project and provide those CSS files to the project owner. A visual style doesn’t necessarily have to be exposed to all Formvine users.

Creating a new visual styleThe runtime form styles are defined by the theme.css style sheets in the theme folders. Theme folders are located here:

TIBCO_FV_HOME/WebContent/versionedfiles/themes/<THEME_NAME>

You can use the existing themes as examples to create your own. Then, register the theme in the themes.js file in the TIBCO_FV_HOME/WebContent/versionedfiles/themes/ folder. Restart Formvine to expose the theme in the Form Designer.

When a user posts a properly configured Formvine URL in a TIBCO tibbr® post, a tibbr specific style is applied.

Theme customization is not carried forward on upgrade. See About the customization process, page 15 for more information.


Branding Formvine forms with a visual style | 26

To apply a custom theme to an individual project, create your own style, but don’t add it to the themes.js file. Post the CSS files to a public location. Then, open your form in the Form Designer and add the URL to your CSS files in the Appearance dialog box.


Customizing voice and style for Formvine communications | 27

Chapter 3 Customizing voice and style for Formvine communications

You can customize the voice and style of your TIBCO Formvine® communications to suit your audience. This chapter explains why you might want to customize Formvine® communications and tells you how to implement the customizations.

Topics

• Why customize communications?, page 28

• Customizing the launch page, page 29

• Customizing the confirmation page, page 33

• Customizing the thank you page, page 35


Why customize communications? | 28

Why customize communications?

The voice used in communications can set the tone for how people interact with Formvine. For example, the Formvine launch page, which is viewed only by project owners and other users of the Formvine Project Tools, is a first introduction to Formvine. You can set the tone to match the tone of other enterprise communications or you can create the tone specifically for Formvine. You can also add links to legal or privacy policies at the bottom of each page.

The confirmation and thank you pages, on the other hand, are viewed exclusively by form submitters. You can set the default text displayed on these pages. If form submitters are outside your enterprise, you can use these pages to extend your messaging outside your enterprise. If form submitters are internal, you can set up these pages to reflect your intranet messaging.


Customizing the launch page | 29

Customizing the launch page

The launch page provides a quick and easy way to start Formvine. It also provides a friendly introduction to the application and offers links to the Quick Start and the Resource Center. It might be the first introduction to Formvine for users in your enterprise. The page can provide links to Privacy Policies or to Terms and Conditions statements that might be required by your Legal department.

The launch page is optional; you can also provide your users with the Formvine URL. The Formvine.com implementation, for example, does not use this page.

To access the launch page, point your browser to:

formvine_url/fv/launch

For example, if the formvine_url is

http://formvine.example.com/fv

then the launch page is

http://formvine.example.com/fv/launch

The launch page can be viewed as a standard HTML web page or can be embedded in an iFrame in your corporate Intranet. The following figure shows the generic implementation of the launch page.



Figure 11 Launch page - generic implementation



You can replace this page or rearrange and supplement the elements on the page. The following figure illustrates how the page was customized for the TIBCO reference implementation. Note that we updated the brand to the Formvine at TIBCO logo. In addition, we updated the text specifically for TIBCO employees and rearranged it for readability. We added a link to the Formvine administrator and added a caveat to the Security section, stating that Formvine is available for business purposes only.

Figure 12 Launch page - reference implementation



Questions to ask about the Formvine launch page

Here’s what you need to consider to get your launch page up and running:

• Do you want to use the launch page? If so, do you want to redesign it?

• Does your Legal department have a privacy policy or terms and conditions statement to add to the page?

• Will your launch page be embedded in another page?

• Do you want to update the text to reinforce your company messaging?

• Do you want to add your company logo to this page?

Recommendations

We recommend the following customizations for the launch page:

• Add your company logo to the top of this page.

• Add a support link.

• Update the text in each section with information specific to your enterprise.

How to customize the launch pageStop the server before implementing these changes. When you’re done, review the new page in different browsers. Launch page customization is not carried forward on upgrade. See About the customization process, page 15 for details.

Customize the launch page

1. Navigate to the following folder in your Formvine installation:TIBCO_FV_HOME/WebContent/WEB-INF/htmltemplates/

2. Make a backup copy of the file: launch.jsp

3. Change the file as needed for your new visual design.

— When modifying this page, keep the CSS and JavaScript references at the top of the file intact, so that you can keep a consistent look and feel between the launch page and the Formvine Form Designer. These lines begin with the code: <link type=... and <script type=...

4. Reload Formvine and open the launch page URL. (Your browser might require that you clear the cache to see updates.)

If you’re updating the visual design, you might have to experiment with the layout. You can embed the launch page file in an iFrame or place the launch page URL in your corporate portal. You can also provide your project owners with a link to the launch page.


Customizing the confirmation page | 33

Customizing the confirmation page

Project owners can choose to display a confirmation page for any form after a submitter clicks Submit. The confirmation page contains default text that you can customize. You can edit the text and tone so that it’s targeted for form submitters, whether they are customers, the public, or employees.

Changes to this page are system-wide, and are displayed on all confirmation pages seen by all form submitters. Project owners choose whether to include a confirmation page on a project-by-project basis. Because the page is optional, make sure that your customizations don't include critical information. A project owner who decides to use the confirmation for a project can also include a personalized project-specific message.

The confirmation page displays the data about to be submitted to the form and, by default, gives the submitter an opportunity to go back and change answers. The confirmation page uses the same visual style as the form.

The default text is: “You are almost done! Please review the information below to make sure it's what you want. Click Submit if it's correct. Click Back if you need to make changes.”

The following figure shows the confirmation page for the generic implementation. In this example, the standard blue visual style is applied.

Figure 13 Confirmation page - generic implementation


Customizing the confirmation page | 34

Here's an example of the confirmation page for the Formvine at TIBCO implementation. The standard blue visual style has been customized with a TIBCO logo at the top and bottom of the form.

Figure 14 Confirmation page - reference implementation

Configure the confirmation page

File to edit: TIBCO_FV_HOME/WebContent/WEB-INF/classes /Runtime.properties

After editing, save the file and restart the server. This customization is not carried forward on upgrade. See About the customization process, page 15 for details.

Property Configuration information

Title Default page title. Change default value (in bold) as needed.confirm_title = You are almost done!

Text Default page text. Change default value (in bold) as needed.confirm_text = Review the information below to make sure it's what you want. Click Submit if it's correct. Click Back if you need to make changes.


Customizing the thank you page | 35

Customizing the thank you page

A thank you page is automatically displayed for every project after Submit is clicked on a form (or on the confirmation page, if used). If form submitters are internal to your enterprise, you can edit the default text to reflect the voice and style for your company. If submitters are external, you can extend your company messaging out to those users, whether they are customers, the public, or employees.

The default text can't be changed on a per-project basis, but the project owner can add additional personalized text. Because the thank you page is always displayed, you can add text you want everyone to see, such as your company mission statement or tag line. Your changes to this page are system-wide and will be seen by all form submitters, so consider your changes carefully.

The thank you page uses the same visual style as the form. Both the generic and reference implementations display the Formvine brand. For the Formvine at TIBCO implementation, we also display the TIBCO logo to give confidence to submitters who may be outside of our enterprise.

The default text is: "Thank you. Your form has been submitted." Here's an example of the thank you page for the generic implementation. The Formvine link at the bottom of the page opens the public Formvine site at Formvine.com.

Figure 15 Thank you page - generic implementation


Customizing the thank you page | 36

Here's an example of the thank you page for the Formvine at TIBCO implementation, with the TIBCO company logo at the top and bottom of the form.

Figure 16 Thank you page - reference implementation

Configure the thank you page

File to edit: TIBCO_FV_HOME/WebContent/WEB-INF/classes /Runtime.properties

After editing, save the file and restart the server. This customization is not carried forward on upgrade. See About the customization process, page 15 for details.


Title Default page title. Change default value (in bold) as needed.thankyou_title = Thank you.

Text Default page text. Change default value (in bold) as needed.thankyou_subtitle = Your form has been submitted.


| 37

Chapter 4 Advanced configuration options for the Formvine application

This chapter describes the application properties that you can set to fine-tune your TIBCO Formvine® implementation. Application properties control how Formvine® runs and behaves. Some of the properties are visible to users, while others are not.

As with other options, we just want to let you know these options exist. We’re not suggesting that you change anything.

Topics

• About the advanced options, page 38

• Usage limit properties, page 39

• User registration properties, page 41

• User session properties, page 43

• Security properties, page 45

• Challenge-response properties, page 48

• Space creation properties, page 50

• Audit log display property, page 51

• Additional properties, page 53

Some of the most common application properties are configurable with the Admin Tool. See the TIBCO Formvine Administration Guide for more information.


About the advanced options | 38

About the advanced options

Some advanced options are available to fine-tune your Formvine configuration. The default settings are suitable for most Formvine installations, but if you need to change the settings, the descriptions in the section can provide guidance.

To set or reconfigure properties after Formvine is running, you must stop and restart the Formvine server for application configuration changes to take effect. As a best practice, we recommend that you make a backup copy of each file before editing. Thoroughly test your changes before rolling them out to your enterprise.

If you do make changes and you are running Formvine on an application server other than the embedded Tomcat, make the corresponding changes to the WAR file and redeploy.

Some of these advanced settings are carried forward on migration; others are not. Changes that are not carried forward are indicated in the instructions.


Usage limit properties | 39

Usage limit properties

Usage limits include the number of projects allowed per account, the number of fields allowed per form, and the maximum length allowed for Single Line Text fields. The defaults are sufficient for many environments, but may require modification if you have disk space constraints. Check with your database administrator for recommendations.

Set usage limit properties

File to edit: TIBCO_FV_HOME/config/features.properties

After editing, save the file and restart the server.


Maximum projects per user account, disabling new projects

The maximum number of projects per account. Change default value (in bold) if needed.

fv.limits.projectquota = -1

Default value allows an unlimited number of projects per user account. Value of 0 disables new accounts. Integers only. If limit is reached, an existing project must deleted in order to create a new one.This property can also be set using the Admin Tool. See “Using the Admin Tool” in the TIBCO Formvine Administration Guide.

Maximum fields allowed per form

The maximum number of fields allowed on a submitter form. Change default value (in bold) if needed.

fv.limits.maxfieldsperform = 200

Default value allows 200 fields on a form. If limit is reached, an existing field must be deleted in order to add a new one. Set to a value of -1 to allow an unlimited number of fields per form.Notes:

• This setting determines the number of columns in the Data view.

• Layout fields, such as headings and page breaks, do not count toward the limit.

• Each individual field that is part of a compound field (such as street address line in an address field) does count towards the total.


Usage limit properties | 40

Size of Single Line Text field

The maximum number of characters that can be submitted to a Single Line Text field. Change default value (in bold) if needed.

fv.limits.textboxfieldmaxsize = 255

Default value allows a Single Line Text field to accept up to 255 characters (this is also the maximum). Value must be between 100 and 255. Notes:

• If you change the maximum number of characters allowed for the Single Line Text field, you can also add hint text to the prefab.xml file for this control. No hint text is included by default.

• If you add hint text that specifies the number of characters allowed, then later change the property, the hint text for Single Line Text fields in online forms will be incorrect.

• See Chapter 5, Customizing controls, page 58 for more information on the prefab.xml file.

• Changes made to the prefab.xml file are not carried forward on upgrade. See About the customization process, page 15 for details.



User registration properties | 41

User registration properties

User registration properties control user registration and sign in. These properties apply only if you are using a Formvine directory implementation where users self-register. Check with your corporate systems engineer for recommendations. For click-through agreements, you also need input from your legal department and a copywriter.

Set user registration properties




Formvine directory registration activation email enabled

The setting for the registration activation email (Formvine directory implementations only). Change the default value (in bold) if needed.

fv.user.registrationmailconfirmation = false

When true, new registrants are required to confirm their registration with an activation link in an auto-generated registration email. When false, registrants can sign in to Formvine after completing the registration form.Applicable only when fv.user.usergroupsource equals _local.

Password reset timeout (in hours)

The number of hours the password reset link (sent out in the reset password email) is active. Change the default value (in bold) if needed.

fv.user.passwordresetexpiryhours = 24

The user must activate this link within the specified time period; otherwise the link expires and the user must reset it again.Applicable only when fv.user.usergroupsource equals _local.


User registration properties | 42

Create click-through agreements

You can provide one or more click-through agreements on the registration page, for example, for a Terms of Use or Privacy policy. The default setting does not display click-throughs. Click-through checkboxes are created as required fields.

1. Navigate to: TIBCO_FV_HOME/WebContent/WEB-INF/classes/

2. Open Strings.properties in a text editor

— Changes made to the Strings.properties file are not carried forward when you upgrade. You need to reimplement these changes. See About the customization process, page 15 for details.

— If you are running Formvine on an application server other than the embedded Tomcat, make the corresponding changes to the WAR file and redeploy.

3. To add registration agreements to the registration page, locate the register.agreement.0 property. By default this property is commented out. Uncomment it and add the text for your agreement.

— If multiple click-through agreements are required, add additional agreements by duplicating the register.agreement.0 property. Increment the integer value and update the text.

4. Place the linked-to HTML pages in a public location.

5. Save the file.

User password hashing The hash algorithm for the user password. This property is used with the Formvine directory option to encrypt user passwords in the database. Change the default value (in bold) if needed.

fv.user.passwordhashingalgorithm = SHA-256

You can substitute another SHA algorithm if needed, but you must do this at installation, before users start registering. If you change it later, users will have to reset their passwords. Applicable only when fv.user.usergroupsource equals _local.User passwords are stored as hash values in the database. No one has access to the original passwords, not even the Formvine administrator. Only users can reset their passwords.



User session properties | 43

User session properties

Session properties determine how Formvine manages an end-user's session in Formvine when the user signs in. The defaults are sufficient for most environments. Check with your corporate systems engineer for recommendations.

Set user session properties




Number of days to remember sign-in cookie

The number of days the system remembers the sign-in cookie (the timeout period for the Remember me checkbox on the Sign in page is based on this value). Change the default value (in bold) if needed.

fv.session.rememberlogindays = 14

With a sign-in cookie, users are not required to sign in each time they access Formvine through a browser. Once the sign-in cookie expires, the user is required to sign in again. This is an absolute timeout since the last sign in. Even if the user closes the browser and later opens Formvine, he or she is still signed in. (The user session may expire few times during this period, based on the fv.session.maxinactivemins setting, but it will be recreated and transparent to the user.)

Domain to use as sign-in cookie

The domain for the sign-in cookie.

fv.session.logincookiedomain =

If this value is not specified, the cookie is set for the Formvine server. This setting is useful if Formvine can be accessed through various URLs, as in an organization that has multiple sub-domains.Example: If you are accessing Formvine using http://formvine.na.example.com:9380/fv and http://formvine.apac.example.com:9380/fv, set this domain to example.com. Then a user accessing Formvine through any of these URLs will use the same sign-in cookie and does not need to sign in when changing from one URL to the other.


User session properties | 44

Hash algorithm for sign-in cookie checksum

The hashing algorithm for calculating the sign-in cookie. Change the default value (in bold) if needed.

fv.session.cookiechecksumhashalgorithm = SHA-512

The algorithm works when encrypting the sign-in cookie checksum.

Maximum number of inactive minutes after which the Formvine HTTP session expires

The default value for the maximum number of inactive minutes after which the Formvine HTTP session expires. Change the default value (in bold) if needed.

fv.session.maxinactivemins = 120

After the specified minutes of inactivity, the session is released from memory. Users must sign in again when revisiting Formvine if the Remember me checkbox was not checked. The HTTP session at the server will time out based on this value if the Remember me checkbox is not selected on the Sign in page. This is an idle timeout: it is not calculated from the time of sign in, but is calculated from the time the user stopped interacting with Formvine. After the session times out, the user will be required to sign in again when he or she starts interacting with Formvine.If Formvine is used with a web server, then this setting is normally set by the administrator for the web server. In this case, you can use this parameter to assign a lower value, if needed. To ignore this setting and use the web server settings, set the value to 0.

Expiration time for user session cache

The expiration time, in minutes, for the user session cache that includes the signed-in user’s details, status, and group memberships. Change the default value (in bold) if needed.

fv.session.cacheexpirymins = 60

The cache is stored in the HTTP session and is periodically expired to avoid stale user details.After the specified number of minutes, the signed-in user information cached in the HTTP session expires. Even though this helps in maintaining up-to-date group membership for the signed-in user, in some cases the membership may still be stale. This may happen if groups are organized in the corporate LDAP in a hierarchical manner and if this hierarchy itself changes. Note that the group hierarchy may be reloaded at a much longer time interval based on the setting of fv.ldap.groupcachereloadmins property (in the usergroupsource.properties file).



Security properties | 45

Security properties

This section describes the available security settings. Your corporate systems engineer can make recommendations for these settings.

Set security properties




Email domain allowed list

A white space-delimited list of domains allowed for user registration. Add a list of accepted domains, separated by spaces.

fv.security.emaildomainwhitelist =

Formvine will only accept registration requests from listed domains. Leave empty if not used. This list takes precedence over the reject list. Do not add domains to both lists. We recommend using one list, but not both.Valid only when fv.user.usergroupsource equals _local.This property can also be set using the Admin Tool. See the chapter called “Using the Admin Tool” in the TIBCO Formvine Administration Guide.

Email domain deny list A white space-delimited list of domains denied for user registration. Add a list of denied domains, separated by spaces.

fv.security.emaildomainblacklist =

Formvine will reject registration requests from listed domains. Leave empty if not used. Do not add domains to both lists. We recommend using one list, but not both.Valid only when fv.user.usergroupsource equals _local.



Set the encyrption key

File to edit: TIBCO_FV_HOME/config/keystore.properties

After editing, save the file and restart the server. •

Re-encrypt passwords

After you change the encryption key, you need to re-encrypt passwords. Follow the instructions below for the passwords used in your environment. Save each file after you edit it.

1. To re-encrypt database connection passwords, open TIBCO_FV_HOME/config/features.properties/db.properties.

— Set or reset the javax.persistence.jdbc.password property to clear text. (Make sure you choose the database your enterprise is using for

Keystore file location The location of the keystore.properties file that contains encryption keys. Change the default value (in bold) if needed.

fv.keystorefile = ${TIBCO_FV_HOME}/config/keystore.properties

Encryption keys are used by Formvine for encrypting passwords in various properties files, the log.lcf file, and for encrypting the sign-in cookie with a checksum. By default, the file is stored in the Formvine home directory. If you move the file to a more secure area in your enterprise network, update this property.



Encryption key The encryption key used for encryption and decryption of items, such as passwords in various properties files and the log.lcf file. Change the default value (in bold). fv.security.encryptionkey = 9432251718

We recommend that you use your own key. It should be a very large number. These passwords are used for accessing your database, LDAP server, SMTP server, tibbr server, and JMS server. The key is also used as a layer of security by encrypting the sign-in cookie with a checksum.When you change this key, you need to provide a clear text password in properties files and log.lcf and restart the Formvine server. On server start, the passwords are encrypted using the new key.



Formvine user authentication: the Formvine directory version uses the embedded Derby database.)

2. To re-encrypt SMTP server connection passwords, open TIBCO_FV_HOME/config/email.properties.

— Set or reset the fv.email.password property to clear text.

3. To re-encrypt LDAP and tibbr connection passwords for user and group access, open TIBCO_FV_HOME/config/usergroupsource.properties.

— Set or reset the fv.ldap.bindpwd property to clear text.

— Set or reset the fv.tibbr.password property to clear text.

4. To re-encrypt JMS server connection passwords, open TIBCO_FV_HOME/config/jms.properties.

— Set or reset the fv.jmsendpoint.<endpointID>.password property to clear text.

5. To re-encrypt logging appender passwords, open TIBCO_FV_HOME/config/log.lcf.

— Set or reset the log4j.appender.<appenderID>.Password property to clear text.

6. To re-encrypt the tibbr server connection password, open TIBCO_FV_HOME/config/tibbr.properties.

— Set or reset the fv.tibbrendpoint.<endpointID>.password properties to clear text.

7. Save the files. After server restart, the passwords are re-encrypted. Once encrypted, passwords are prefixed with: enc://


Challenge-response properties | 48

Challenge-response properties

Challenge-response, also known as CAPTCHA, is available to verify that a real person, and not an automated process, has provided the information for the purposes of user registration and project submission. Check with your corporate systems engineer for recommendations on CAPTCHA settings.

Set challenge-response for submitters and registration




CAPTCHA provider configuration

The CAPTCHA provider. Change the default value (in bold) if needed.

fv.captcha.provider = fv

By default, the CAPTCHA provider is used. To use the Google reCAPTCHA service, set this property to: recaptcha Refer to the steps in the Change the default CAPTCHA provider to reCAPTCHA, page 49 section.

CAPTCHA enabled as a setting for submitters filling out anonymous forms

The setting to enable CAPTCHA for use by project owners. Change the default value (in bold) if needed.

fv.captcha.challengeenabled = true

When set to true, allows project owners to dipslay the challenge-response property on anonymous forms. When false, the challenge-response is not available as an option for anonymous forms.

Display CAPTCHA on Formvine directory registration screen

The setting to enable CAPTCHA on the registration screen. Change the default value (in bold) if needed. fv.captcha.registration = true

When set to true, a challenge-response is displayed on the registration screen. When false, a user can register without having to complete a challenge-response. Valid only when fv.user.usergroupsource equals _local.Note that this property can also be set using the Admin Tool. See the TIBCO Formvine Administration Guide.


Challenge-response properties | 49

Change the default CAPTCHA provider to reCAPTCHA

1. Create a reCAPTCHA account and obtain a public/private key pair.

— Go to https://www.google.com/recaptcha/admin/create and follow the steps to obtain the public/private key pair.

2. Open the TIBCO_FV_HOME/config/recaptcha.properties file.

— Add the public_key and private_key setting that you received after creating a reCAPTCHA account.

— Save the file.

3. Open the TIBCO_FV_HOME/config/features.properties file.

— Change the value of fv.captcha.provider to recaptcha.

— Save the file.


Space creation properties | 50

Space creation properties

This property controls the ability to create spaces and projects using the Formvine Project Tools UI.

Set space creation property




Allow space creation Change the value in bold if needed.

fv.projecttools.spacecreationtool = true


Audit log display property | 51

Audit log display property

The audit log display property allows audit logs to be stored in the Formvine database and makes the audit log available in the Data view. If the property is off, audit information is only stored in the TIBCO_FV_HOME/logs/audit.log file and the audit log is not visible from the Data view. When it is on (the default setting), a green highlight in the Data view indicates the original data; a yellow highlight indicates updated data, as illustrated in the following figure.

Figure 17 Audit log display for record

Even though the audit log displays as a record history in the Data view, an audit log is also stored for all data sensitive and security sensitive operations in Formvine.

Check with your database administrator for recommendations.

Set the audit log display



If the audit log display property is changed multiple times, some audit history may be lost.


Audit log display property | 52


Audit log The location of the audit file. Change the default value (in bold) if needed. fv.audit.db.logging = true

The default value of true stores audit logs in the Formvine database and makes the audit log available in the Data view. Set to false if necessary to store audit information in the TIBCO_FV_HOME/logs/audit.log file and hide the audit log in the Data view.You can also set the audit log display property using the Admin Tool. See the chapter called “Using the Admin Tool” in the TIBCO Formvine Administration Guide.


Additional properties | 53

Additional properties

Additional properties that impact the application are listed below. The default properties for most of these settings will be sufficient.

Date and time formats

Files to edit:

TIBCO_FV_HOME/WebContent/WEB-INF/classes/Strings.propertiesTIBCO_FV_HOME/WebContent/WEB-INF/classes/Runtime.properties

After editing, save the files and restart the server. These customizations are not carried forward on upgrade. See About the customization process, page 15 for details.

If you make changes and you are running Formvine on an application server other than the embedded Tomcat, make the corresponding changes to the WAR file and redeploy.


Date and time formatTIBCO_FV_HOME/WebContent/WEB-INF/classes/Strings.properties

Date format for the Data view, Task view, Data export, and Admin Report

The date format. Change the default value (in bold) if needed.

fmt.date = M/d/yyyySupported formats: M/d/yyyy, d/M/yyyy, yyyy/M/d or yyyy/d/M

Time format for the Data view, Task view, Data export, and Admin Report

The time format. Change the default value (in bold) if needed.

fmt.time = <h:mm a>

Supported formats:

• Change the lowercase "h" to an uppercase "H" for a 24-hour clock.

• Remove the "a" to hide the AM/PM dropdown.

Date and time format for the Data view, Task view, Data export, and Admin Report

The date and time format. Change the default value (in bold) if needed.

fmt.datetime = <M/d/yyyy h:mm a>

Supported formats:

• Change the lowercase "h" to an uppercase "H" for a 24-hour clock.

• Remove the "a" to hide the AM/PM dropdown.



Time format in forms that submitters fill outTIBCO_FV_HOME/WebContent/WEB-INF/classes/Runtime.properties

Time format in forms The time format for online forms. Change the default values (in bold) if needed.

• 24 Hour clock

tp_24hour = false

Set to true to display a 24 hour clock.

• Display text for hours field

tp_hour_title = Hour (12-hour clock)

• Display text for minutes field

tp_minute_title = Minute

• Display text for AM/PM indicator

tp_ampm_title = AM/PM

• Separator between hours and minutes

tp_sep_hm = :

• Separator between minutes and AM/PM

tp_sep_ma =




Google analytics

File to edit:TIBCO_FV_HOME/WebContent/WEB-INF/classes/Strings.properties

After editing, save the files and restart the server. These customizations are not carried forward on upgrade. See About the customization process, page 15 for details.

If you make changes and you are running Formvine on an application server other than the embedded Tomcat, make the corresponding changes to the WAR file and redeploy.


Google analytics trackingTIBCO_FV_HOME/WebContent/WEB-INF/classes/Strings.properties

Google analytics tracking for Form Designer and Data view

Google analytics tracking configuration for Project Tools. Enter your Google analytics account ID.

google-analyics.account.authoring =

To configure Google analytics tracking, you must first set up a Google analytics account. See the Google Analytics website (http://www.google.com/analytics/) for more information.

Google analytics tracking for forms

Google analytics tracking configuration for online forms. Enter your Google analytics account ID.

google-analyics.account.runtime =



File system configuration parameters

File system configuration parameters set up access to the file system and are used to store and retrieve project files and attachments. The default settings keep the file system on the Formvine server. These locations can be changed to store data on a network file server. The network file server can be a mirrored disk or can be independently configured for regular backups.

If you have a load-balanced setup of Formvine (using WAR deployed on your corporate servlet container), that involves mutliple instances, make sure that the file system locations on each of the Formvine instances point to a common network file server.

File to edit:TIBCO_FV_HOME/config/filesystem.properties


Property Property

Location of Formvine project files

The network file server location where Formvine project files created by project owners are stored. Change the default value (in bold) if needed.

fv.filesystem.basedir = ${TIBCO_FV_HOME}/files

Location of attachments

The network file server location where attachments uploaded by form submitters are stored. Change the default value (in bold) if needed.

fv.filesystem.basedir.datafiles = ${TIBCO_FV_HOME}/files

Location of temporary files

The network file server location where temporary files uploaded by form submitters are stored. Temporary files are created while uploading the attachments when submitters save or submit their records.Change the default value (in bold) if needed.

fv.filesystem.tempdir = ${TIBCO_FV_HOME}/tempfiles



External resources

File to edit:TIBCO_FV_HOME/config/features.properties


Property Property

Location of external libraries

The location of vendor-specific third-party libraries that need to made available to the Formvine application, such as a JDBC library or the JMS provider library. Change the default value (in bold) if needed.

fv.resources.external.lib = ${TIBCO_FV_HOME}/external/lib


Customizing controls | 58

Chapter 5 Customizing controls

TIBCO Formvine® uses controls, also known as fields, to collect data. Many of the controls included with Formvine® can be modified and new controls can be added. We recommend making changes only if essential. XML proficiency is required to modify or add controls.

Since the presentation of—and XML behind—each control affects the data collected, any modification or addition should be approached with care and forethought. Requirements should be well understood, with design carefully executed and copy thoroughly reviewed and edited. Projects will be more successful if the controls offer sufficient instruction and error messages for submitters to successfully enter data.

Changes made to controls are not carried forward on upgrade. See About the customization process, page 15 for more information.

Topics

• Formvine controls, page 59

• What is customizable?, page 61

• Simple controls, page 63

• Validated controls, page 64

• File Upload control, page 66

• Compound controls, page 69


Formvine controls | 59

Formvine controls

The term control refers to fields and related elements of a form. Formvine contains a variety of controls from simple controls, like a text field, to more complex multi-column, multi-row checkbox and radio button fields. The default controls will cover most uses cases. The Formvine controls are listed below.

Table 2 Formvine controls

Control Results collected by control

Single Line Text By default, up to 255 characters of text. (Configurable)

Multi-Line Text Multiple lines of text.

Formatted Text Text augmented with HTML tags.

Single Checkbox On/Off, Yes/No, True/False choices.

Date Date, selected from a date picker.

Time Time, with hours and minutes, as a 12-hour or 24-hour clock.

Numeric Numbers, such as 1, -500 or 1.55.

Slider A single number from a range.

Phone Digits 0-9 and the symbols:+ - ( )

Phone - US A 10-digit US phone number.

Email Formatted email address.

URL Formatted web address.

Short name First name field, last name field.

Long name Title dropdown with Mr, Mrs, and Ms options. First name field, middle initial field, last name field.


Formvine controls | 60

Address International address with two street address fields, City field, State/Province/Region field, Zip/Postal Code field, Country field.

Address - US Standard US address with two street address fields, City field, State dropdown, Zip field.

Zip+4 Zip code field for 5 digits, additional field for 4 digits. (Maps to one column in the Data view.)

Name and Email First name field, last name field, email address field. (Maps to one column in the Data view.)

File Upload A file. Default file types: jpg, png, gif

Auto-Fill First name, last name, or email address. Additional attributes can be implemented. Valid only on authorized forms.

User Lookup Email address.

Checkbox Group One or more responses from a list of options.

Dropdown List One response from a list of options.

Radio Button Group One response from a list of options.

High-Medium-Low One response from a pre-configured list of options.

Likert Scale One response from a pre-configured list of options.

Multi-Row Check One or more responses per row.

Multi-Row Radio One response per row.

Table 2 Formvine controls (Cont’d)

Control Results collected by control


What is customizable? | 61

What is customizable?

You can customize controls, but we recommend making changes only if essential. It is straightforward to add new controls, delete controls or modify controls slightly (change a field label or add default instructional text). More significant changes, however, may cause unexpected behavior.

You can modify controls that fall into the following categories:

• Simple controls, page 63

• Validated controls, page 64

• File Upload control, page 66

• Compound controls, page 69

Controls are defined in: TIBCO_FV_HOME/WebContent/versionedfiles/ JSXAPPS/dashboard/editor/xml/prefab.xml

You need to be proficient with XML to customize the prefab.xml file. Shut down the Formvine server before editing this file.

Ask these types of questions as you consider modifying or adding controls:

• What kind of files do you want your form submitters to be able to upload? What is the maximum file size?

• Do you need to collect data not provided for in the existing compound controls? If so:

— Do any of the existing compound controls (address, phone, long name) have some of the details that you want to collect, for example, state or country?

— What do you want to call your new or modified control?

— What simple controls does it consist of?

— What parts of it are required if the project owner marks the field as required?

— What validations does the control need?

• Do you need to remove any of the default controls?

A control is copied into each form as it is dragged onto the form canvas. Therefore, changes to prefab.xml do not affect forms that have already been created and deployed.


What is customizable? | 62

Adding and removing controlsYou can add controls to or remove controls from the Form Designer. For example, you can add a control to collect a specifically formatted phone number or address. To add a control, think about your use case and answer the following questions:

• How does your use case differ from the available controls?

• Can you modify an existing control or copy it as a starting point?

• What do you need a new control to do?

Designing a control from the ground up is out of the scope of this documentation set; however, you can use existing controls as starting points and experiment. You can also remove one or more controls from the Form Designer. This does not impact existing projects. However, this could impact future projects being imported with the Data Import process.

If a Formvine user assigns a column of data in the Data wizard to a control type that you have deleted as not applicable for your Formvine implementation, that control won’t get removed from the Data wizard. The end result is that the associated data won’t be imported. For example, if you remove the Multi-Line Text control from your Formvine implementation, and a project owner assigns a column of data to that type of control in Step 2 of the Data Import wizard, the data is not imported and no warning is issued

The controls used by data import are:

• Single Line Text

• Multi-Line Text

• Single Checkbox

• Checkbox Group

• Dropdown List

• Radio Button Group

• Numeric

• Date

• Time

• Email

• URL

• US Phone

• Zip Code


Simple controls | 63

Simple controls

Simple controls are single field controls, like a text box, a checkbox, a dropdown list or a set of radio buttons. The simple controls included with Formvine are sufficient for most use cases. It is possible to modify the default text or field label for these controls. The Formvine simple controls include:

• Single Line Text

• Multi-Line Text

• Formatted Text

• Single Checkbox

• Date

• Time

• Dropdown List

• Checkbox Group

• Radio Button Group

Any simple control can be used as a building block for a compound control.


Validated controls | 64

Validated controls

Validated controls are a modification of a simple control. Formvine checks the data against a pre-set expression to ensure the data is entered as expected. A numeric control, for example, is simply a Single Line Text control that only accepts a combination of digits.

The validated controls below are all variations on the Single Line Text control. Validated controls include:

• Numeric

• Phone

• Phone - US

• Email

• URL

Changing validation for a controlThe following example illustrates how we modified the US Phone control to validate for an Australian phone number.

The following figure shows the completed Australian Phone control.

Figure 18 Australian Phone control

Here’s the existing code in prefab.xml for the US Phone control:

<item id="phone" text="Phone" thumbnail="Us_Phone.png" icon="phone_24x24.png"

description="Accepts a phone number. The format is validated on entry.">

<field pf_prefab="true" type="textbox" title="Phone Number" tip="Accepts 0-9 and the symbols + - ( )"

inputformat="{pattern:{value:"^[ 0-9\$\$\\+\\-]*$",error:"Phone number not valid. This field only accepts the digits 0-9 or the symbols + - ( )."}}"/>

</item>


Validated controls | 65

And here is the code for the Australian Phone control:

<item id="auphone" text="AU Phone" thumbnail="AU_Phone.png" icon="phone_24x24.png"

description="Allows the submitter to type a 10 digit Australian phone number. The phone number format is validated on entry.">

<field pf_prefab="true" type="textbox" title="AU Phone Number" tip="For example, 00-5555-1212 or 0455-555-555"

inputformat="{pattern:{value:"^(\$0\\d\$\\s?|0\\d(?:-|\\s)?\\d{4}(?:-|\\s)?\\d{4})|(04\\d{2}(?:-|\\s)?\\d{3}(?:-|\\s)?\\d{3})$",error:"Phone number not valid. Enter a 10-digit number as 0n-nnnn-nnnn or 04nn-nnn-nnn."}}"/>

</item>

We changed the following elements:

• id

• text

• thumbnail

• description

• title

• tip

• inputformat

Note the differences in the regular expressions in the inputformat element in each of these controls. The US Phone control validates US phone numbers and the Australian Phone control validates for Australian phone numbers.


File Upload control | 66

File Upload control

You can expand the use case of the File Upload control, turning it into a control that accepts any type of file. The default control is set to accept only image files.

If you change the types of files accepted by this control, also update the following attributes of the control:

• Help text displayed in the hover

• Instructional text in the control

You can also adjust the maximum file size allowed for attachments. The default size is 10MB.

The File Upload control can be customized with the Admin Tool. See the chapter called “Using the Admin Tool” in the TIBCO Formvine Administration Guide.

Customizing the File Upload controlBefore making any changes, stop the Formvine server.

Customize the types of files that can be uploaded

Any changes to settings.properties file are carried forward on upgrade.

1. Open TIBCO_FV_HOME/config/settings.properties file.

2. Set the fv.upload.allowed-mime property by editing the list of allowed file types. jpg, jpeg, gif, png files are allowed by default.

— Enter a list of comma-separated file extensions (no “dot” separator) for the file types you want to upload:doc,docx,ppt,pptx,xls,xlsx,pdf,zip,htm,html,txt,bmp,mov,mp3Though not recommended, you can add executable files to the list.

3. Save your changes and reload Formvine. (Your browser might require that you clear the cache.)

Note that you can also adjust the file types that can be uploaded with the Admin Tool. See “Using the Admin Tool” in the TIBCO Formvine Administration Guide.

Consult your database administrator for security and space considerations.



Adjust the maximum file size

Any changes to filesystem.properties file are carried forward on upgrade.

1. Open TIBCO_FV_HOME/config/filesystem.properties file.

2. Set the following fv.filesystem.uploadFileSize property to the default size required for your use case.

3. Save your changes and restart Formvine. (Your browser might require that you clear the cache before reloading Formvine.)

Note that you can also adjust the default maximum file size using the Admin Tool. See “Using the Admin Tool” in the TIBCO Formvine Administration Guide.

Customize the help text and default instructional text

Any changes to prefab.xml file are not carried forward on upgrade.

1. Open the prefab.xml file, located in the TIBCO_FV_HOME/WebContent/ versionedfiles/JSXAPPS/dashboard/editor/xml folder.

2. Locate the File Upload control record. The record starts with: <item id="upload"...

3. To change the help text and default instructional text, change the description and subtitle attributes for the control. See the table below for details on how the control is defined.

4. Save your changes and reload Formvine. (Your browser might require that you clear the cache.)

The record for the File Upload control in prefab.xml is illustrated below:

<item id="upload" description="Allows the submitter to include an uploaded file, such as a photograph or clip art image, when submitting the form." text="File Upload" icon="imageUpload_24x24.png" thumbnail="Upload.png">

<field title="Click to edit the label" type="upload" datatype="file" subtitle="Supported file types: png, jpg, gif"/>

</item>

Changes to prefab.xml are not carried forward on upgrade. You must reimplement these changes.



Attributes for the File Upload control are listed in the following table.

Element Description

id Required. Must be unique in prefab.xml.Default value: upload

description Required. The description displayed on hover.

text Required. The name of the control, displayed in the field list. Default set to File Upload. Change as required.

icon Required. The 24x24 icon that is displayed in the Form Designer field list. The path is relative to:

WebContent/versionedfiles/JSXAPPS/dashboard/editor/images

thumbnail Optional. The preview image displayed in the spyglass, shown when hovering over the item in the Form Designer field list. The image must be 240 pixels wide. The path is relative to:

WebContent/versionedfiles/JSXAPPS/dashboard/editor/images/thumbnails

title Required. The control label displayed when the image is dropped onto the canvas. Default is set to:Click to edit the label

type Required. Do not change the default setting: upload

datatype Required. Do not change the default setting: file

subtitle Required. The instructional text displayed for the field. Add extensions for the types of files you are supporting, for example, pdf or xls.

mimes Optional. The type(s) of allowed files. If used, overrides the settings in settings.properties for this control.


Compound controls | 69

Compound controls

Compound controls are made up of simple controls that are added to the Form Designer as a single object. These controls collect multiple pieces of data. For example, the Address control consists of several text boxes and a dropdown menu in a custom layout.

Except for the Zip+4 control and the Name and Email control, the data collected from submitters are shown as one column per subfield of a compound control in the Data view.

Your use case might require new or modified compound controls. A compound control is a special case of a control. It includes multiple field elements. Examples of compound controls are US Address, Short Name, or Long Name.

Compound controls:

• Can be composed of any simple controls such as text box, checkbox, or dropdown list

• Can be laid out in a table-like structure in one or more rows

• Are dragged around in the Form Designer as a single control

• Can be defined as required or not

• Map to one-column per subfield in the Data view and underlying database (depending on the setting of the type property in the control definition)

The default Formvine compound controls are:

• Short Name

• Long Name

• Address

• Address - US

• Zip+4

• Name and Email



Anatomy of a compound controlBefore you can modify an existing compound control or create a new one, you need to understand how they are put together. The diagram below illustrates how a compound control is assembled.

Figure 19 Anatomy of a compound control

As the illustration shows, a compound control consists of a number of simple controls that have been assembled into a single control. You need to think about how you want your new control to be put together. How many lines does it span? Are multiple simple controls on one line? If so, how much space do they take as a percentage of the whole line?

There are two icons to create: one icon is displayed in Formvine’s field list in the Form Designer. Another icon is displayed when the project owner drags the control to a form. This icon is also displayed in the control spyglass.

Finally, you need to think about text. You need a name for the control. You also need to label each part of the control so the submitter will know what data is being asked for. And, you need to provide default instructional and hint text, or use the standard Formvine placeholder text. In addition, you must create an error message for each piece of data that does not meet validation requirements.



Creating a new compound controlBefore you modify prefab.xml, make sure you have the following assets in hand:

• Visual design for the control displayed in the spyglass thumbnail, sized to 240 pixels in width; height is variable

• Visual design for the control in the Form Designer field list, sized to 24x24 pixels

• The text for the control name, the labels for fields that are part of the compound control, the help text on hover, the hint text, and validation errors

Here is the entry for US Address field in prefab.xml:

<item id="usaddress" text="Address - US" thumbnail="Address.png"icon="US_address_v2_24x24.png"description="Adds address fields for a U.S. address, including two street address lines, city, state, and zip code."><field title="US Address" type="fieldset" preferredlayout="100%,100%,65%,20%,15%"><field title="Address line 1" required="true" type="textbox" error="This field is required. Enter the first line of the address."/><field type="textbox" title="Address line 2" label="Address line 2"/><field title="City" required="true" type="textbox" error="This field is required. Enter the city."/><field title="State" type="lookup" lookup="0" required="true" error="The state is required. Make a selection."><data>

<record id="AL" text="AL"/>

<record id="AK" text="AK"/>

...

</data></field><field title="Zip" type="textbox" required="true" error="This field is required. Enter a 5-digit zip code."inputformat="{pattern:{value:'^(\\d{5})?$',error:'Zip code not valid. Enter a 5-digit zip code.'},minlength:{value:5, error:'Zip code not valid. Enter a 5-digit zip code.'},maxlength:{value:5, error:'Zip code not valid. Enter a 5-digit zip code.'}}"/></field></item>



XML attributes for a compound control

The tables in this section list the XML attributes for a compound control.

The following table lists the attributes that define how the control is displayed.

The table below lists the elements that define the entire field set on the canvas.

Element Description

id The record ID. Used internally. Must be a unique identifier.

text The name of the control in the field list. In this example, the name is: US Address

thumbnail The preview image displayed in the spyglass, shown when hovering over the item in the Form Designer field list. The image must be 240 pixels wide. The path is relative to:

WebContent/versionedfiles/JSXAPPS/dashboard/editor/images/thumbnails

icon The 24x24 icon that is displayed in the Form Designer field list. The path is relative to:

WebContent/versionedfiles/JSXAPPS/dashboard/editor/images

description The text that is displayed when hovering over the list item.

Element Description

title The title of the control when it is dropped on the canvas. This can be changed by the project owner.

type The element that defines the type of control. For a compound control, this is set to: fieldset or compound

If type is set to fieldset, validation occurs as the cursor is moved off the control. Each subfield maps to a unique column in the Data view and the underlying database.

If type is set to compound, the control is validated on form submission. Each subfield is displayed in one column in the Data view and the underlying database. The Name and Email control and the Zip+4 controls are controls of type compound.



This table lists elements referring to fields and their data within the field set.

preferred layout

The structure of the control. The percentages correspond to the relative widths of the subfields, in the order in which they are defined. Each full row of the table equals 100%.

In the US Address example, the first two subfields are each on their own row. The three subfields on the third row share the row to total 100%: 65%+20%+15%

subtitle

tipThe default instructional text and hint text. Neither is used in the US Address control.

Note: Hint text cannot be longer than the field the text is providing the hint for.

Element Description

title The title of each part of the compound control, for example Address Line 1 or State. This cannot be changed by the project owner. If the element is empty or missing, no label is displayed.

required true makes the subfield required, but only if the project owner has selected that the entire compound control is required.

type Type of subfield, for example lookup defines this field as a dropdown list control. If lookup is defined, an additional lookup element is required. lookup=0 defines this control as a dropdown with a set of enumerated values.

error Defines the error message text.

label The text used at the top of the table in the Data view for each subfield. If this is absent, the title is used in the Data view.

<data><record>... :

Defines the list of enumerated values for a dropdown list.

Element Description



Example: Australian address compound controlTo give an idea of how advanced control modifications work, this section describes how to create an Australian Address compound control that replaces the US Address compound control. The following figure shows the completed control.

Figure 20 Australian Address control

inputformat Defines a set of additional validations (other than required/not empty). The format is a JSON object literal. The allowed keys are: pattern, minlength and maxlength. The value of each key is an object with two keys: value and error. value is the argument to the validation and error is the error message shown if the validation fails. Examples:

inputformat="{minlength:{value:4, error:'The year must be at least 4 digits.'}}"

inputformat="{maxlength:{value:1, error:'Your middle initial cannot be longer than one character.'}}"

inputformat="{pattern:{value:'^[A-Z][a-z]+$', error:'Your first name must start with an uppercase letter and proceed with one or more lowercase letters.'}}"

The pattern type validation follows standard Regular Expression syntax. Here is a Regular Expression reference: https://developer.mozilla.org/en/Core_JavaScript_1.5_Guide/Regular_Expressions

Element Description


https://developer.mozilla.org/en/Core_JavaScript_1.5_Guide/Regular_Expressions


To add this control to prefab.xml,

1. Remove the US Address control from the controls list by deleting the entire element from prefab.xml, beginning with:

<item id="usaddress" ...

2. Add the AU Address control to a new Compound Controls section in the field list:

— Create an appropriate compound control entry meeting the Australian address requirements.

— Create a Compound Controls record at the end of the prefab.xml file. The Compound Controls record looks like this:<item id="customcontrols" description="Custom Controls" text="Custom Controls" jsxopen="0" > </item>

3. Save the file.

XML for the Australian Address compound control

The following code block shows the code used to create the Australian Address compound control.

<item id="auaddress" text="AU Address" thumbnail="Address.png" icon="AU_address_24x24.png"

description="Adds address fields for an Australian address, including two street address lines, locality, state (dropdown list), and postcode." jsxtext="AU Address" jsxcategory="1" ">

<field title="AU Address" type="fieldset" preferredlayout="100%,100%,65%,20%,15%">

<field title="Street" required="true" type="textbox" error="This field is required. Enter the first line of the address." />

<field type="textbox" title="" label="Street 2"/>

<field title="Locality" required="true" type="textbox" error="This field is required. Enter the locality."/>

<field title="State" type="lookup" lookup="0" required="true" error="The state is required. Make a selection." value="VIC">

<data>

<record id="ACT" text="ACT"/>

<record id="NSW" text="NSW"/>

<record id="NT" text="NT"/>

<record id="QLD" text="QLD"/>



<record id="SA" text="SA"/>

<record id="TAS" text="TAS"/>

<record id="VIC" text="VIC"/>

<record id="WA" text="WA"/>

</data>

</field>

<field title="Postcode" type="textbox" required="true" error="This field is required. Enter a 4-digit postcode." inputformat= "{pattern:{value:'^(\\d{4})?$',error:'Postcode not valid. Enter a 4-digit zip code.'},minlength:{value:4, error:'Postcode not valid. Enter a 4-digit postcode.'},maxlength:{value:4, error:'Postcode not valid. Enter a 4-digit zip code.'}}" />

</field>

</item>
