Rules

This page covers the following ways to work with rules:

Rule actions
Add a new rule
Change or delete rules
Use the Rules Inspector
Work with conditions

Rules are powerful tools that control logic and help automate functions within a form, such as updating one field automatically when data in another field is changed. Rules can apply formulas to data, change data, and change the appearance of data in a form.

For example, you would use a rule to make a Button trigger a specific function, such as a search against a database, activating a Web service, or setting a field value. You can also use a rule to indicate incorrect data entry by changing a field color to red to indicate an incorrect value.

For Advanced Rules

If the Solution Builder does not provide the flexibility required to create a rule, advanced users can create rules using custom JavaScript. See the JavaScript Reference Guide for information about supported JavaScript wrappers, syntax, and more.

Rule actions

Note:

Every rule can consist of one or more Actions. In the example above, a single rule could be used to handle both functions, each of which would be a separate action. For example, you can use a rule to automatically calculate and update the total price form field based upon values entered by the user in an item price field and a quantity field.

When applying more than one rule to a Field or Button, the following Actions can only be used once and must be the last rule in the sequence:

Execute Query
Execute Web Service
Submit Form

This is because a request is made to the server so no additional rules can be executed once the request has been made.

Note:

Fields with rules applied to them appear with a check icon next to their name in the Solution pane on the Solution tab. Example:

A rule consists of a rule type (Action, Formatting, or Validation), one or more Conditions, or one or more Actions.

Add a new rule

In the Properties pane, click Properties.
On the Properties tab, next to Rules, click the Options [...] button.
The Rules Inspector opens in the Properties pane.
Click Add Rule.
Enter the following information for the rule:
- Label: Type a descriptive name for the rule.
- Run Rule On form Load: Select this to run the rule as soon as the form is loaded.
- Type: Select a Rule Type: Validation, Formatting, or Actions.
- Condition: Click to create the condition(s) for when the rule is triggered, such as when a specific form field changes. See Work with conditions (below) for more information.
- Message: Enter a message to display to the user when the rule is run.
- Use Popup: Check this box to use a popup to display the message to the user.
- Popup Title: If you selected Use Popup, type a name for the popup window in this field.
Click OK to finish.

Change or delete existing rules

Click in the field or element that has the rule you wish to change.

In the Properties pane, click Properties.
On the Properties tab, next to Rules, click the Options [...] button.
In the Rules Editor:
- Click add to add a rule action.
- Click the edit icon to open the rule in the editor.
- Click the delete (trash can) icon to delete the rule.
- Click the condition to change the rule condition. See Working with conditions (below) for more information.
- Click delete condition (the trashcan) to delete a condition.
Click OK to finish your changes.

Use the Rules Inspector

Use the Rules Inspector to get a snapshot or 'dashboard' of all the rules in your solution.

From the Rules Inspector, you can:

Search for specific rules in the search bar to filter results.
Print the results.
Edit a rule by clicking its name.
View all of the rules applied to a field by clicking the name of the field.

Work with conditions

The Condition Builder provides a simple graphical interface for creating the logic and rules for your condition.

Click Add Condition to add a condition.
Click Add Group to add a sub-group of conditions.
Select Form Fields and logical operators (such as "is equal to" or "not equal to" for example) from the drop down menus.
Click Delete to delete a condition or group.

Below: A sample condition in the Rule Condition Builder

Types of rules

There are 4 basic types of rules: Validation, Formatting, Action, and JavaScript (see the JavaScript reference guide for more information about JavaScript rules.) Each type of rule is also governed by a common set of general properties.

See below for details about the following:

General rule properties
Validation rules
Formatting rules
Action rules
Action Rule Quick Reference Table

General rule properties

Run Rule on Form Load Indicates whether or not the rule should be executed immediately when the form is loaded.

Halt Execution in Debugger Before running this rule

This option is good for troubleshooting rules. Enabling this option inserts a debug breakpoint into the javascript code just prior to executing the rule. If the browser Development Tools are active and this rule is executed, the browser debugging session will stop just prior to executing the rule for further interrogation of the code.

Disable Rule

Enabling this option stops the rule from running when the form is run.

Type Specify the type of rule to create. Additional options will be displayed depending on the type of rule selected. See below for more information:

Validation
Formatting
Action

Condition If the specified condition condition is true this rule will be run, otherwise it will not run.

Note:

