You are here: Reference > Activity methods > Obj-Open-By-Handle

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.

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.

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

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 7 Platform system. Locking does not prevent changes to the external database — including changes to the row open in the Pega 7 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: pxOwnerID — requestor who holds the lock pxExpireDateTime — date and time the lock will go soft pxUpdateOperator — pyUserIdentifier value for the requestor who holds the lock pxLockHandle — text string that defines the lock 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 `LockInfo` in standard rules. When a lock failure occurs during a flow execution, the flow can display the standard harness Work-.LockInfo (or a similar harness incorporating the standard section System-Locks.LockInfo) to report the situation. If the lock not acquired is held by the same user in a separate requestor session, the user can click the Release Lock button to relinquish it.

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

These situations cause the method status to be Fail or Warn:

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
If you selected the Lock parameter (on the Locking tab of the Class 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 Warn status.
If you selected the Lock 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 Fail status.

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