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 Work-.LockInfo 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 Work-.LockInfo 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 match.For 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