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.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.
Caution: Except in rare cases, identify in the Step Page field the name of a page to be created by this method. If the Step Page field of the step is blank, this method opens the object into the primary page of the current activity, replacing the current contents of the primary page and changing the class of the primary page to match the class of the object. Typically, this is not desirable.
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:
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. See How to Capture... below for details. |
| Lock |
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.) Caution: Locking an object from an external class prevents updates by other requestors in the Pega Platform system. Locking does not prevent changes to the external database — including changes to the row open in the Pega Platform — by other systems. |
| ReleaseOnCommit |
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. |
| 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:
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.
These situations cause the method status to be Fail or Warn:
Warn status. Fail status. 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.
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.
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.