Obj-Browse method

Only properties exposed as columns can be used as selection criteria. However, values of properties that are not exposed as columns, including embedded properties, can be returned.

Use the Obj-Browse method optionally followed by the Obj-Filter method to create a list of search results. The Obj-Browse method selects instances based on values of properties exposed as a column. The Obj-Filter method qualifies and filters list results based on all property values, exposed or not. Together these two methods provide greater control over which properties are returned, and better performance, than the Obj-List method.

Parameters

The Obj-Browse method has five base parameters and an optional array of selection criteria.

Parameter	Description
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. Within the PegaRULES database, the class can correspond to a database table or to a database view.
MaxRecords	Optional. Enter the maximum number of instances you want returned in the list at run time. If left blank, the default value is 10,000. If the value is 0, up to 50 instances are returned. As a best practice, specify a MaxRecords value to reduce the demand for database activity memory. If necessary, your activity can test the property pxMore on the results page to see whether additional rows were not returned because the MaxRecords limit was reached.
GetRowKey	Select to include the primary key in the set of property values returned. Clear to exclude the primary key. (Selected by default.)
RowKey	This field is required if GetRowKey, above, is selected. Otherwise, leave blank unless the class in the ObjClass parameter corresponds to an external table. Enter the name of a property in the external table, or an expression involving one or more property names, that specifies the unique key of rows of the external table.
Lightweight List	Select to have the embedded pages for the selected instances use lightweight lists for better performance. Leave unselected if the activity performs operations unsupported by lightweight lists, like forward chaining declarative processing, messaging, or value vetting. Refer to the Pega Community article About lightweight lists for more information. As a best practice, select this check box. This can reduce memory requirements during processing. Having the embedded pages use lightweight lists does not affect your ability to remove an embedded page completely (with the Obj-Filter or Page-Remove method). Two dynamic system settings control the use of lightweight lists by the Obj-Browse method. There is a setting each for the Pega Platform and application rules: clipboard/lightWeightList/enableForCorePRPCRules - this is set to true by default. clipboard/lightWeightList/enableForCustomerRules - this is set to false by default. When true, these dynamic system settings override the Use Lightweight List check box setting on the Activity rule form.
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 assumes the AND operation applies to all rows of the array.
	Optional. Complete one or more rows of this array to define the selection criteria and the properties to be returned. If you leave this array blank, all rows (and all columns including the pzPVStream column) are selected, up to the MaxRecords limit. For an external class, complete at least one row of the array.
Label	Enter a unique letter or identifier for this row, referenced in the Logic field.
Select	Select to return the value of this property on each embedded page. In the resulting SQL statement at run time, 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, or individual elements of a list or group property. You can return any property — exposed as a column or not — in the results by setting the Condition field to `Value Only`. However, only `Single Value` properties exposed as database columns can be used as selection criteria. Click the Open icon to open the property. Do not use the Gear icon. To restrict the search to specific values of a property, enter a property reference that is exposed as a database column. You can review the database schema to determine which properties are exposed for a class. Consult your database administrator for information on the current database schema, or use the Modify Schema facility. See Property optimization.
Condition	Select a comparison, such as `Is Equal` or `Is Less Than`. Select `Value Only` if the search results are to include the property value, but the property value is not to be used as a selection criterion. Select `Is Null` to require that the field a 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 or other expression for the comparison. Leave blank if the Condition is `Value Only`, `Is Null`, `Is Not Null`, `Is True` or `Is False`. Click the Open icon to open a property. Click the Open expression builder icon to start the Expression Builder. If you enter an expression involving function rules, Java, and properties on various clipboard pages, then at run time the expression is evaluated only once. If you enter a property (that is exposed as a column) that applies to the ObjClass class, the Value value is evaluated for each row. For example, if the Field field contains a `DateTime` property ExpireDateTime, the Condition is `IS GREATER THAN`, and the Value field contains a function computing the current date and time, the function is evaluated only once, not once per row. Note: The second value in the comparison refers to a property on the current clipboard page, or a hard-coded value, not to a value in the database record.
Sort	Select `No Sorting`, `Ascending`, or `Descending` to control the sorting of results by this field. (Sorting occurs through database software, on the database server.) If the Condition is `Value Only` or `Is Null`, select `No Sorting`.

Results

At run time, 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.