If you use a condition to compare against a Reference Data list Yes/No column:The value must be True or False (without quotation marks, etc.) The first letter must be capitalized, i.e., True or False, not true/false

1. Validation Rules


A Validation Rule can be used to display an error message when data entered into a form field is invalid. You can specify the conditions under which the error message is displayed. For example, you could create a rule to display an error if a number entered into a field is greater than a certain value, less than a certain value, or both. Label: A descriptive label for the rule. Run rule on form load: Check this to run the rule when the form is first loaded. Condition: Click to open the Rule Condition creator to define conditions under which the rule comes into effect. Conditions can be basic value comparisons or involve complex formulas. Type: The type of rule. Error Message: The error message text you would like displayed when the conditions you have defined are met. Use Popup: Displays a dialog box with the Validation Message instead of highlighting the error on the form. This option is used to only display a message. The rule will not be validated prior to submitting the form. Popup Title: The title for the Popup box.

2. Formatting Rules


Formatting rules apply specific formatting to a form field when certain conditions are met. For example, if the value entered into a form field is too high, you can create a rule to change the form field to the color yellow. Label: A descriptive label for the rule. Run rule on form load: Check this to run the rule when the form is first loaded. Condition: Click to open the Rule Condition creator to define conditions under which the rule comes into effect. Conditions can be basic value comparisons or involve complex formulas. Type: The type of rule. Apply Styles to Fields: The field to which the formatting will be applied. Formatting options: Font and color options: Bold, Italic, Underline, Striket background and text color.
Font Style Modifications
Font style modifications (to apply the form component for this field): Bold Italic Underline Strike-through Background Color Text Color
Form Component Modifications
To hide, require, or disable a field, create an Action Rule using Change Field Properties. For more information, see the entry for Change Field Properties in the Action Rule - Quick Reference Table. Hide Component Group: Hide the entire group that contains the field if the condition is true. Hide Component: Hide the field and its labels if the condition is true. Disable this Component: Disable the field if the condition is true. Require Component: Set the field to Required (i.e., the form cannot be submitted if the field is empty) if the condition is true.

3. Action Rules

Action rules are the most versatile rules. Action rules can perform a wide range of functions, such as setting values in specific fields, comparing values in fields, calculating values based upon formulas, and more.


Label: A descriptive label for the rule Run rule on form load: Check this to run the rule when the form is first loaded. Condition: Click to open the Rule Condition creator to define conditions under which the rule comes into effect. Conditions can be basic value comparisons or involve complex formulas. Type: The type of rule. Add: Click to add the rule and open the Add Rule Action dialog box (see below).

Once you have specified the basic information and conditions for an Action rule:


Action: Select the action from the drop-down menu. See the Rule Quick Reference Table below for a description of Rule Actions. Field: Select the field that the action will be applied to. You can also type the name of a field to automatically search for it. Value: Type a value, or click f(x) (function) to insert a formula that will be run as part of the action.

Action rules - quick reference table

See below for a description of what each Action rule does, and the parameters associated with the action.


