Property form: General tab — Configuring validation

  1. About
  2. New
  3. General
  4. Advanced
  5. More...
Note: For basic information about the General tab and choosing a property mode, see Completing the General tab — Choosing a mode.

Providing validation of input data is a best practice to prevent invalid data from entering a work item or the business process. One way of doing that is to specify a set of acceptable values for a field. At runtime, the system compares the input value to the specified set, verifies whether the value has a match, and potentially formats the value (as appropriate) for the property.

A property of mode Single Value, Value List or Value Group can use table validation to constrain an input value to match one of the specified values or a pattern of values. You define a table of data that describes what values are valid for this property.

To use table validation:

  1. Select one of the values in the Table type drop-down list (other than the None value). The appropriate fields for that type appear in the form.
  2. Complete the fields appropriate for the selected Table type value. These fields define the set (table) of acceptable values. See the following sections for details of the fields used for each type of table validation.
CAUTION:
If you update an existing property and revise the table details, additional steps may be necessary. See Revalidation is necessary after certain property updates in More about Properties.

Basics

Note: Table validation is part of property and page validation. If an input value for a property doesn't have a match in the set of table elements, the property name and the invalid value remain on the clipboard, but during validation the system adds a message and error text to the clipboard page that contains the property. The presence of the message ordinarily prevents the system from saving the clipboard page (which contains invalid data) into the database. The message does not prevent an activity from reading or using the (invalid) property value.

Although the value is compared with the table elements a case-insensitive way, the system corrects the case. For example, if the values recorded in a Local List on this tab are all lowercase, a user can enter at runtime the value in uppercase, mixed case, or lowercase letters. The system accepts a matching value but converts it to lowercase.

Display-only option

Note: This check box appears when the selected Table type is Field Value, Class Key Value, Remote List, or Prompt List.

Local List table validation

Select Local List as the Table Type when your property value is permanently limited to a modest number of known values in a single language. (To accomplish a similar presentation with localized values, specify Prompt List instead of Local List.)

If there are to be a large list of values that are expected to change frequently, rather than having to maintain a long list here, use the field value table validation method instead.

Typically when using this option, the Control field is set to either the PromptSelect or RadioButtons standard control, so that at runtime, a selection list displaying the specified acceptable values is presented to the user.

You cannot use a Local List if the Property Type field is Password, TrueFalse, Date, or DateTime.

Note: When Local List is selected, a Table Values array appears. In this array, specify those values that are acceptable input for this property. Enter each value as a literal. Order is not significant.

Using Local List is the simplest way to show a list to the user at runtime for the user to make a selection. Localization of the values is not supported for a Local List. The value displayed at runtime is the value stored in the clipboard.

Field Description
Table values You need not leave a blank entry to allow the property value to be empty.

If you enter a value in the first row, it appears at runtime as the default value, and might be too easy for users to overlook. To encourage users to make a non-blank selection at runtime, leave the first entry blank. To require users to make an explicit choice, leave the first row entry and mark the corresponding field on a user form as required.

Note: To encourage users to make accurate, fast selections, list the values in a meaningful order, such as alphabetically, or in a natural sequence (for example S, M, L, XL, XXL).
Note: If, at runtime, a user input or other processing assigns a non-null value to the property that is not on this list, the value is accepted but, when the page is later validated, the system adds an error message to the page on the clipboard.

Field Value table validation

Select Field Value as the Table Type when the set of valid values:

  • Contains more than a few hundred values or the values are expected to change frequently, and
  • The values are available at runtime within the keys of field value rules

For this method, you specify only the first two key parts of the set of field value rules. At runtime, the system locates the actual literal values by using the specified two key parts to locate the field value rules that contain the values. If a match for the input value is not found among the field values, the validation fails and the system returns an error.

Typically when using this option, the Control field is set to PromptFieldValue, to present a user with a fixed list of selection values to select from at runtime.

Field Description
Field Value Description  
Class Select a class that is the first key part ( Applies To class) of one or more field value rules, where the third key part of the field value rule (the Field Value on the Field Value rule form) defines an acceptable input value for the property. (The class specified here need not match the Applies To key part of this property.)
Field name Enter the second key part of one or more field value rules that have the specified Class as their first key part.

This key part of the field value rule is usually a Single Value property in that class. Its name does not have to match the name of the property you are defining.

Note: The field value — the third key part — of a field value rule is limited to 64 characters.

Field value examples

For example, the standard property Work-.pyRootCause uses field value rules to define possible root causes for an exception-oriented work item.

The first key part of the field value rules that provides the acceptable values is Work- (the Applies To class for these rules). The second key part is the literal pyRootCause (the Field Name for these rules).

The final key part of these field value rules varies to provide specific values. Recommended values for the pyRootCause property are Conduct, Duplicate, Facilities, Finance, Policy, Product, Service, and User Error. These values are predefined through standard field value rules.

You can add field values as the application evolves, and the values can be updated without having to edit the pyRootCause property itself.

In comparison, the standard property Work-.pyStatusWork also is restricted to values defined by field value rules. However, for this property, an activity and a control enforces the restriction, rather than table validation.

Reviewing field value rules for the property

After you save the property, you can open the Property Explorer from the Property form's Advanced tab to locate and review the list of existing field value rules that match the specified field value class and field name:

  1. Click the Advanced tab. Click the Explore button at the bottom of the tab to start the Property Explorer in a new window
  2. On the Property Explorer, click the Field Values tab.

Class Key Value table validation

Use Class Key Value to use a concrete class, rather than field value rules, as the source of acceptable values for the property. Class Key Value specifies a class to validate the input values against.

