All OBJ Methods
Methods for persistence instances:
Commit
Obj-Browse
Obj-Delete
Obj-Delete-By-Handle
Obj-Filter
Obj-List
Obj-List-View
Obj-Open
Obj-Open-by-Handle
Obj-Refresh-and-Lock
Obj-Save
Obj-Save-Cancel
Obj-Sort
Obj-Validate
Rollback
Obj-Browse:
Use the Obj-Browse method to search instances of one class and copy the
entire instances, or specified properties, to the clipboard as an array of
embedded pages.
this method, the properties that are not exposed as columns can be
returned, but not used for selection criteria.
The Obj-Browse method has five base parameters and an optional array of
selection criteria.
PageName: Enter the name of the destination page to contain search
results. The system uses Code-Pega-List as the class of this page.
ObjClass: Identify a class to search. You can search one concrete class, or
all classes in a class group.
Note:You can search the instances of a class that corresponds to a
PEGARULES database table or database view
1|Page
All OBJ Methods
(Why database view also Because we can’t provide lock for the
instance)
MaxRecords: Optional. Enter the maximum number of instances you want
returned. If left blank, the default value is 10,000.
GetRowKey: Select to include the primary key in the set of property values
returned. Clear to exclude the primary key. (Selected by default.)
RowKey: Optional. Enter the name of a property of the external table, or an
expression involving one or more property names, that specifies the unique
key of the external table. Leave blank if the class in the ObjClass parameter
is not corresponds to an external table(PZinskey)
ReadOnly: Select to mark the embedded pages as read-only, that means in
later requestor can’t update or delete the data in the page.
Leave unselected if you have the plan to update the embedded pages.
Note: Selecting this Read-only checkbox does not affect your ability to
remove an embedded page completely (with the Obj-Filter or Page-Remove
method).
Logic: Optional. Enter a boolean statement that defines how the rows of the
parameter array are to be combined. Identify rows by the Label field. You
can use the operators AND and OR in this statement, and parentheses for
grouping.
For example, A AND (B OR C OR (E AND F)).
If you leave this blank, the system applies the AND operation to all the rows
of the array.
The below parameters of the array are optional. The rows of this array to
define the selection criteria and the properties to be returned.
Label: Enter a unique letter for this row, referenced in the Logic field.
2|Page
All OBJ Methods
Select: Select to return the value of this property on each embedded page.
In the resulting SQL statement, this property is listed in the SELECT list (as
well as the WHERE condition).
Field: Enter a property reference. You can specify a Single Value property, a
list or group property.
However, only Single Value properties exposed as columns can be used as
selection criteria(means you can specify in Field parameter as Single Value
properties are a list or group property, but if you specified Group are list
property that value will present in returned values but not include in SQL
statement of selection criteria) .
Note1: only Single value properties and exposed as columns can be added
in select stmt as well as WHERE condition of that SELECT stmt.
Note 2:If single value properties are not exposed as columns those
properties will include in SELECT stmt only, not in WHERE condition.
Note 3:List and group properties also will include in SELECT stmt only, not
in WHERE condition.
Note 4: in condition field if you select Value Only even that property
specified in Field parameter is exposed will include in SELECT stmt only, not
in WHERE condition.
Condition: Select a comparison, such as Is Equal or Is Less Than.
Select Value Only to return the value of this property , but this
property value is not to be used as a selection criterion.
Select Is Null to require that the field have null value.
Select Is Not Null to require that the field have a value.
If the property is not exposed as a database column, select Value Only.
Value: Enter a constant value, a property reference for the comparison.
Leave blank if the Condition is Value Only, Is Null, Is Not Null, Is True or Is
False
Sorting: it provides the options to make the data order Like No Sorting,
Ascending, or Descending.
3|Page
All OBJ Methods
If the Condition is Value Only or Is Null, select No Sorting.
Results
At runtime, the system converts the parameters to an SQL query statement,
creating a SELECT WHERE and ORDER BY query based on the parameters,
and sends the query to the PegaRULES database.
Performance
This method can return thousands of database rows and create large
clipboard pages.
The below screen shows the Activity for obj-browse method,
4|Page
All OBJ Methods
The result for the obj-browse method, when you run this activity is shown
below.
OBJ-Open
Use the Obj-Open method to open an instance stored in the PegaRULES
database or in an external database, and save it as a clipboard page.
Parameters
This method has four base parameters plus an array of property names and
values.
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.
5|Page
All OBJ Methods
Note:You can open the instance of a class that corresponds to a
PEGARULES database table ,but we can’t the database view(Because we
can provide lock for the instance).
Lock: Select this box to acquire a lock. So that you can update and save and
delete the instance.
You cannot lock an object unless the Allow Locking? checkbox (on the
Locking tab of the Class form. If the class is part of a class group, the Allow
Locking? checkbox on the class named for the class group is applicable).
ReleaseonCommit: Select this box if you selected the Lock. And the system
releases the lock when the next Commit method occurs for this instance.(if
not selected after commit method execution also still the lock will be
retained.)
LockInfoPage: Optional. identify the name of a page. If the Obj-Open fails
to acquire a lock, this page will be created and can be viewed with the
Clipboard tool or the Tracer.
This page holds the like below properties. The class of this page is System-
Locks,
pxOwnerID — Requestor who holds the lock
pxExpireDateTime — Date and time the lock will go soft
By convention, this page is named LockInfo in standard rules.
PropertyName: Enter name of property reference or properties and the
associated values in this array, that together make up the key of the
instance to be opened.
Enter at least one property name.
PropertyValue: For the value, specify either a literal value, a property
reference.
Results.
6|Page
All OBJ Methods
If it finds the specified step page, the system clears the data on it and
reuses the page. If page does not found for the specified step page, the
system creates a new page.
Note:
The activity to check whether a page of a certain name exists or not.
To test for a page, enter the following the precondition to the activity step:
= @PageExists("myPage", tools)
where myPage is the name of the clipboard page.
7|Page
All OBJ Methods
Obj-Open-By Handle:
Use the Obj-Open-By-Handle method only to open an instance identified by
its handle .Otherwise, use the Obj-Open method.
A handle, known as an internal key. A handle uniquely identifies the
instance, the pzInsKey property holds the handle value for the object.
A handle identifies the class, certain key parts, and the creation date and
time for a single instance. So, for a new rule the pzInsKey property has no
value until the rule instance is saved.
Parameters
This method has four parameters:
InstanceHandle: Enter the handle that identifies the instance to be opened
as a literal or a property reference. This handle corresponds to the value of
the pzInsKey property .
Lock: Select this box to acquire a lock. So that you can update and save and
delete the instance.
8|Page
All OBJ Methods
You cannot lock an object unless the Allow Locking? checkbox (on the
Locking tab of the Class form. If the class is part of a class group, the Allow
Locking? checkbox on the class named for the class group is applicable).
Release on Commit: Select this box if you selected the Lock. And the
system releases the lock when the next Commit method occurs for this
instance.(if not selected after commit method execution also still the lock
will be retained.)
LockInfoPage: Optional. identify the name of a page. If the Obj-Open fails
to acquire a lock, this page will be created and can be viewed with the
Clipboard tool or the Tracer.
This page holds like below properties. The class of this page is System-
Locks,
pxOwnerID — Requestor who holds the lock
pxExpireDateTime — Date and time the lock will go soft
By convention, this page is named LockInfo in standard rules.
Results
This method opens database and finds the unique instance using the handle.
It copies the object's properties and values into a new clipboard page.
Restrictions
This method cannot be used in a step that involves iteration.
9|Page
All OBJ Methods
Obj-Save method:
Use this method to save a clipboard page to the PegaRULES database or an
external database (if the page belongs to an external class).
Unlike the Commit method, the Obj-Save method does not operate on all
objects, previously marked for commit, operates only on the current page,
and does not release locks.
Cautions
When you use the Obj-Save method in an activity with Activity Type as,
Utility, Notify, Assign, or Route, do not check the WriteNow checkbox. and in
situations where you want to mark a page to be saved, but want the system
to perform the database commit later.
Parameters
This method has three parameters:
WriteNow: Normally, leave this box cleared
Select the box to cause the system to write this page's data to the database
(database commit) as this method executes.
WithErrors: Select this box to cause this page to be saved even when it
contains messages, indicating validation errors.
OnlyIfNew: Select to cause only an insert operation, not update.
Results
First, the system examines the page's pxObjClass property to determine its
class. It uses the corresponding Rule-Obj-Class instance to find the
Database Table name.
The system determines whether a lock is already present on the instance. If
the current session does not hold a lock) the method will fails.
10 | P a g e
All OBJ Methods
Properties with a null value (or equivalently "") are ignored (not saved) by
this method.
Obj-Save-Cancel:
Use this method to cancel the most recent uncommitted Obj-Save and Obj-
Delete method. So that the instance will not written or delete as part of a
later Commit operation.
You can also use Rollback method to cancel all uncommitted Obj-Save and
Obj-Delete operations, not only the most recent one.(Means Rollback will
cancel All pending Obj-Save and Obj-Delete methods).
Parameters
This method has no parameters.
Commit method
Use this method to commit all uncommitted database changes that means
All pending Obj-Save and Obj-Delete methods. This method writes all the
instances specified by one or more Obj-Save methods to the PegaRULES
database (for internal classes) and to external databases (for external
classes).
Note: All locks held by the requestor Thread (except those that were
acquired with the ReleaseOnCommit box not selected in the Obj-Open
method) are released.
Rollback method
Use this method to cancel or withdraw any previous uncommitted changes
to the PegaRULES database (and to external databases accessed from an
external class). All pending Obj-Save and Obj-Delete methods are cancelled.
11 | P a g e
All OBJ Methods
Parameters
This method has no parameters.
Results
All uncommitted database operations are withdrawn. If an instance is locked
and the ReleaseOnCommit box was selected, the lock is released. Locks on
instances where the ReleaseOnCommit box was not selected are retained.
Obj-Refresh-Lock :
This method is used to ensures that the contents of the step page is gets
refreshed and a lock is acquired for that object.
This method does not effect when the object is locked and the lock has
not expired.
If the object is not locked, this method acquires a lock and if
necessary replaces the step page contents with the current value of an
object instance.
Parameters
This method has two parameters.
ReleaseonCommit: Select this box if you want the system to release the lock
when the next Commit method occurs for this instance.
LockInfoPage: Optional. 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
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.
12 | P a g e
All OBJ Methods
When a lock failure occurs during a flow execution, the flow can display
the standard harness [Link] to report the situation.
Results
The system checks whether the object on the step page is locked and the
lock has not expired. If the lock is held, the method creates the results page
as specified in the LockInfoPage parameter, but no further processing
occurs.
Obj-Delete
Use the Obj-Delete method to delete a database instance corresponding to a
clipboard page and optionally to delete the clipboard page too.
This method can operate on objects of both internal classes and external
classes.
You can cancel or undo a previously executed Obj-Delete method by using
the Obj-Save-Cancel method, unless the Immediate box is selected or the
Commit method has already occurred.
Note: The Obj-Delete-By-Handle method combines the Obj-Open-By-Handle
method and the Obj-Delete method in a single step, making your activity
shorter. Use the Obj-Delete-By-Handle method, not the Obj-Delete method,
when the object is not open on your clipboard and the object handle
(pzInsKey value) is known.
Parameters
This method has two parameters:
Remove: If selected, the system deletes the page identified in the Step Page
column of this step from your clipboard and marks the corresponding
persistent instance for deletion.
Immediate: If selected, the system deletes the database instance
immediately (commits this deletion).
13 | P a g e
All OBJ Methods
If this box is cleared, the database instance is deleted by the next Commit
operation.
Results
If the page is locked and the Remove parameter is selected, the system
deletes the page. It marks the persistent object in the database for deletion,
or deletes it immediately, depending on the Immediate parameter.
The below screen shows the activity containing obj-delete method,
The clipboard page before running the obj-delete method.
14 | P a g e
All OBJ Methods
The clipboard page after running the obj-delete method.
Obj-Delete-By-Handle
Use the Obj-Delete-by-Handle method to delete an instance identified by its
handle. This method executes the operations of the Obj-Open-By-Handle
method followed (if successful) the Obj-Delete method.
Note: Unlike the Obj-Delete method, the Obj-Delete-By-Handle method
does not require that the instance be open on the clipboard. Using Obj-
Delete-By-Handle, you can delete it without first opening the object.
Parameters
15 | P a g e
All OBJ Methods
This method has five parameters:
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.
Lock: Select to delete the object only if able to acquire a lock. Leave cleared
to delete the object weather lock acquired or not.(If Lock selected but the
situation, class does not allow locking or object is locked by others the
system will gets deletes the object but produces the warning. means
anyway object will gets deleted even lock not acquired due to lock)
If selected but the class does not allow locking, the Obj-Delete-By-Handle
method deletes the instance but produces a warning: Database-LockFailure-
NotSupported.(it means anyway object will gets deleted even lock not
acquired due to lock
Note:As a best practice, select this box if the object belongs to a class that
allows locking. With rare exceptions, it is not desirable to delete an object
that may be locked
ReleaseonCommit: Select this box if you selected the Lock. And the system
releases the lock when the next Commit method occurs for this instance.(if
not selected after commit method execution also still the lock will be
retained.)
LockInfoPage: Optional. 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
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 [Link] to report the situation.
16 | P a g e
All OBJ Methods
Immediate:
To delete the database instance immediately from the database, select
this box. If this box is cleared, the database instance is deleted by the
next Commit operation
Results
If the Lock checkbox is selected, the system attempts to acquire a lock on
the object. This attempt does not require the object to be opened. If Lock is
selected, the class supports locking, but the lock cannot be acquired, the
method fails.
Next, if Immediate is selected, the method deletes the instance from the
clipboard and from the PegaRULES database. If Immediate is not selected,
the deletion operation is queued until the next Commit occurs.
OBJ-LIST Method
Use the Obj-List method to retrieve data to the clipboard as an array of
embedded pages.
The Obj-List method searches instances sequentially for the PegaRULES
database or an external database and retrieves specified data to pages in
the clipboard. It returns either:
All instances, each as an embedded page.
Selected properties from the instances, placed in embedded pages
known as shortcut pages. Shortcut pages contain only partial
instance data and so cannot be resaved to the database.
Parameters
The Obj-List method has four base parameters and an optional array of
selection criteria. If you omit optional parameters, the system uses values
from the specified list rule (Rule-Obj-List rule type).
PageName: Enter the name of the destination page to contain search
results. The system uses Code-Pega-List as the class of this page.
ObjClass: Identify the concrete class to search. When this method references
a list rule, it uses this value as the Applies To key part to find the list rule.
17 | P a g e
All OBJ Methods
RuleObjList: Optional. Identify the name of a list rule that specifies which
properties are to be retrieved. The system uses the ObjClass parameter as
the first key part of the list rule.
MaxRecords: Optional. Enter the maximum number of instances you want
returned in the list at runtime. If this parameter is left blank, or set to zero
(0), that means no limit on the number of instances retrieved.
SelectionProperty: Optional. Enter one or more properties to select and
return from each instance of the class to be searched. At least one of these
properties must be exposed as a column in the PegaRULES database.
If the ObjClass field identifies an external class, enter at least one Selection
Property.
Note: As a best practice for good performance, specify only Single Value
properties that correspond to exposed columns in a database table .
SelectFrom: Optional. Enter a literal case-sensitive start value for this
property, or a property.
Leave blank when the Selection Property value for a row contains a property
reference and you want the results to include instances which contain no
value for that property.
SelectTo: Optional. Enter a literal case-sensitive end value for this property,
or a property reference.
Leave blank when the Selection Property value for a row contains a property
reference and you want the results to include instances which contain no
value of the property.
If the values in the SelectFrom and SelectTo are identical strings, PRPC uses
a LIKE SQL pattern. This selects database values that contain the string as
an initial prefix rather than as an exact [Link] example, if the
SelectFrom and SelectTo values are both APE, then the database returns
rows containing APE, but also returns rows containing APERITIF, APEX, and
APERIODIC.
Like: Optional. If the property identified in this row is an exposed column in
the corresponding database table, you can enter an SQL expression using
18 | P a g e
All OBJ Methods
syntax for the LIKE predicate, including the percent sign (%) for a wildcard
character. (If your expression contains no percent sign characters, PRPC
automatically supplies a trailing percent sign character.)
Lightweight Results: this Obj-List method to be returned in a special format
with a lightweight table in SQL rather than the standard pxResults pages.
This might reduce memory requirements when a large number of rows is
expected.
Results
This method creates one embedded page for each instance retrieved.
Performance
This method can return thousands of database rows and create large
clipboard pages.
The Obj-List-View method often produce more efficient SQL statements
and provide better performance than the Obj-List method.
Obj-ListView:
Use the Obj-List-View method to execute the retrieval and sorting
operations of a list view rule, but not the formatting and display processing
of a list view rule.
Parameters
Specify all three key parts of a list view rule
ObjClass: Select the Applies To key part of a list view rule. This may identify
an internal class or class group, or an external class.
ListView: Select the Purpose key part of a list view rule
Owner: Select the Owner key part of a list view rule.(Ex:All)
19 | P a g e
All OBJ Methods
Results
The system uses rule resolution to find the list view rule and executes it
20 | P a g e
All OBJ Methods
The selection criteria of the list view rule and the sorting requirements
(recorded on the Content tab) are converted to an SQL query that is sent
to the PegaRULES database.
The database results are organized into a results page of class Code-Pega-
List. The name of this page is determined in the Content Page Name field on
the Content tab of the List View form, (The Step Page field on the step is
ignored.)
Obj-Sort method
Use this method to sort the clipboard pages based on the values of a
property of Page List(pxResults). You can specify one or more properties to
sort, and the sort sequence is ascending or descending for each sort level.
Parameters
This method has two base parameters and an array of two parameters per
row:
PageListProperty: Enter a property reference that identifies Page List to be
sorted.
Class: Identify the class of the pages within the Page List property.
SortProperty: Identify a property reference (starting with a period or a
page name). based on which sorting of pages in page list will happen.
property must identify a Single Value mode property.
The order of your entries in this array is significant. The first property listed
is the major sort.
Descending: Select to cause the method to sort in descending order for the
property. Clear the box to sort in ascending order
Results
The system sorts (reorders) the pages of the indicated Page List property.
The rest of the clipboard is unaffected.
Sorting is sensitive to case and to Type.
21 | P a g e
All OBJ Methods
Obj-Filter method
Use the Obj-Filter method to filter the embedded pages of a results page
(such as a Code-Pega-List page produced by the Obj-List, RDB-List, Obj-
List-View or Obj-Browse methods) based on one or more when condition
rules.
For example, if each embedded page on results page contains a Page List
property Child and each Child page contains a Single Value property
FirstName, you can use the Obj-Filter method to remove all embedded
pages where no value of FirstName is "Robert".
22 | P a g e
All OBJ Methods
For best performance, use an Obj-Browse method to search and retrieve
instances of a class where the selection criteria involve only Single Value
properties exposed as columns in the PegaRULES database.
Parameters
This method has two required parameters and an array parameter.
ListPage: Name of the results page, of class Code-Pega-List.
ResultsClass: Select the Applies To key part of one or more when condition
rules (Rule-Obj-When) to be used to test each result. Must match or be an
ancestor class of the class of the embedded pages in the ListPage page.
When: Complete at least one row of this array, specifying a when
condition rule. Enter the second key part (When Name) of a when condition
rule.
Obj-Validate method
Use this method to apply a validate rule (Rule-Obj-Validate rule type) for
the object identified on the primary page or step page.
A validate rule (Rule-Obj-Validate rule type) can call edit validate rules
(Rule-Edit-Validate rule type).
Parameters
This method has two parameters:
Validate: Enter the second key part of a validate rule to apply.
OverrideClass: Optional. Enter the name of a class to search Validate rule.
If blank, rule resolution begins searching for the validate rule on the class of
the step page. You can override the class of the step page with a higher or
lower class.
Results
The system uses rule resolution to find the validation rule. It then applies
the validation rule to the properties on the step page (or primary page if the
23 | P a g e
All OBJ Methods
Step Page column is blank). If any validations fail, the system adds
messages to the page.
Ordinarily, if any property fails validation, the page cannot be saved from
the clipboard into the database.
Note:A later Page-Clear-Messages method applied to the same page
removes the messages set by this method
The result for the above activity is shown in the clip board page below.
24 | P a g e
