Configuring rules

The UI includes a framework of rules for field dependencies and validation. Rules ensure that the data that users enter in the UI is valid.

A rule can either provide additional validation of a field’s value or alter the behavior of a field, such as hiding a field. Some rules allow you to compare the value of a field with another field, while others compare it to values defined in the rule itself. However, you can't use rules to change or override field dependencies.

Rules are available in Creation, Task, and Admin Views but not in Grid Views. In Task Views, you cannot add rules to fields in the Task View header. Controller fields used in rules must be in the view.

To define rules, go to the Design tab in the View Designer. Select a field and click New Rule in a field's property panel. Select a Rule Type and add conditions. The field type determines what rule types are available. A field can have multiple rule types.

To remove a rule, hover over the rule on the property panel. Click remove and then Done.

There are also Required, Editable, and Read Only rule types. These rule types are defined when you click New Rule. Use them to define whether a field is required, editable, or read only based on the value of another field in the view, called a controller field.

If Required is displayed as a toggle, you can set it to True. In which case, the Required rule type is disabled. If you set it to False, you can define a Required rule type that determines whether the field is required.
If Read Only is displayed as a toggle, you can set it to True. In which case, the Editable and Read Only rule types are disabled. If you set it to False, you can define Editable or Read Only rule types that determine whether the field is read only or editable.

Note: Dependent picklists are not defined in Task or Creation views. However, the views enforce the dependent pick lists that are defined on object types. For more information, see Adding and working with dependent picklists.

Table 1. Rule Types
Design	JSON	Description
Editable Read Only	`editable` `readOnly`	Makes a field editable or read-only based on the value of one or more other fields.
Visible Hidden	`visible` `hidden`	Makes a field visible or hidden based on the value of one or more other fields.
Required	`required`	Makes a field required based on the value of one or more other fields. In a view, the Save button is disabled until the field is given a value.
Greater than Greater than or equal Less than Less than or equal Equal	`greater` `greaterEqual` `less` `lessEqual` `equal`	Validates that a field’s value is greater than, less than, or equal to the value of another field of the same type, or to a value provided in the rule definition. You can define these rules on integer, decimal, date, or currency fields. In a view, a red star is displayed next to the field and the Save button is disabled until the validation passes. The Equal rule can also validate that two text fields have the same value. Large long string fields are not supported.
Minimum Length Maximum Length	`minLength` `maxLength`	Validates that the value of a text field has a minimum or maximum number of characters. In a view, the Save button is disabled until the validation passes. You can define these rules on string fields.
Pattern	`pattern`	Validates that the value of a text field has a specified format, for example, `nnn-nn-nnnn`. In a view, the Save button is disabled until the validation passes. You can define this rules on string fields. Large long string fields are not supported in pattern rules.

Defining Editable and Read Only rules

The Editable and Read Only rule types make a field editable or read-only depending on the value or values of one or more controller fields in a view.

About this task

You can define Editable and Read Only rules on any field type.

When you open the property panel for a field, the field type and field definition determine whether the Required property is displayed.

The controller fields must be either enumeration or actor fields.

When a field is made read-only because of a change to a controller field, changes to that field’s value since it was last saved are reverted to its original value.

Note: An exception exists for changes to values in grid and card relationship fields. The values cannot be reverted because they are saved immediately.

On the JSON tab, editable and read only rules are defined when type is set to editable or readOnly. Must also specify either a controllers or controllerName attribute. Specify one or more controllers as an array. Use the short-hand format controllerName rather than controllers to specify only a single controller for which ANY value will satisfy the rule’s criterion.

In the following steps, select Editable or Read Only in Rule Type.

Procedure

In the View Designer, click the Design tab.
The palette is displayed.
Select the field that you want to add a rule to.
In the property panel, click New Rule.
Select a Rule Type.
In Controlled By, choose One field with any value or Multiple controllers or values.
If you choose One field with any value:
1. Select a Controlling Field.
2. Click Done.
If you choose Multiple controllers or values:
1. In Controlling Field Logic select All controlling field conditions must be met or Any controlling field condition may be met.
2. Click New Controller.
3. Choose a field in Controlling Field. All available controlling fields are displayed. The next selections depend on the field type.
  - For actor fields, you can set Match Current User and/or select other users or user groups in Other Users or Groups. Any match on either field resolves the controller to true. If Match Current User is set to true, the signed on user must be the user or be in a user group for the value in the Controlling Field.
  - For enumerated type fields, click Values and you can choose one or more individual values.
  - Click Done.
