General tab on the Class form

Use the General tab to define the class inheritance and database access.

Note: After you save this form, your entries for many fields are permanently set and you cannot change them later. However, the Keys array is an exception. If you save the form with the Keys array blank, you can update the Class form later and specify the Keys array to reference properties that are defined to apply to this class.

How the system forms key values from the properties in the Keys array

Every object saved to the PegaRULES database — that is, every instance of a concrete class — must have a key formed from the value of properties that is unique within the class or class group.

For example, your system cannot contain two instances of the Data-Admin-Operator-ID class with an ID value of [email protected]. Similarly, your system cannot contain two HTML fragment rules named MyFragment in the same ruleset and version.

The properties that form the key may apply to the concrete class itself or to a parent class. (For rule instances, the ruleset and version are appended as part of the internal key.)

Pega Platform looks in three places to learn which property values, in what order, to concatenate to form the unique key. The system assembles keys the first time it saves an instance:

  • For a concrete class that does not belong to a class group, the system first examines the Keys array of the Class form. If this array is not empty, it forms a key by concatenating values of the properties identified in that array.
  • If the Keys array of this class is empty, the system uses class inheritance to locate a superclass (an ancestor) for which the Keys array on this tab of the Class form is not blank. When such as class is found, it concatenates the values of the properties in that Keys array to form the key.
  • For a concrete class that does belong to a class group, the system forms a key based on properties in the Keys array of the Class Group form. As a result, any information in the Keys array of the Class form is ignored.

Completing the Settings fields

The appearance of the General tab changes depending on whether you enter a class group, keys, or neither. You cannot enter both a class group and keys. If you enter a class group, Pega Platform uses keys defined in the class group.

When you save the Class form, most of the choices you made become permanent. For example, you cannot later select or clear the Find by name first (Pattern)? check box to use, and you cannot change properties entered in the Keys array.

Field Description
Select Indicate whether this class is to be abstract or concrete. Both abstract and concrete classes can have subclasses.

If this class is to have persistent instances, select Concrete. (You cannot select Concrete if the class name ends with a hyphen.)

Otherwise select Abstract.

Created in Version Identify the ruleset version number that applies to this class. The Archive tools depend on the version you enter here. The Export Archive tool includes this class instance if you export this ruleset version or a higher-numbered version.

However, version information in class rules is not used for rule resolution. You cannot define multiple class rules with the same class name but different versions.

Complete this field when first creating a new class (with New or Save as). Alter this field later in rare circumstances only.
This Class Select one:
  • belongs to a class group to indicate that: (1) the key format of this class is identical to the key format of another class, (2) an existing class group named identically to the other class exists, and (3) you want to store instances of this class in the same table as instances of other member classes. Typically, choose this option for a concrete class derived from the Work - base class.
  • does not belong to a class group to indicate that database storage of this class is determined by the class inheritance and database table data instances.
  • is a class group to have Pega Platform create a class group data instance with a name identical to the name of this class, This allows other classes to share a database table associated with instances of this class.

If this concrete class is derived from the Work- base class or the History-Work- class, select:

  • is a class group or
  • belongs to a class group.
Note: Concrete classes created in releases prior to PRPC Version 6.2 might not conform to this restriction.

