Property form - Completing the General tab

The General tab for properties has three sections: Property Type, Data Access, and Display and Validation.

Property Type

A property has one of eleven modes. Each is defined in the table below. Three are string-based modes, three are page-based modes, and five are modes used with Java objects. The appearance of the General and Behavior tabs depends on the mode chosen.

Use the Property Mode selection box to choose a mode. The property mode determines how the system represents the property data. After you select a mode, consult these topics to complete the General tab fields:

Mode Description
Single Value Select Single Value to create a property that can contain a single text string value. Text, numbers, dates, Boolean values, and amounts are stored in Single Value mode properties.

The internal value of a Single Value property is String, not Single Value. Single Value property values correspond to objects of the Java.lang.String Class.

For example, use this mode to create a property that can hold a birth date. The standard Single Value property named Work-.pyID holds the system-assigned unique identifier for a work item.

Value List Select Value List to create a property that can contain an ordered list of single values.

If you create a Value List property named LetterSent, you can use it to hold a list of values. For example, you can use an activity or an HTML form to set LetterSent(1) to Mom and LetterSent(2) to Dad.

After setting these values, the LetterSent Value List contains LetterSent(1) and LetterSent(2).

An example of a standard Value List property is Work-.pyOpenWindows.

Value Group Select Value Group to create a property that can contain an unordered group of single values. (Rare.)

If you create a Value Group property named Birthday, you can use it in your future configuration to hold a group of values. For example, you can use an activity or an HTML form to set Birthday(Bob) to July and Birthday(Mary) to September. Birthday(Bob) and Birthday(Mary) become elements of the Birthday Value Group.
Page Select Page to create a property that can contain an embedded page as its value.

For example, a Page mode property named Originator can contain information about the originator of a work item, such as the originator's name, account number, and so on.

An example of a standard Page property is Work-.pyIndexes.

Page List Select Page List to create a property that can contain an ordered list of embedded pages.

For example, a Page List property named Contacts can contain the pages Contact(1), Contact(2), Contact(3), and so on.

Work-.pyFlowActionCosts is an example of a standard Page List property.

Page Group Select Page Group to create a property that can contain an unordered group of embedded pages.

For example, the standard Page Group property named Work-.pyWorkParty can contain pyWorkParty(Lawyer), pyWorkParty(Customer), pyWorkParty(Staff), and so on.

Java Object Some properties with this mode can be saved as persistent data in the PegaRULES database. If the Java class of the Java object instance implements the Serializable interface, and the value can be validated, the Pega Platform can persist instances of the Java class with other clipboard data.
Java ObjectList
Note: Select Java ObjectList to indicate that this property can contain an array of references to instances of Java objects. The first element in the array is identified by the 1 subscript, not the 0 subscript.
Java Object Group
Note: Select Java Object Group to indicate that this property can contain an unordered group of references to instances of Java objects.
Java Property Select Java Property to indicate that this property represents a single property of a Java class that defines an external Java object. Typically, properties of this mode are generated by the Import JavaBeans wizard when you use it to import a Java class and implement in the Pega Platform the data model of an external Java object.

For information, see Working with Java Objects, a document available in the Integration section of Pega Community.

Java Property List Select Java Property List to indicate that this property represents an array property of a Java class that defines an external Java object. Typically, properties of this mode are generated by the Import JavaBeans wizard.
CAUTION:
If you update an existing property and change the Property Mode , additional steps may be necessary. See Revalidation is necessary after certain property updates in More about Properties.

Data Access

Use this section to configure automatic data access and persistence settings.

For all property types except Page and PageList

Section Controls
Data Access Select a Data Access Type. The options are:
  • Manual - At run time, the user adds data to this property through the UI. Data transforms and other rules may be required to support this workflow.
  • Automatic reference to class instance (linked) - This property holds the value of a key to an Operator ID, Organization, Access Group, or other data object that presents data from that object anywhere in the system.

If you choose Automatic Reference to class instance (linked), further fields appear:

  • Provide a linked class in the Linked Class field
  • Select a Source Property in that class to populate the property you are editing. The keys for the linked class then appear.

    If there is only one key, the value of your property becomes the key used to open the object at run-time. If there is more than one key, the source properties become input fields where you may enter values for the keys or properties that will contain the appropriate values at run time.
Data Persistence The system saves the property data with the work item for which it is used by default. Check the "Don't save property data (transient)" check box to prevent the system from saving the data with the work item.

For Page and PageList properties

Section Controls
Data Access Select a data access option from those provided:
  • Manual - At run time, the user adds data to this property through the UI. Data transforms and other rules may be required to support this workflow.
  • Refer to a data page - This is the recommended option. When data page parameters change and a reference to a non-parameter value is made, the system loads a new data page. Reads from and writes to the property occur on the new data page.
  • Copy data from a data page - Only use this option if you need to copy the data into your case. When parameters to the data page change and a non-parameter value is referenced, a new data page is loaded and copied into this property. Interactions with the property happen on the copied data.

If you choose "Refer to a data page", further fields appear:

  • For a Page property, you must choose a Data Page whose structure is "Page".
  • You can check the Load each page in this page list individually check box to have the system retrieve each embedded page in the PageList separately. You must specify a data page whose structure is "page".
  • Select a data page in the Data Page field, or click the Edit icon to the right of the field to create one.
  • If fields appear below the Parameters title, specify for each parameter a value, or a property that, at run time, contains the value to assign to the parameter. The parameters are passed to the data page for keyed page access.

If you select Copy data from a data page , you can select a data transform in the Data Transform field that appears. This allows you to copy only a subset of the results on a data page into the property. To create a new data transform, specify a name and then click the Edit icon to the right of the field.

Note: When you select Copy data from a data page, be aware of the following behavior if the value for a parameter is missing:
  • If you are copying to a property of page structure, the property behaves as if no relevant reference exists and retrieves no data from the data page. The property displays any data the user has set manually. Once there are values for the keys, the property autopopulates from the data the data page provides and overrides any existing data the user has provided.
  • If you are copying to a property of page-list structure, the property behaves as if no filters are applied and copies the complete list of data (.pxResults) provided by the data page. Once there are values for the keys, any additional list elements that were created earlier are removed and the data in any existing list-elements is overridden.
Data Persistence
  • For property types with manual data access selected, the system by default saves the property data with the case for which it is used. Check the Don't save property data (transient) check box to prevent the system from saving the data with the work item.
  • For Interact directly with automatically loaded data pages , the property is a reference.The user can choose at run time to save or not save parameters to the data page.
  • If you select Copy automatically loaded data page into this property , the system follows your direction. There is no way to discard property data at the time of save. Select "Interact directly with automatically loaded data pages" if you wish to discard property data when saving.

Display and validation

In this section, you configure which control displays the property and, optionally, validation of input data.

To configure the UI control:

  1. In the UI Control field, specify the control that displays the property.
  2. If the control takes parameters, click the Parameters link and provide values for the parameters in the Parameters dialog.

For information about configuring validation tables, see Property form General tab — Configuring validation.

Other ways to associate values with properties

You can use other methods to associate a value with a property, including:

It is also possible to use any of the Property-Set methods in an activity, but it is not recommended to use this method.

Note: The values of many standard properties, such as pyUserName (which holds the identifier for the current user), are set automatically at log-in.