Class keys

When you define concrete classes, you can add keys to identify the classes. You can add the keys when you create a class, or you can update the keys later.

Every instance of a concrete class includes a key formed from the value of the properties that the class contains. The value is unique within the class or class group. For example, your system can contain only one instance of the Data-Admin-Operator-ID class with an ID value of SampleID. Similarly, your system can contain only one HTML fragment rule named MyFragment in the same ruleset and version.

The properties that form the key might apply to the concrete class itself, or to a parent class. For rule instances, the system appends the ruleset and version as part of the internal key.

Pega Platform looks in three places to learn which property values to connect to, and in what order, 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 connecting the values of the properties identified in that array.
  • If the Keys array of a class is empty, the system uses class inheritance to locate a superclass for which the Keys array on the Class form is not blank. When the system finds such a class, it connects the values of the properties in that Keys array, and forms 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, the system ignores any information in the Keys array of the Class form.
When you add keys to a class, consider the following factors:
  • The system creates both a new class and single value properties of the Text type when you enter the property names into the Keys array, before you save the Class form for the first time. If you want to apply one or more already-defined properties as key properties to a super class of this class, enter the already-defined properties after you save the Class form.
  • 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 might 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. Avoid using any other properties in the key.
  • For external classes, use of properties with a Type value of Date, Time, DateTime, or Double as key parts might introduce rounding or uniqueness issues. Review the data representation on the external database that you use, to confirm that it maps one-to-one with the Pega Platform representation.
  • If two or more properties form the key, the order of rows in the Keys array is significant. Consider which order is likely to produce a natural or frequently presented sort order in reporting or searching.