The handle of an instance is a unique key, in an internal format, assembled by the system that identifies an instance in the PegaRULES database. It may differ from the visible key generally used to identify instances. (Every instance has a unique handle, but more than one instance may share the same visible key.) For rule instances, the handle includes system-generated identifying values (including the create date and time) that make it unique.
Use the Obj-Open-By-Handle method only if you can determine the unique handle that permanently identifies which instance to open. Otherwise, use the Obj-Open method.
Rows of a view (rather than in a table) in the PegaRULES database do not have a handle. This method cannot be used with classes corresponding to views.
When used on a primary page, this method clears any data on the page and reuses its name
and position in an embedded
An external class (defined through the Connector and Metadata wizard ) may not contain one property that can serve as a handle. To support the Obj-Open-by-Handle method with external classes, a substitute string is assembled from the key columns of the table.
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.
This method has four parameters:
Enter the handle that identifies the instance to be opened as a literal or a
property reference. This corresponds to the value of the
property for an internal class, and a simulated handle for an external class.
Because the handle is lengthy and not easily displayed, it is often easier to identify it by a property reference, rather than attempt to enter the handle by typing. See How to Capture... below for details.
Select this box if you plan to change and save or delete the instance.
Your session cannot lock the object unless your access role includes the ability to update objects of the class.
You cannot lock an object unless the Allow Locking? check box (on the Locking tab of the Class form) for the object class is selected. (If the class is part of a class group, the Allow Locking? check box on the class named for the class group is applicable.)
Select this box to cause a lock to be released when your changes are completed
through the Commit method.
In most cases, select this box if you selected the Lock box. In the unusual case that you want to retain the lock after Commit (perhaps because additional changes are expected), your activity can later use the Page-Unlock method to release the lock.
Optional. As a debugging aid, identify the name of a page to be created by this
method to hold the results of the locking attempt when it fails. The page, of class
System-Locks, contains the following properties:
If the Obj-Open-By-Handle fails to acquire a lock, this page is created and can be viewed with the Clipboard tool or the Tracer.
By convention, this page is named
This method accesses the PegaRULES database and finds the unique instance that matches the handle. It copies the object's properties and values into a new clipboard page (identified in the Step Page column, or the activity's primary page if no step page is specified).
If it finds the specified step page, the system clears any data that is on it and re-uses it. If the step page is not found, the system creates it. If the Step Page field is blank, the system clears and reuses the primary page of the activity.
If the Lock check box is selected and the requestor has permission to update objects of this class, the system locks the instance.
If the LockInfoPage parameter is not blank, the system creates a page of that name and reports results through property values on that page.
Fail and Warn conditions
These situations cause the method status to be
- If the instance is locked by another requestor, the object is opened to the clipboard but the method returns a Fail status.
- If the key supplied does not match the key of an instance in the database, the system creates a page of the indicated class that is empty except for the pxObjClass property, and returns a Fail status.
f you selected the
parameter (on the
tab of the
form or in some
cases the Class Group form) but the class does not allow locking, the object is opened,
but the method returns a
If you selected the
parameter but at runtime the requestor's
access role does not allow the requestor to update objects of that class, the object is
opened but without a lock is, and the method returns a
To avoid overwriting an existing page
You may want an activity to check whether a page of a certain name exists before you open a new page.
In the precondition to the activity step, enter the following:
= @PageExists("myPage", tools)
where myPage is the name of the clipboard page.
You may also want to check whether the page on the clipboard is the same as the one you want. For example, your activity performs an Obj-Open-By-Handle method and the handle is stored in a local variable Local.strHandle. After the PageExists check, perform the following check:
@GetInstanceHandle("myPage", tools) == Local.strHandle
If both checks are true, the page on the clipboard is the same as the one you plan to open, so you can skip the step.
How to capture a handle in a property reference
image/img00218.gif You can obtain a property reference by creating and running a list report (using the Obj-Browse or Obj-List method) earlier in your activity, before the Obj-Open-By-Handle step.
Enter the name of a list rule (instance of the Rule-Obj-List rule type) in the RuleObjList parameter of a step that uses the Obj-List method.
After you execute that step, the results appear in embedded clipboard pages under the
page. Each instance listed (pxResults(1), pxResults(2), and so
on) includes a property
that has the handle as its value:
In some settings, a user selects one element from the results list. Your activity can reference this property in the InstanceHandle parameter for the desired instance.
Checking the method status
This method updates the pxMethodStatus property. See How to test method results using a transition.
The Activity-Clear-Status method may be useful following an Obj-Open-by-Handle method.
This method cannot be used in a step that involves iteration.