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.
This method has four base parameters plus an array of property names and values.
Optional. Identify the concrete class of the instance to be opened. If left
blank, the class is obtained from the
Pages & Classes
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).
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.
Select this box if you selected the
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.
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 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
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.
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.|
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
If the another requestor has locked the instance, the system opens the object to the
clipboard, but the method returns a
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
property and the key values, and returns a
If you selected the
parameter (on the
tab of the
form or in some
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, and the method returns a
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.
This method cannot be used in a step that involves iteration.