Obj-Open method

Use the Obj-Open method to open an instance stored in the PegaRULES database or in an external database linked to an external class, and save it as a clipboard page.

The system uses the specified class and key fields to find and open the object and place its data into the specified step page. The system searches up the class hierarchy as appropriate to find the instance. If it finds the specified step page, the system clears any data that is on it and reuses the page. If no existing page has a name matching the specified step page, the system creates a new page.

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 if necessary to match the class of the object. Typically, this is not desirable.

When rule and Function rule alternatives

In some cases, you may need only to confirm whether or not the object exists, and not need access to the properties that make up the object. You can use either of two alternatives, each is faster (less costly) than using Obj-Open. They do not alter your clipboard.

  • When — The standard when rule @baseclass.@pxDoesObjectExist checks to see whether the object described by the current step page exists. The class of the step page identifies the class of the object. The step page must contain properties and property values that form the key parts of the object to be tested.
  • Function — Similarly, the standard function rule pxDoesObjectExist() in the Utilities library determines whether a specific object exists in the database. The pxDoesObjectExist() function accepts as a single parameter a clipboard page containing the properties and values for the key parts of the object to be tested, and returns true or false. The class of the page identifies the class of the object.

Parameters

This method has four base parameters plus an array of property names and values.

Parameter Description
OpenClass Optional. Identify the concrete class of the instance to be opened. If left blank, the class is obtained from the Pages & Classes tab of the activity based on the property references in the parameter array.

You can't open an instance of a class that corresponds to a view in the PegaRULES database (rather than a table).
Lock Select this box to acquire a lock. Lock the instance if you plan to change and save the instance or delete it.

Your session cannot lock the object unless your access role includes the ability to update objects of the class.

Locking an object from an external class prevents updates by other requestors in the Pega Platform system. Such locking does not prevent changes to the external database — including changes to a row open and locked in PRPC — by other systems.

ReleaseonCommit Select this box if you selected the Lock box and want the system to release the lock when the next Commit method occurs for this instance.

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 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 requested but not acquired is held by the same Operator ID in a separate requestor session, that user can click the Release Lock button to release the lock.

PropertyName Enter in this array the name of each property or properties and the associated values that together make up the key of the instance to be opened. Type a period before the property name. Enter at least one property name.

Review the General tab of the Class form for the class (or of superclasses of this class) to determine which properties form the key.

Note: When acquiring a lock, include the properties that make up the lock key when they differ from the properties that make up the instance key. (This is rare.) Information about the properties that make up locks is on the Locking tab of the Class form (or in some cases on the Class Group form).
PropertyValue For the value, specify either a literal value, a property reference, or a linked property reference.

Results

The system computes a pzInsKey value by concatenating the property values identified in the Keys definition on the Basic tab of the class rule. If the OpenClass parameter identifies an external class, the system sets the value of the pxObjClass property on the clipboard to the class name.

If the step page does not exist, a new page is created. (The pxObjClass property, part of every instance, identifies its class.) If the Step Page field is blank, the system clears and reuses the primary page of the activity.

It reads the persistent object instance from the database and adds all properties of the object to the step page.

If the Lock check box is selected and the requestor has permission to update objects of this class, the system locks the instance.

The step page may be an embedded page, or one page in a list or group. In these cases, the page, if it exists, is replaced completely. For example, if the page is seventh in a Page List, or “Customer” in a Page Group, your application can still reference the page as "7" or “Customer” after the replacement.

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.

To test for a page, enter the following precondition to the activity step:

= @PageExists("myPage", tools)

where myPage is the name of the clipboard page.

Fail and Warn conditions

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

  • If the another requestor has locked the instance, the system opens the object 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 the key values, 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, and the method returns a Fail status.

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

Restrictions

This method cannot be used in a step that involves iteration.