General tab on the Class form
Use the General tab to define the class inheritance and database access.
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
Otherwise select |
| 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:
If this concrete class is derived from the Work- base class or the History-Work- class, select:
Note: Concrete classes created in releases prior to PRPC Version 6.2 might not
conform to this restriction.
As a best practice, choose If you create a class is derived from the Work - base class,
and you selected For an external class created through the External Data Table wizard, the
initial value is |
| 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 Valueproperties of typeTextwith 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, orDoubleas 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 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 selected 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:
|
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:
- Save the class rule with the Keys array empty; no keys defined.
- Define properties that are to form the keys in the class in the normal way.
- Open the class rule again, and enter the key properties into the Keys array of the General tab.
- Save the class rule again.