As a best practice, choose belongs to a class group for any concrete class that is derived (according to pattern inheritance from a class that has This class set to is a class group. Otherwise, warning message may appear when you save the Class form. Although possible, avoid creating Database Table mappings for subclasses of a class group that differ from the Database Table for the entire class group.

If you create a class is derived from the Work - base class, and you selected is a class group, review the Description for this class carefully; the Description text is visible to application users. See More about Class rules.

For an external class created through the External Data Table wizard, the initial value is does not belong to a class group. Do not change this value.

Encrypt BLOB Select to cause Pega Platform to encrypt the Storage Stream of each instance of this concrete class when saved to the PegaRULES database, and to decrypt the Storage Stream when an instance is retrieved from the database.

This check box appears only for concrete classes. It affects only instances of exactly this class, not instances of any subclasses of this class.

Note: Determine whether you application is to use this feature early during the development project. You cannot select or clear this check box if the database already contains instances of the class.

Additional configuration is required to set up this capability. See Storage Stream encryption of selected classes.

About the Class Group field

This field appears only when is a class group or belongs to a class group is selected in the This class field. Confirm that the class group identified is the one expected.

Field Description
Class Group Optional. If you selected belongs to a class group, select a class group (an instance of the Data-Admin-DB-ClassGroup class) from the list. A class group — a data instance — has the same name as its first or defining container class.

The name of the class group you choose must match an initial portion of the class name.

Choose this option when defining one or several concrete classes that define types of work items to be stored and processed as part of a single application, or the corresponding class derived from History-Work-.

If you enter a class group, leave the Keys array empty. In this case, the class group instance defines a common key structure used by all associated classes.

Completing the Keys fields

The keys array appears only for concrete classes that either define a class group or that are do not belong to a class group.

If the Keys array appears, in many cases, you can leave it blank, at least when you first save the Class form:

  • To create new Single Value properties of type Text with this class as the Applies To key part, enter the property names into the Keys array before you first save the Class form. When you save the form, the system creates both the new class and properties.
  • To use one or more properties already defined to apply to a superclass of this class as key properties, do not enter them before you first save the Class form. Save the Class form once, and then use SmartPrompt to select the properties that form the key.
  • For concrete classes derived from the Log- base class, the property pxCreateDateTime is usually the final (or only) key part. In some high-volume systems, two log events may occur in the same millisecond. If this can occur in your Log- class, choose additional properties to ensure uniqueness.
  • For concrete classes derived from the Index- base class, enter the properties pxInsIndexedKey, pxIndexCount, and pxIndexPurpose in that order. No other properties can appear in the key.
  • For external classes, use of properties with a Type value of Date, Time, DateTime, or Double as key parts is permitted, but may introduce rounding or uniqueness issues. Review the data representation on the external database to confirm that it maps one-to-one with the Pega Platform representation.
Field Description
Keys If two or more properties are to form the key, the order of rows in this array is significant. Consider which order is likely to produce a natural or frequently presented sort order in reporting or searching.

For example, consider a class named Data-County, with a key formed from a county name (such as Suffolk, for Suffolk county) and state code (such as MA for Massachusetts). Assuming that reporting requirements present county information within state, a natural order for the two key parts is state followed by county.
Name Optional. Leave blank if the concrete class is a subclass of a superclass that corresponds to a class group. Also, leave blank if a parent (or higher superclass) of this class is concrete and the key structure of this class is to be the same as the key structure of the parent.

Identify the property or properties that together define a unique key for objects of this class. If the property or properties that are to form the key are not yet defined, you can create them automatically the first time you save the Class form by entering a name here.

If the properties that are to make up the key are already defined (in a superclass), do not enter them initially. Save the Class form once, then use SmartPrompt to select them as rows in the Keys array, and then resave the Class form.

Typically, the key of an object also determines how it is identified when locked. In the unusual case that a different key structure is needed, you can define a separate lock string on the Locking tab.
Caption Optional. For concrete classes derived from Rule- or Data- for which a Rule-File-Form is present, this text appears as field labels in the New dialog box.

In other cases, you can enter text to document why you chose this property to be part of the key; the information you enter appears only in this field.
Automatically generate a unique ID for records of this type This checkbox appears when you have entered one key field. If you want instances of this class to be unique using this one field, and you want the system to automatically supply a globally unique value for new instances, select this check box. Selecting this check box also changes the key name to pyGUID.

Completing the Rule Instances of this class fields

These four check boxes appear only for concrete classes derived from the Rule- base class, with a few exceptions. They determine which aspects of the full rule resolution algorithm the system uses to find rules of the new rule type. See How the system finds rules through rule resolution.

Field Description
Allow multiple versions with the same key values? (rule resolution) When selected causes the system to allow multiple rules of this rule type to have the same name, distinguished by ruleset or ruleset version. If this check box is selected, at run time Pega Platform uses the ruleset list part of the rule resolution algorithm for this class to select a rule at run time.
Allow selection of rules based on property values? (circumstance-qualified) When selected, causes the system to allow rules of this rule type to have circumstance-based qualifications. If this check box is selected, at run time Pega Platform uses circumstance-based processing at run time to select a rule, and these fields appear on the Save As form. See circumstance.

This field appears only when the Allow multiple versions field is selected.
Allow rules that are valid only for a certain period of time? (date range availability) When selected, causes the system to allow rules of this rule type to have time-based qualifications. If this check box is selected, Pega Platform uses time-based processing at run time to select a rule, and these fields appear on the Save As form. See time-based rules.

This field appears only when the Allow multiple versions field is selected.
Use class-based-inheritance to arrive at the correct rule to execute? When selected, causes the system to cause the system to search up the class inheritance structure (using both pattern and directed inheritance) to find rules of this rule type. If this check box is not selected, at run time Pega Platform expects to find the rule in the current class only, not by searching through super-classes.

Completing the Class Inheritance fields

Indicate how this class inherits rules from super classes.

Field Description
Find by name first (Pattern)? Select to cause the system to use pattern inheritance before it uses directed inheritance when finding rules at run time. Pattern inheritance searches superclasses based on prefixes of the class name that end in a hyphen.

Clear this check box to bypass pattern inheritance. Directed inheritance always occurs for all rule types with an Applies To key part.

If you selected belongs to a class group, this check box is selected.

After you save a Class form, you cannot change this setting.
Parent class (Directed) Identify the class that is to be the immediate parent of this class:
  • If you don't select the Find by name first (Pattern)? check box, at run time as part of rule resolution processing, the system searches the parent class and its parent and so on when it cannot find a rule in the current class.
  • If you select the Find by name first (Pattern)? check box, the system during rule resolution searches classes with derived class names before it searches the parent class identified in this field.

If you selected is a class group in the This class field, enter Work- or a class that is derived from the Work- base class here. (Or, enter History-Work- or a class that is derived from History-Work-, if you create a class to hold the history of work items. Such History-Work- classes are ordinarily created automatically.)

If you enter the longest possible prefix of this class ending in a hyphen, you can select or clear the Find by name first (Pattern)? check box, with no difference in rule resolution behavior or results. For example, if this class is named Work-Object-Mortgage and the parent class is to be Work-Object-, Pega Platform performs the same search regardless of the check box setting.

CAUTION:
Do not assume that the "inherits from" relationship is transitive. Because only one Parent class to inherit from (Directed) value is used by a rule resolution, it is possible that class C inherits from class B, and B inherits from A, but C does not inherit from A.
Note: You cannot create a class derived from the Code- or System- base classes. These base classes are reserved.

Testing the class-to-database table mapping

For a concrete class, you can test the database connection and learn the table structure.

Test Connection After you save the Class form, click to confirm that the database instance ( Data-Admin-DB-Name ) and database table instance ( Data-Admin-DB-Table ) are working as intended. The test confirms that Pega Platform can access the database and displays the database table that will contain instances of this class.

Results appear in a new window, identifying the database and database table that correspond to this concrete class, and whether the class is an internal or external class.

This button appears only for concrete classes.

Note: For the test connection to work, the JDBC JAR file for the database platform must be present and included in the classpath and the prconfig.xml file must contain an entry for the database driver. For example:

<env name="database/drivers" value="org.postgresql.Driver" />

How to include properties in a class as key parts of that class

As you complete the Key Name fields while adding a class, you can only reference existing properties. If a key part for your new class is a property that will apply to the new class, you cannot create the property until after you create and save the class rule.

Take these steps to work around this circular situation:

  1. Save the class rule with the Keys array empty; no keys defined.
  2. Define properties that are to form the keys in the class in the normal way.
  3. Open the class rule again, and enter the key properties into the Keys array of the General tab.
  4. Save the class rule again.