What is Form Administration?
Form administration is where BLUE administrators create and edit forms. Form administration is accessible from BLUE by selecting ‘Form Template Administration’ from the Advanced administration menu.
After selecting ‘Form Template Administration’, the Form Administration screen opens, which by default lists all ‘enabled’ forms within the system.
From the forms template administration page an administrator can:
-
- Use the search dialog to search for forms with matching name
- Toggle the list to show / hide ‘disabled’ forms
- Create a new form
- Preview the selected form
- Edit the selected form
- Disable / enable the selected form
- Export the selected form
- Import a form that was exported from this or another BLUE system
Disabling forms
Disabling a form prevents the form from being selected while configuring a process template. Disabled forms will continue to be used by process templates that have already been verified and saved.
Previewing forms
Previewing a form allows the administrator to view the layout of a form as it would be displayed to an end user. The administrator can also interact with fields and buttons on the form to test (most) of the form rules that may have been configured.
Form rules are described below. Certain rules, like those based on the users group (role) can’t be tested in preview mode.
Exporting and importing forms
Exporting and importing forms is a tool that can be used by administrators to ‘copy’ a form from one system to another – an example would be to export a form from a development environment and import it to a production system.
Exporting forms
To export a form, select the form in the Forms Administration page and click Export.
Your browser will prompt you save the file to your local machine. Forms are saved as .json files
Importing forms
To import a form, click Import in the Forms Administration page. You will be prompted to navigate to a file to import. Select a “.json” file previously exported. When the form is imported, you will be placed in the forms editor. Once in the Forms Editor, you will need to (at a minimum):
-
- Enter a form name
- Enter a form title
- Save the form
Note: Because forms are a vehicle to enter and display custom fields, it is a best practice to ensure that field(s) referenced in the form exist in the target environment prior to the import.
If you import a form that references custom fields that are not defined in the system, the import will be successful. When the form is opened in the editor, visual cues will assist in identifying which form fields need to be addressed. The screenshot below is an example of a form imported to a system where none of the custom fields were defined:
In the screenshot above – visual warnings (yellow triangles) are provided for each field where the administrator must take an action. In this case, the administrator could either:
1. Click on the form field(s) containing a warning and assign a similar custom field already defined in the system.
2. Save the form, create a new custom field(s), then re-edit the form to select the newly created field.
Tip: Notice also that the left navigation panel contains a list of all fields within the form that need to be addressed. The list is updated as errors are fixed. The Field Error list comes in handy when the form contains errors are on tab(s) that are not currently visible to the user.
Creating new forms
To create a new form, click Create New Form on the Forms Administration page. A blank form opens:
Overview of form editor sections
The form editor contains 5 primary sections:
1. Form Properties
– Form Name (required): Descriptive name used by administrator only
– Form Title (required): Text end user will see in the title bar
– Form Rules (button): Opens Form Rules Builder (see below)
2. Form Elements
This section allows the administrator to drag a control onto the form (e.g. check-boxes, radio buttons, text areas, etc.)
3. Form Structures
This section allows the administrator to drag a container to the form. Container types are:
– Blank Container
– Tabbed Container
4. Constraint Rules
This section allows the administrator to add and remove constraint custom fields on the form.
5. Canvas
The form itself is represented in the center of the screen – referred to as the ‘canvas’.
6. Properties Panel
Allows the user to configure properties of the selected field or form container (tab, section, etc.).
Working with tabs
A new form has one tab, named ‘Tab 1’ by default. Tab names are only visible to the end user when more than one tab is present on the Form.
To add additional tab(s), select the + icon next to the existing tab.
To edit the properties of a tab, select the pencil icon next to the tab name.
To delete a tab, select the ‘x’ next to the pencil icon.
Tab properties
Selecting the pencil icon will open the tab properties panel on the bottom half of the canvas. From here you can configure:
| Tab Title (required) | Visible only if there is more than one tab on the form |
| Visibility | Tab and contents are either visible or hidden by default |
| Verify Required Fields on Tab Change |
If selected, the end user will be required to enter data into all ‘required’ fields on the tab before they can advance to the next tab. If deselected the end user can move from tab to tab without entering required fields. On submission of the form missing fields marked as required will be brought to the end user’s attention. |
Working with form structures (containers)
The ‘Form Structures’ section in the left navigation lets you drag new tabbed or blank containers to the form. There’s no limit on nesting of containers.
Form Elements (drop-down boxes etc.) can be added directly to any container.
Tip: You can ‘split’ containers using the ‘number of rows / columns’ properties, then use the ‘number of columns spanned to make some larger than others’.
Tip: To help align items on the form, try adding multiple containers and spans, then set the containers style property to ‘no-border / title’. End users will not see the borders around the container but the fields within the containers will still be sized and aligned.
Clicking on the title bar of a container will open its Properties panel. Through the properties panel you can configure the following:
Title |
The title of the container / section is displayed to the end user |
Number of Rows |
Will split the container into sections (up to 10 rows) |
Number of Columns |
Will split the container into sections (up to 4 columns) |
Number of Columns Spanned |
If the container was split into 4 columns, you can control how many of the four columns each individual ‘piece’ should occupy |
Style |
Color / style for the border of the container (no border, green, red, yellow) |
Visibility |
Should the container and its contents be visible or hidden by default? Visibility can be changed using form rules |
Default Display Mode |
Editable / view Only. Can be changed using form rules |
Expand / Collapse Enabled |
If checked, the form will contain a ‘+’ or ‘-’ icon to the user, allowing them to expand or collapse the section when working with the form |
Remove Button Enabled |
Future functionality – please disregard |
Adding Form Elements (Field Types)
To add a custom field type to a form, expand the list of ‘Form Elements’ in the left navigation panel of the form editor. Select an element type and drag it to the desired container. Once the elements are in the container, you can re-position them within the container using drag and drop.
Here’s a screenshot of the expanded ‘Form Elements’ section within the left navigation panel of the Form Editor:
Each form element is associated with specific types of custom fields:
| Form Elements | Description and usage |
| Check Boxes | Can be used with predefined custom field values. |
| Date Input | Can only be used with date custom fields. |
| Multiselect | Can be used with predefined custom field values. |
| Radio Buttons | Can be used with predefined custom field values. |
| Select 2 | Can be used for single or multi-select predefined custom field values, with options to search for values, and select and clear all values. Use this type of form element when there are lots of values. |
| Select Box | Can be used with predefined custom field values. |
| Text Area | Can be used with custom fields defined as a string or number. |
| Text Input | Can be used with custom fields defined as a string or number. |
| Fixed Text | Enter ‘helper text’ on a form. This field is not associated with a custom field – it’s just a way to enter static text on a form that will be seen by end users. |
Attribute Setup Tab
Once a form element is on the form canvas, the properties panel for that element will open in the bottom portion of the canvas. If it is not open already, click on the form element to open the properties panel.
In the properties panel for an element you can configure:
Data Source |
Configure the attribute and data settings |
Attribute (required) |
Select the custom field this control will be associated with |
Utility Only (don’t submit) (checkbox) |
The value selected on the form is not saved. These are typically fields on the form the user selects which change the layout of the form (e.g. if the user selects ‘Translations Needed’ on the form which makes an additional field appear where they now need to translate the language) |
Display All Values (checkbox) |
This option is available for preset custom field values. If checked, all preset values will appear to the end user. If unchecked, the administrator selects which values should appear for the end user. |
Display Control |
Configure the element display settings |
Label |
By default you will see the label defined in Custom Field Administration but you can override it to something different for the form user |
Width |
The field can take either the entire width of the container or a portion of it |
Display Mode |
Editable / view only |
Required (checkbox) |
If checked, the user must enter a value in this field to submit the form |
Disabled (checkbox) |
If checked, the value selected / seen is sent with the form but the control is not editable by the end user |
Visibility |
Default visibility of the field (visible or hidden). Form rules are used to change visibility |
Utility Only (don’t submit) (checkbox) |
The value selected on the form is not saved. These are typically fields on the form the user selects which change the layout of the form (e.g. if the user selects ‘Translations Needed’ on the form which makes an additional field appear where they now need to translate the language) |
Display All Values (checkbox) |
This option is available for preset custom field values. If checked, all preset values will appear to the end user. If unchecked, the administrator selects which values should appear for the end user. |
Label |
By default you will see the label defined in Custom Field Administration but you can override it to something different for the form user |
Display Tip |
Configure the tooltip |
Activate Display Tip (checkbox) |
If checked, the administrator can enter helper text which will appear as a tooltip to the end user on hover |
About Form Rules
The Form Properties section in the left navigation of the Form Editor allows you to configure form rules.
The rule builder allows you to create rules by selecting values from drop-down items and/or clicking directly on the form fields you want to base the rule and be affected when the rule is executed.
Here are a few examples of things you can do with Form Rules:
-
- Show or Hide fields and entire sections
- Set default values or available values of fields
- Set fields to editable / view-only, enabled / disabled, or required / optional
- Change tab or container titles on-the-fly
Examples of what a rule might do:
-
- If the value of Brand is ‘a’ or ‘b’ then hide form-tab-2, make sub-brand required and set it’s available values to only be ‘xtra-strength’ and ‘maximum strength’
- If the users Role is ‘Marketing’ then hide the legal-section and show the marketing-section
Limitation
-
- When a Fixed Text element is selected as a dependent (after clicking the Select Dependent button), the Affect drop down has an option to “Set Value(s)”, which is not relevant or supported for this type of element.
To create a new rule based on the value of a field on the form:
- Open the ‘Form Properties’ section in the left navigation of the form editor.
- Click Add New Rule.
- Enter a name for the rule
- On the Controller drop down, select ‘element’ as the type of controller
- Click Select Controller.
- Click on the field within the form that you want the condition to be based on
- Select the ‘Condition Type’ (e.g. on-change, value, load)
- Select the actual value(s) of the condition
- Select the value of the condition
– Ex. ‘is equal to’, ‘is not eqal to’, - If you want the condition of the rule to be based on more than one field click ‘Add ‘and’ Rule’ link and repeat steps 2 thru 8
- Click on Select Dependent.
- Click on the field (or tab / section) within the form that you want to impact
- Select an ‘Affect’ (e.g. required, hidden, disabled, set value, label…)
- Depending on the ‘Affect’ selected, you will be prompted to set the actual value(s) or provide other information
- If you want to have more than one field or section impacted when the rule fires, Click ‘Add a Dependent’ link and repeat steps 10 thru 13
- When your rule is complete, click Done Editing to save and minimize the rule
To create a new rule Based on the value of a field on the form:
- Click Add New Rule.
- Enter a name for the rule
- Select ‘Role / Group’ as the e type of controller
- Select ‘Logged in User’ as the Condition Type
- Select ‘Is Equal To’ or ‘Is Not Equal To’ as the condition
- Select the Role(s) that will make the condition true
- Follow steps 10 thru 15 above to complete the rule
Tip: Rules based on field values are fired dynamically as users interact with the form and changes a selection or value. You will typically need several rules to ensure the form sets and re-sets fields properly as the user clicks around on the form then changes their selection to something else.
About Constraint Rules
A constraint field in BLUE is a single custom field that defines the relationship and available values between multiple (other) custom fields. This constraint logic allows for a certain custom field value to drive which values are available for another custom field. For example, if a user chooses a particular brand on one drop down, then on another related drop down only a subset of products that are appropriate for the selected brand should be available to choose from.
The ‘Constraint Rules’ section in the forms editor is where you will search for, apply and remove constraints on the form. Here is some additional information about setting constraint rules on forms:
Tips and Notes
- Multiple constraints can be added to a single form, provided there is no overlap in the fields they are constraining
- Custom fields that make up the constraint can appear anywhere on the form (eg. different groups, sections or tabs)
- Form rules can be applied to constrained fields provided the form rule does not violate the constraint rule
- Adding constraints to a form that is already in use by an enabled workflow, will automatically:
- Home the constraint to the form task if the constraint is not used elsewhere in the workflow
- Extend the constraint to the form task if the constraint is already homed at another task in the workflow
- Use Template Administration to verify homing of custom fields
- A recommended best practice after updating any form that’s already associated with a template, is to use legacy Template Administration to check the homing of all custom fields associated with the form task to ensure they are homed or extended as expected, especially when deleting any type of custom field from a form.
- Removing a constraint rule from a form will not automatically remove the constraint from being associated with the form task in a workflow.
Adding constraints to a form
BLUE forms support constraint custom fields. Once the constraint custom field has been configured, perform the following steps to set up the constraint and custom fields:
- Open the ‘Constraint Rules’ section of the form editor.
2. Open the ‘Constraint Rules’ dropdown
-
- The selection list displays all of the constraints defined in the system
- Choose a constraint from the list. The fields that it constraints will be shown in the Detail panel.
3. Click Apply to Form to apply the constraint rule to the form. The constraint is shown in the applied rules section.
4. Ensure each of the underlying constrained fields (that make up the constraint) appear on the form.
To add the fields to the form, you will need to open the ‘Form Elements’ (or ‘Form Fields’) section and drag the element types onto the form, then choose the attribute associated with that form element.
Notes and Tips:
-
- This can be done before or after applying the constraint rule
- Fields can be placed anywhere on the form—on any tab or container as long as they are on the form
In the following example, the constraint includes the custom fields Brand, Product, and Component Type, which all exist on the form.
Tip: Hovering over the applied rule will display a tooltip showing the underlying constrained fields that need to be on the form.
5. Click Save (top right) to save your changes.
If the form is associated with an enabled workflow template, the system will try to automatically home or extend the constraint to the corresponding form task in the workflow.
Here is an example of correct custom field assignments for the form in the example above.
Notice in the above screenshot that the constraint ‘Brand>Product>Component’ is homed to the form task but the underlying constrained fields (Brand, Product and Component Type) are not.
6. Resolve Warnings.
If there are no warnings, go to the next step.
If you’ve applied a constraint rule to a form where any of the underlying constrained fields are already homed to a workflow task, a Warning dialog similar to this will appear.
The warning dialog provides information about which templates, tasks and constraints need to be verified after saving the form. In the sample screenshot above, the system is about to home the constraint ‘Brand>Product>Component’ to two tasks where the underlying custom fields that make up the constraint are already homed or extended.
To save the warning and save your form changes:
-
- Click Save Warning if you would like to download a text version fo the warning, so you can refer to it while in template administration. These warnings will guide you to the templates and tasks that need to be updated.
- Click Continue to save the form.
7. Verify the custom fields in legacy Template Administration.
After saving the changes to the form:
-
- Open the workflow template in legacy ‘Template Administration’.
- Select the ‘Custom Fields’ tab.
- Verify that the custom fields are homed correctly. Verify that the constraint is homed or extended as expected. The custom fields that make up the constraint should not be homed or extended to the task.
- If you are upgrading from BLUE 6.2 or earlier, which did not support true constraints on forms, remove each of the underlying custom fields that make up the constraint.
- Go back to the form in form administration and save the form again. Verify that the warnings are now resolved.
Removing constraints from a form
The following instructions explain how to remove constraint rules on forms, including templates which are using the constraints.
- Remove the constraint rule from the form.
Select the constraint from the ‘Applied Rules’ dialog, then click the ‘Remove selected’ link. This only removes the constraint rule; the form fields/elements that were added to the form remain on the form.
If the form is associated with an enabled workflow template, the constraint will remain homed (or extended) to the form task within the workflow. A warning dialog similar this will appear when you save the form.
The Warning dialog provides information about which templates, tasks and constraints need to be reviewed in legacy template administration after saving the form. In this example, the constraint is homed or extended to three tasks in two different workflows.
2. Verify the custom fields in legacy Template Administration.
After saving the changes to the form, do the following:
-
- Open the workflow template in legacy ‘Template Administration’
- Select the ‘Custom Fields’ tab
- Remove the constraint custom field from the form task.
Saving Forms
After you’ve made changes to the form, save your changes.
Save your changes
- Click Save (top right) to save your form changes.
2. Resolve any warnings when saving the form. You may need to go to template administration to do this.
Warning dialog options
If there are any form issues, including issues related to custom fields and/or homing on templates, a warning message will inform the administrator about any issues or conflicts that exist.
When presented with a warning dialog, choose one of the following options:
-
- Cancel: No changes to the form or updates to constraint custom fields on the template will be made.
- Save Warning: Wave the warning message to a file or open it in an editor to use as reference after saving the changes to the form. This allows you to save a copy of the changes that are needed if you need to navigate to template administration to make some changes to custom field homing and extending.
- Continue: Save the changes to the form and also home or extend any constraints to form tasks in the workflow.
Save As new form
This option allows you to save a new copy of the form with a new form a name and title.
Upgrade Notes for 6.3
If you were using forms that leveraged constraint logic prior to BLUE 6.3 you will need to do the following:
Edit the form:
-
- Apply the constraint rule to the form as described above.
- Save the form and take note of any warning messages – they will guide you to the templates and tasks that need attention.
From legacy Template Administration:
-
- Select the Custom Fields section
- Click ‘Show Custom Fields’ for the form task
- Remove the underlying custom fields from the task (this are the custom fields that are being constrained)
- Ensure the constraint custom field is homed or extended to the form task as expected
For more information on related topics, visit these links…
To configure Complete Form tasks on the template, see Form Task Nodes more information.
For more information about template task node settings, see Task Node Settings.
For more information about completing forms tasks, see Form Tasks.