Action	Description
Add New Row	Adds a new row to a repeating table or group. Parameters Group: The repeating group to which a new row is to be added.
Change Field Properties	Change a field's properties to show, hide, enable / disable, or require / not require input. Parameters Available options: Show \| Hide \| Enable \| Disable \| Required \ Not Required Field: The field to change.
Change Group Display	Shows, Hides, Expands, or Collapses a group based upon a specified field within the group. Parameters Field Within Group: The Field data governing the display state of the containing group. (Show \| Hide \| Expand \| Collapse)
Copy Like Rows	This rule can be used to copy rows from one repeating table or repeating group to a target repeating table or repeating group. This rule matches the column value in the source repeating element to determine which rows to copy based upon the selector field property. The Copy Rows Action determines if the matching rows should be overwritten or added to the target repeating element as new rows.
Copy Table Data	You can copy data between tables using the Copy Table Data rule available in the Solution Builder user interface. If you want to access this feature, please reach out to your Sales account representative for more details. Parameters Current Field/Table: The field to which the Copy Table Data rule is applied. (Mandatory) Primary Source: The table from which the values can be copied. This can be a single row or multiple rows based on the defined conditions. (Mandatory) All the Repeating Table/Repeating Group/Selectable Table present in Form Data will be populated in Primary Source list. Additional Source: Non-Repeating source fields defined in addition to the primary source. (Optional) Target Table: The table or the repeating group where the final set of data is copied. (Mandatory) Actionable fields: All the preceding fields are collectively referred to as the actionable fields. Condition: Defines the condition on which the rows to be copied are selected. Mapping: Defines the relationship between the source and the target fields. Update Type: Overwrite Rows: Clears the table and enables data to be written from the first row. If the Copy Data condition is not met, then no source table rows get copied to the target table. Also, the target table gets cleared. Append Rows: Enables to copy data from the last available row. Notes and Limitations Data type between the Source field(s) and the Target field must be the same. For a Repeating Table the data type field is called Input Type, whereas for a Repeating Group, the data type field is called Element Type. For example - If the Source table has a Date field which needs to be copied using the Copy Table Data rule, then the Target table should also be a Date field. The Source and the Target table should always be in the same Form view (current). When copying data from a Source field to a Target - Repeating Group (read-only), when you choose the Overwrite Rows option, the Delete Icon disappears even when the Copy Table Data rule condition is not met. The following elements cannot be copied: Label Attachment Selectable Table with Pagination Nested repeating tables are not supported for the Copy Table Data rule. Rules are not supported or executed on the Target table.
Delete Row Options	Enable: Show the "trashcan" (delete) icon Disable: Hide the "trashcan" (delete) icon Parameters Group: The repeating group for which to enable/disable Delete Row Options.
Empty Table	Clears all data out of a repeating table or group. Parameters Group: The repeating group which is to be cleared of all data.
Execute Query	Executes a Query control in the form. Parameters Query Control: The query to be executed.
Execute Rules for Field	Runs the rule on another field. This can be useful if 2 fields have rules related to one another. Parameters Field: The field on which to run the rule.
Execute Web Service	Executes a web service control in the form. Parameters Web Service Control: The web service to be executed.
Filter Repeating Content	Enables the filtering of Repeating Tables/Groups while preserving the content. You can configure a “condition” to use with this -- for example, field1= “this” and field2 != “that”. Only the rows that satisfy the condition(s) will be displayed in the Repeating Table/Group. Parameters Group: The group to filter based upon the Filter criteria. Filter: Create the filter logic for the drop-down list. For example, you can specify Is equal to and type a specific value, as well as and/or operators. You can also filter and view the repeating content by clearing the Filter and using contains operator in place of Is equal to.
New Row Options	Enable: Show the "Add New Row" link on a Repeating Table/Group Disable: Hide the "Add New Row" link on a Repeating Table/Group Parameters Group: The repeating group for which to enable/disable New Row Options.
Reload Drop Down Options	Causes the options of a drop down list or Combo box to be reloaded. This may be used for dynamic options lists. Parameters Field: The drop down field in which the options will be reloaded.
Render Map	Sends a new address to a map control on the form. Parameters Map Element: The map control to update with a new address. Description: The description to assign to the map location. Address: The address of the new map location. City: The city of the new map location. State: The state of the new map location. Postal Code: The postal code of the new map location. Country: The country of the new map location.
Search Repeating Content	This provides a mechanism to search all fields for a “pattern” (for example, if any field contains “abcd”). In this case all the rows where at least one field contains the pattern will be displayed in the Repeating Table/Group. Parameters Group: Group name Contains: Field name
Set a Field Value	This action allows you to change the value of a field in the form. Parameters Field: The target field you want to set the value of. Value: The formula to evaluate to obtain the new value for the field. This may contain other field values, function calls, external data references or constant values.
Set a Label	This rule action is similar to Set a Field Value (above), but will change the Label (or sub-Label) of a Form Element. Parameters XPath: The Field (selected from a drop down) for which to change the label valueof the form element. Value: The formula to evaluate to obtain the new value for the field. This may contain other field values, function calls, external data references or constant values Sub-Labels (True/False): Set to True to change the Sub-label of the specified element.
Show Message	This displays a pop up box with the message text specified in the rule. The properties on this rule are derived from a form's fields by default.
Sort Repeating Content	Sort the items in a repeating table. Parameters Field within group: The field in the repeating content to sort by. Sort Order: Ascending or Descending Persist: Set to True so the data remains sorted between different views. Set to false so the data does not remain sorted between different views.
Submit Form	This action allows you to simulate the Submit button of the form. Parameters Submit Type: The disposition or type of submit: Complete – Complete the current task. Approve – Complete the current task with Approved disposition. Reject – Complete the current task with Rejected disposition. Save – Save the form but do not start or advance the process. Save and Route – Save the form and start the process.