Back Forward Understanding the pzInsKey property (handle)

Concepts and terms

A handle, sometimes known as an internal key, is a permanent representation of an object instance key in an external form. A handle uniquely identifies the instance, though in a format that differs from the normal presentation. Internally, the pzInsKey property holds the handle value for the object.

A handle identifies the class, certain key parts, and (for rules and some other classes) the creation date and time of a single instance. Handle values are in the format:

CLASSNAME CLASSKEY ! NAME #YYYYMMDD T HHMMSSTTTTMMM GMT

where:

The date and time portions are present only on rule instances. For most database tables, a handle may be up to 255 characters long.

Notes

CautionBecause it often contains a date and time, the system computes a handle value only when the Obj-Save method executes. Before the object is first saved, the pzInsKey property is undefined.

This key uniquely identifies an instance. The pzInsKey column is the primary key of all but a few tables in the PegaRULES database.

In contrast, the key parts defined in the class rule (the Rule-Obj-Class instance) are collectively known as the visible key.

NoteWhen reviewing a handle for a rule, the creation date and time may appear to differ from the creation date appearing in the History tab of the rule form. This History tab date and time are converted to display in the time zone of the PRPC server, not GMT.

CautionA handle for a rule does not explicitly identify a RuleSet name or version value. Don't assume that the most recently created instance is the highest version. PRPC does not require any relationship between versions and creation dates. For example, an application developer can intentionally place a new rule into a lower version.

Example

For example, this handle identifies an activity named ProcessAssignment that is associated with the Assign- base class. This rule instance was created on April 10, 2001 at 23:02:19 Greenwich Mean Time:

RULE-OBJ-ACTIVITY ASSIGN- PROCESSASSIGNMENT # 20010410T230219.752 GMT

Where handles are used

The Archive tools uses handles as file names for extracted rule instances as XML documents. The number sign character (octothorpe) # replaces the exclamation mark character ! in XML file names. Certain queries display rule instances keys as handles, and the My Rules explorer identifies rules and data objects by handles. In an activity, the Obj-Open-by-Handle method uses a handle to bypass rule resolution and open an exactly specified rule instance.

In most activities, use the Obj-Open method to copy a rule from the database to the clipboard. This causes the system to use the current RuleSet list and other standard facilities to find and open the most context-appropriate rule.

In unusual situations, use the Obj-Open-by-Handle method, to open a specific instance even if this instance is not the one found by rule resolution.

Function rule

You can call the standard function rule pxDoesHandleExist() in the Utilities library to determine whether a specific instance exists in the database, as an alternative to creating an activity that uses the Obj-Open method and tests whether the instance was or was not found. The pxDoesHandleExist function accepts as a single parameter a text value containing the candidate handle, and returns true or false. The clipboard is unchanged. The function execution is faster than using an activity.

How to learn the handle of an object

To learn the handle of any Rule- or Data- object that has a corresponding form, open the instance using the form and click the RuleData button (Rule Data button). Find the pzInsKey property in the resulting browser window.

To learn the handle of other objects, first open the object to the clipboard. Like other pz properties, the pzInsKey property is not visible on the initial display of the Clipboard tool. Click Show XML to see the full contents, and search for pzInsKey.

pxInsHandle property

The property pxInsHandle is deprecated and not guaranteed to be equal to pzInsKey in all cases.

Definitions Archive tools, Coordinated Universal Time, instance, internal key
Related topics Choosing rule and data instance names
Obj-Open-by-Handle method

Working with the PegaRULES database — Tables and columns

UpConcepts