When you select Class Key Value, Table Description fields appear. Complete them to identify a range of keys in a class other than the Applies To class of the property you are defining.

Field Description
Table Description  
Validation class Select a concrete class that stores the set of acceptable values.
Depending on the number of keys defined for the class (in the Keys array of the class's rule form, certain conditions must be met:
If class has: Then:
One key value Corresponds to the valid value for the property you are defining.
Two key values The first key value must act to group values for the second key.

The second key value corresponds to a valid value for the property you are defining.

Three key values The first key value must correspond to a class (the standard property pyClassName.

The second key value must act to group values for the second key.

The third key value must act to group values for the third key.

Subset name (when appropriate) Optional if the Validation class has only one key. Required if the Validation class has more than one key. Enter the value of the key in the Validation class that represents the subset that contains the list of acceptable values.

For example, if a class Data-CustomerTerritory has key parts for state code and county name, to restrict input values for a property at runtime to county names in New York state, enter Data-CustomerTerritory as the Validation class and "NY" as the Subset Name .

If you leave this field blank, the system uses the Property Name of the property you are defining in the Property form as a default. (The Property Name is the second key part of this property.)

Class Key Value examples

Single key example: The standard class Rule-Obj-Class is used to validate values entered into the Applies To field in the Create form when creating a new rule. To validate that input entered into the Applies To field is a valid, existing class, the property associated with that field in the New dialog specifies Rule-Obj-Class as the Validation class . The Rule-Obj-Class class has one key defined in its Keys array.

Two key example: A class Data-CustomerTerritory has two keys defined in its Keys array — state code and county name. To restrict input values for a property at runtime to county names in New York state, specify Data-CustomerTerritory as the Validation class and "NY" as the Subset Name .

Three key example: The standard class Rule-Obj-FieldValue used to validate properties has three keys defined in its Keys array. The first is pyClassName, the second is pyFieldName and is used to group the values for the third key ( pyFieldValue ), which are the allowed input values.

The Class Key Value validation method is a generalization of the Field Value method. For example, a Pega Platform system has fifty-one (51) standard field value rules that identify codes for the fifty United States and the District of Columbia. These field value rules have Data-Party as the first key part (the Applies To ) and pyState as the second key part (the Field Name ). The values for the third key part of these field value rules range from AK (for Alaska) to WY (for Wyoming).

Two standard properties, Data-Party.pyHomeState and Data-Party.pyWorkState, use these field values through the Class Key Values method. Those properties specify:

  • Rule-Obj-FieldValue for the Validation Class
  • pyState for the Subset Name

At runtime, if your system contains other field value rules in this key range (in an application RuleSet) such as PR for Puerto Rico, the system uses them as acceptable values for pyHomeState and pyWorkState also.

Remote List table validation

Choose Remote List when there are a large number of objects to be validated against (such as countries of the world) that you might not want to enter as individual values, or when the data changes frequently, but is available at runtime as the keys of a certain known class.

Whereas Class Key Value specifies a class to validate the input values against, Remote List specifies a particular instance of a class to validate against.

After you select Remote List, complete the fields that appear.

Field Description
Class of instance Select the class of the instance. After entering the class, you can skip to complete the Keys of instance fields and then return to complete the Reference to list or group field.
Reference to list or group Select a property that has one of the List or Group modes — Value List, Value Group, Page List, or Page Group.
Reference in each to scalar property Optional if the Reference to list or group is Value List or Value Group. Specify either an index value, a reference to one element of an aggregate property, or the Use-Group-Name keyword.
Your choices depend on the Property Mode of the property in the Reference to list or group field.
Mode Choices
Page List or Page Group Identify a property that contains a value that is an index that identifies the specific page that contains the list.
Value List Leave blank.
Value Group Leave this field blank to edit against each value in the Value Group, or enter the keyword Use-Group-Name to indicate that the index values of the Value Group are the allowed values.
Reference to localized value Leave blank.
Keys of instance Click the Add a row icon to add a key. This array identifies the instance that contains the property value that contains the set of values. Identify keys in the correct order, matching the class definition.
Key field Enter the name of a property that is a key part of the class.
Value Enter the value for this key part for the instance.

Prompt List table validation

Select Prompt List and complete the associated fields to provide a mapping between a list of text values used in the property value internally and corresponding text values presented on input or output. For example, the text values presented at runtime can be human-readable labels that end users see and choose from, while the corresponding stored values can be shorter, easy-to-machine-reference values.

When you use Prompt List as the Table type , specify PromptSelect for the Control . At runtime, a selection list displaying the Prompt value values is presented to the user. If the values have been localized using the Localization wizard, the appropriate translated values are presented.

Prompt List tables are used when you want the actual value stored in the clipboard to be different from the value presented to the user 'on the glass' at runtime. This choice allows users to see information from the Prompt value column on both input and display, while the system internally maintains the corresponding value from the Standard value column. For example, when the Standard value specifies a short value like EDate, the corresponding Prompt value can be a more human-readable value like Date to complete this task. The Standard value is the value stored in the clipboard, and the Prompt value is the value displayed to the user at runtime.

This feature is most useful to support localization. The Localization wizard localizes the values specified in the Prompt value field. When the wizard runs, it creates the appropriate field value rules for the Prompt Value entries, and then those field value rules are used to hold the translated text.

Field Description
Prompt values Click the Add a row icon to add a prompt. This array identifies the mapping of the internal values to the runtime-presentation ('on the glass') values.
Standard value Enter a value. The system stores this value internally as the property value.
Prompt value Specify the runtime-presentation alternative value. Use the SmartPrompt to select from available field value rules.