Understanding the pzInsKey property (handle)

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:

• Alphabetic characters are all uppercased.
• CLASS is the class of the instance, or of the class group for objects (such as work items) that belong to a class that is a member of a class group.
• A single space precedes the next key part.
• CLASSKEY is the Applies To or class key part of the instance, if present
• An exclamation point character separates this key part from later parts.
• NAME is the name of the instance, which may involve multiple key parts.
• A number sign (#) or octothorpe precedes the date.
• YYYYMMDD is the creation date of the instance.
• A capital T precedes the creation time.
• HHMMSSTTTTMMM is the creation time after midnight in hours, minutes, and seconds (6 digits), a decimal point, and milliseconds (3 digits), based on GMT (Coordinated Universal Time).

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

Because 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.

When 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.

A 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 (). 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.

	Archive tools, Coordinated Universal Time, instance, internal key
	Choosing rule and data instance names Obj-Open-by-Handle method Working with the PegaRULES database — Tables and columns

Concepts