This method operates on the database response to create a results page containing one embedded page for each instance retrieved.

If the Field parameters identify only Single Value properties exposed as columns, each embedded page in the results contains only those properties. However, if one or more of the Field parameters identifies a property that is not an exposed column, the entire pzPVStream column, also known as the Storage Stream or Blob column, is also returned.

The Obj-Browse method returns the data either to a previously created step page — which is cleared and reused — or to a new page of that this method creates of class Code-Pega-List. The system writes search results in the specified step page, along with information that controlled the search.

Note: Execution of this method does not trigger declarative rule processing that depends on change tracking. Even when a property retrieved by the Obj-Browse method is involved in a Declare Expression, Declare Constraint or other declarative rule, retrieval does not cause the declarative rule to re-evaluate.

Properties of Code-Pega-List

This table identifies some of the main properties of the Code-Pega-List class, which is output from various methods. Properties marked with a yellow diamond can hold input parameters for the search. Other properties specified as read-only contain outputs from the search.

Property	Purpose
pyCacheFile	For list view reports that save results as an XML file in the lookup list cache, identifies the file name.
pyCondition	A `Page List.` Identifies the parameters that define search comparisons, for the Obj-List method: pyConditionFieldName — A property reference resulting in a single text value pyConditionOperation — A comparison operator, such as "<" pyConditionValue1 — An expression for the comparison value
pyDetailsAction	For list view and summary view rules, identifies the value of the `pyAction` parameter to the ShowView activity, such as `PREPARE` or `SHOW`.
pyDetailsWindow	For list view and summary view rules, identifies the name of the window that is to hold the resulting display.
pxElapsedTime	Elapsed time in seconds to process the RDB-List operation. Read-only.
pxMore	Indicates whether there are more instances not returned. Values are true or false. Read-only.
pyMaxRecords	Optional input to limit the number of rows returned.
pxNextKey	Indicates the key of the first row (instance) not returned, if pxMore is true. Read-only.
pyObjClass	Identifies the class containing the instances that are to be searched. This property is different from pxObjClass, the class of this page, which always has the value Code-Pega-List.
pyPageSize	For list view or summary view rules that support report paging, the maximum number of results to presented on a page.
pyQueryTimeStamp	A `DateTime` value recording the start of the operation. Read-only.
pxResults	A Page List containing pages with individual search results. each of the class defined in the pxObjClass property. (Not used for Obj-List methods that specify the lightweight results format.) Read-only.
pxResultCount	Number of rows of data returned by the search. Read-only.
pyReturnLightweightResults	For the Obj-List method, indicates that the results are in a special format rather than in pxResults pages. Read-only.
pxSelectStatement	For the Obj-List method, the SQL statement sent to the database before substitution. Read-only.
pxSQLStatementPost	For the RDB-List method, SQL statements as sent to the SQL database. Appears only when requested through the `{SQLPage}` syntax. Read-only.
pxSQLStatementPre	For the RDB-List method, SQL statements before substitution. Appears only when requested through the `{SQLPage}` syntax. Read-only.
pxTimeElapsed	For the Obj-List method, elapsed seconds taken for the method. Read-only.
pxTotalResultCount	For the RDB-List method, the total number of results returned by the query. This is set only if pyReturnTotalResultCount is true. (If pyReturnTotalResultCount is false, then this is zero.) Read-only.
pyUseAlternateDb	Set to true if an alternate database, not the primary PegaRULES database, was the source of data for a list view or summary view report.

Performance

This method can return thousands of database rows and create large clipboard pages. Use care to retrieve only the rows (instances) and columns (properties) you truly need. Similarly, specify sorting only when needed.

Note: Execution of this method may cause an alert to be added to the Alert log, of type PEGA004 - PEGA007, PEGA0025, PEGA0027, or PEGA0028. Review the Alert log to understand the frequency and sources of such alerts, and for best performance, alter your application or database to eliminate those alerts that occur frequently. For example, if execution of an Obj-Browse method accesses properties within the Storage Stream column, a PEGA0025 alert occurs. The alert indicates that exposing one or more columns in the PegaRULES database table that holds instances of the class is likely to improve performance.

Checking the method status

This method updates the pxMethodStatus property. See How to test method results using a transition.

Pega Community Article

See the Pega Community article Comparing the Obj-List-View, Obj-Browse and Obj-List methods.