4. Click New Controller to add the next controller field. Repeat the previous steps until all controller fields are added. Although you can change the order of the controller fields, it has no effect in the view.
Click Done.

Defining Visible and Hidden rules

The Visible and Hidden rule types make a field or inline guidance for sections either visible or hidden depending on the value or values of one or more controller fields in a view.

Before you begin

About this task

The Visible and Hidden rule can be defined on any field type and on inline guidance for sections. If a visible field dependency is already defined on a field, you cannot define additional rules of these types on that field in a Task or Creation View.

The controllers must be either enumeration or actor fields.

When a field is made hidden because of a change to a controller field, changes to that field’s value since it was last saved are reverted to its original value.

Note: An exception exists for changes to values in grid and card relationship fields. The values cannot be reverted because they are saved immediately.

On the JSON tab, visible and hidden rules are defined when type is set to visible or hidden. You must specify either a controllers or controllerName attribute. For more information, see Defining Editable and Read Only rules.

In the following steps, select Visible or Hidden in Rule Type.

Procedure

In the View Designer, click the Design tab.
The palette is displayed.
Select the field that you want to add a rule to.
In the property panel, click New Rule.
Select a Rule Type.
In Controlled By, choose One field with any value or Multiple controllers or values.
If you choose One field with any value:
1. Select a Controlling Field.
2. Click Done.
If you choose Multiple controllers or values:
1. In Controlling Field Logic select All controlling field conditions must be met or Any controlling field condition may be met.
2. Click New Controller.
3. Choose a field in Controlling Field. All available controlling fields are displayed. The next selections depend on the field type.
  - For actor fields, you can set Match Current User and/or select other users or user groups in Other Users or Groups. Any match on either field resolves the controller to true. If Match Current User is set to true, the signed on user must be the user or be in a user group for the value in the Controlling Field.
  - For enumerated type fields, click Values and you can choose one or more individual values.
  - Click Done.
4. Click New Controller to add the next controller field. Repeat the previous steps until all controller fields are added. Although you can change the order of the controller fields, it has no effect in the view.
Click Done.

Defining Required rules

The Required rule type makes a field required depending on the value or values of one or more controller fields in a view.

About this task

The field is validated to make sure that it has a value any time a change is made to the field or one of its controller fields. If the field is required but is missing a value, a message is displayed on the field and the Save button is disabled.

This rule can be defined on any field type, except on relationship fields where the object type (objectTypeName in JSON) is set to SOXDocument.

If a required field dependency is already defined on a field, you cannot define additional rules of this type on that field in a Task or Creation View.

The controllers must be either enumeration or actor fields.

On the JSON tab, a required rule is defined when type is set to required. You must specify either a controllers or controllerName attribute. See Defining Editable and Read Only rules for more details.

In the following steps, select Required in Rule Type.

Procedure

In the View Designer, click the Design tab.
The palette is displayed.
Select the field that you want to add a rule to.
In the property panel, click New Rule.
Select a Rule Type.
In Controlled By, choose One field with any value or Multiple controllers or values.
If you choose One field with any value:
1. Select a Controlling Field.
2. Click Done.
If you choose Multiple controllers or values:
1. In Controlling Field Logic select All controlling field conditions must be met or Any controlling field condition may be met.
2. Click New Controller.
3. Choose a field in Controlling Field. All available controlling fields are displayed. The next selections depend on the field type.
  - For actor fields, you can set Match Current User and/or select other users or user groups in Other Users or Groups. Any match on either field resolves the controller to true. If Match Current User is set to true, the signed on user must be the user or be in a user group for the value in the Controlling Field.
  - For enumerated type fields, click Values and you can choose one or more individual values.
  - Click Done.
4. Click New Controller to add the next controller field. Repeat the previous steps until all controller fields are added. Although you can change the order of the controller fields, it has no effect in the view.
Click Done.

Defining Greater than, Greater than or equal, Less than, Less than or equal, and Equal rules

The Greater Than, Greater than or equal, Less than , Less than or equal, and Equal rule types validate the value of a field and make sure that it satisfies the condition applied by the rule type. The rule can be set up to compare a field’s value with the value of another field of the same type, or with a value defined in the rule itself.

About this task

