Obj-Open-By-Handle method
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 Page List.
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.
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.
Parameters
You define the parameters listed in the following table for the Obj-Open-By-Handle method.
| Parameter | Description |
| InstanceHandle | Enter the handle that identifies the instance to be opened as a literal or a
property reference. This corresponds to the value of the pzInsKey
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. For more information, see the section Capturing a handle in a property reference below. |
| Lock | Select this option 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.) |
| ReleaseOnCommit | Select this option to cause a lock to be released when your changes are
completed through the Commit method. In most cases, select this option 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. |
| LockInfoPage | 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:
By convention, this page is
named |
Results
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
The following table lists conditions that cause the method status to be set to
Fail or Warn.
| Status | Cause |
| Warn | The class does not allow locking but the Lock parameter (on the Locking tab of the Class form or in some cases the Class Group form) is selected. |
| Fail | The object is opened to the clipboard but the instance is locked by another requestor. |
| Fail | The Lock parameter is selected but at, runtime, the requestor's access role does not allow the requestor to update objects of that class. |
| Fail | The page of the indicated class that is created is empty except for the pxObjClass property. This occurs when the key supplied does not match the key of an instance in the database. |
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.strHandleIf 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.
Capturing a handle in a property reference
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
pxResults page. Each instance listed (pxResults(1), pxResults(2), and so
on) includes a property pyInsHandle 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
The method updates the pxMethodStatus property. For more information, see How to test method results using a transition.
The Activity-Clear-Status method may be useful following an Obj-Open-by-Handle method.
Restrictions
The method cannot be used in a step that involves iteration.
Previous topic Using handles Next topic Determining if a handle exists