Obj-List method

Beginning with V5.4, the Obj-List method is deprecated except when used with external classes. For best performance, use the Obj-Browse method followed if necessary by the Obj-Filter method rather than the Obj-List method. See Obj-Browse method and Obj-Filter method.

Use the Obj-List method to retrieve data to the clipboard as an array of embedded pages.

The Obj-List method searches sequentially through instances of the PegaRULES database or an external database and retrieves specified data to pages in the clipboard. It returns either:

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

This method is often used with a list rule (Rule-Obj-List rule type), which defines a list of properties to retrieve.

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

To open a rule instance (for example, of a custom rule type), use PublicAPI facilities, not the Obj-List method, to perform rule resolution processing. The handle of a rule instance contains the creation date and time, but does not identify the RuleSets or version. Do not assume that the rule created most recently is the one in the highest RuleSet version.

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

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 the concrete class to search. When this method references a list rule, it uses this value as the Applies To field (first key part) with rule resolution to find the list rule. Within the PegaRULES database, the class can correspond to a database table or to a database view.
RuleObjList	Optional. Identify the second key part — List Name — 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 a value of zero (0), no limit will be imposed on the number of instances retrieved. 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.
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. As a best practice for good performance, specify only `Single Value` properties that correspond to exposed columns in a database table here, rather than properties within the Storage Stream (BLOB) column. See Pega Developer Network article PRKB-23116 How to detect and remedy the performance impact of Obj-List methods and list view reports. If you need to select on a property value that is not an exposed column and the activity containing this Obj-List method will be heavily used, consider exposing the property to improve performance. You can review the database schema to see which properties are exposed. Consult your database administrator for information on the current database schema, or use the Modify Database Schema facility. See How to expose a property as a database column.
SelectFrom	Optional. Enter a literal, case-sensitive start value for this property, or a property reference on the step page, or other expression. Click the magnifying glass icon ( ) to start he Expression Builder. 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. In V4.2SP1 and earlier, rows containing a blank SelectFrom or SelectTo values were ignored and did not affect method results. If your system depends on this older behavior, a compatibility setting is available. See Pega Developer Network article PRKB-20392 How the Obj-List method processes blank database columns (versus V4.2SP1) .
SelectTo	Optional. Enter a literal, case-sensitive end value for this property, or a property reference on the step page, or an expression. When distinct, the SelectFrom and SelectTo values define an inclusive range. Click the magnifying glass icon ( ) to start he Expression Builder. 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, Process Commander 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. As an alternative to Obj-List when you need only exact matches, your activity can call the PublicAPI method Database.list() in a Java step.
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 syntax for the LIKE predicate, including the percent sign (%) for a wildcard character. (If your expression contains no percent sign characters, Process Commander automatically supplies a trailing percent sign character.)
Lightweight Results	Select to cause results from this Obj-List method to be returned in a special format consistent 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. However, handcrafted Java steps are needed to work with the results.

Results

This method creates one embedded page for each instance retrieved. See Obj-List Method — Examples and Standard properties in the Code-Pega-List class.

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

This method also adds or updates these properties in the step page:

pxResultCount — A count of the instances retrieved by this search.
pxMore — Indicates whether there are more instances in the database that were not returned. Values are true or false.
pxNextKey — Indicates the key of the first row (instance) not returned, if pxMore is true.
pxElapsedTime — Seconds of elapsed time spent executing the request.

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.

The Obj-List-View method often produce more efficient SQL statements and provide better performance than the Obj-List method.

If the results of an Obj-List method are of multiple classes and will appear in an HTML display or be used in correspondence, consider using the optional pega:assert JSP tag to improve performance.

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

Notes

See the Pega Developer Network article PRKB-25063 Comparing the Obj-List-View, Obj-Browse and Obj-List methods.

	external class, internal class schema, results page, Storage Stream, view
	How to configure Dynamic Select for a property JSP tag — Pega:assert Obj-List method — Examples RDB-List method How to monitor Storage Stream operations How detect database list operations that return many rows
	Atlas — Standard properties in the Code-Pega-List class

Methods and instructions by function