Any time a change is made to the field that it is validated to make sure that it satisfies the condition. If the value is being compared to another field, it is validated any time that field’s value changes. If the condition is not satisfied, a message is displayed on the field and the Save button is disabled. The message explains how to provide a valid value.

These rule types can be set up on integer, decimal, date, and currency fields. When comparing two fields, both fields must be of the same type. If one of the fields has no value, the rule is not evaluated.

Text fields can also have an Equal rule, but only to compare against another text field. Large long string fields are not supported.

On the JSON tab, comparison rules are defined when type is set to greater, greaterEqual, less, lessEqual, or equal. A compareTo attribute must also be specified.

Procedure

In the View Designer, click the Design tab.
The palette is displayed.
Select the field that you want to add a rule to.
In the property panel, click New Rule.
In Rule Type, choose Greater Than, Greater than or equal, Less than , Less than or equal, or Equal.
In Compare To, the field type determines the options.
- For integer, decimal, and currency fields, you can choose A specific value and enter a value. Do not include quotation marks, decimal separators, currency codes, or symbols.
- For integer, decimal, currency, date, and text fields, you can choose Another field and select a field. Only fields in the view and of the same field type are listed.
- For currency fields, values are compared using the base amount rather than the local amount. This allows values to be compared across different currency codes.
- For date fields, you can compare the value to today and optionally add an offset in days.
  Because the value of Today changes as time progresses, rules that compare against Today are evaluated only when a user selects a value for the field. This prevents previously saved data from failing validation due to the changing nature of Today.
Optional: Apply a Severity. For more information, see Controlling error severity on rules.
Click Done.

Defining Minimum Length and Maximum Length rules

The Minimum Length and Maximum Length rule type validates the length of a text field or, if used together, defines a range.

About this task

The field is validated to make sure that the length of the text value is valid any time a change is made to the field. If the condition is not satisfied, a message is displayed on the field and the Save button is disabled. The message states how many characters are allowed.

These rules can be set up only for text fields.

You can provide either the Minimum Length or Maximum Length rule type. You can apply both to define a range.

On the JSON tab, minimum and maximum rules are defined when type is set to minLength or maxLength. Specify compareTo as a number of characters within quotation marks.

Procedure

In the View Designer, click the Design tab.
The palette is displayed.
Select the field that you want to add a rule to.
In the property panel, click New Rule.
In Rule Type, choose Minimum Length or Maximum Length.
Enter the number of characters.
Apply a Severity (optional). For information, see Controlling error severity on rules.
Click Done.

Defining Pattern rules

The Pattern rule type validates that a text field has a specified format.

About this task

The field is validated to make sure that the value has the correct format any time its value is changed. If the format is not correct, a message is displayed on the field and the Save button is disabled.

This rule can be set up only for text fields. Large long string fields are not supported in pattern rules.

On the JSON tab, a pattern rule is defined when type is set to pattern. Specify compareTo as a valid regular expression.

Procedure

In the View Designer, click the Design tab.
The palette is displayed.
Select the field that you want to add a rule to.
In the property panel, click New Rule.
In Rule Type, choose Pattern.
In Pattern, enter a valid regular expression, for example, ^[0-9]{3}-[0-9]{2}-[0-9]{4}$.
Apply a Severity (optional). For information, see Controlling error severity on rules.
Click Done.

Controlling error severity on rules

Use the Severity property to control whether errors or warnings are issued when users enter values that do not pass validation rules.

About this task

When users enter values that do not pass a field's validation rules, an error is issued and the object cannot be saved. However, if you apply the Severity property, warnings are issued rather than errors. When a warning is issued, an object can still be saved.

You can add a Severity property to any validation rule type (Greater Than, Greater than or equal, Less than , Less than or equal, and Equal). You can specify it to be an error, warning, or information. If a rule has no severity property, errors are issued.

For example, a warning can be issued if a date field is not within the next 90 days. If the severity property is omitted, an error is issued.

The text in the message is set by the system and cannot be customized.

Multiple warning messages can be displayed for a field. However, only one error message is displayed.

Conditions, for example, field dependencies and field attributes, always issue errors rather than warnings.

An information message behaves like a warning but is displayed with an information symbol. The error message text is the same whether it is a warning or an information.

On the JSON tab, specify severity as error, warning, or info.

Procedure

In the View Designer, click the Design tab.
The palette is displayed.
Select the field that you want to add a rule to.
In the property panel, click New Rule.
In Rule Type, choose a rule type.
In Severity, choose Error, Warning, or Info.
Click Done.