A list view rule defines report characteristics that the Pega Platform converts into source HTML when you save the form.
When executing a list view rule, stream processing is used to select, retrieve, and format data for user presentation. Normally, it creates SQL statements from information on the Content tab and sends the SQL request to the Pega Platform database.
The database results appear in a Page List property named pxResults of class Code-Pega-List, which contains a Page property pxResults(1), pxResults(2), and so on for each returned row (each object instance). Each page value contains the properties listed in the Get These Fields array.
After database results are available, local sorting, filtering based on when condition rules, and formatting operations occur as defined on the Organize tab.
For performance reasons, some selecting, filtering, and sorting occurs through the software supporting the database (such as Oracle, IBM DB2 or Microsoft SQL Server), while later processing of the data occurs on the Pega Platform server. Selection and sorting operations done by database software are typically faster, but are limited to those Single Value properties that are exposed columns in the database schema.
DateTime values (but not Date or Time of Day values) in the results are converted to display in the time zone of the user, based on the Time Zone value on the Availability tab of the Operator ID instance. This conversion affects selection criteria and displayed results, and so can present a different day and time for different users.
The text of the Full Description field (property .pyDescription) of a list view rule (on the History tab) appears to application users as a report title. Choose text that clearly describes the report contents. You can include syntax in the Full Description to include at run time the value of a parameter or scalar property. . For example:
List of {pagename.property1} as of {pagename.property2 }
Only refer to properties that are certain to be present. This feature can support localization, through language-specific rulesets.
If a list view rule requires no parameters, you can test it directly by clicking Run.
To call a list view rule within an activity, use the Obj-List-View method or the standard activity Rule-Obj-ListView.ShowView, depending on your requirements.
Use the Obj-List-View method to create a results page (of class Code-Pega-List) containing the class instances that meet the criteria on the Content tab, sorted as specified on that tab. No output appears. Information in the Organize, Display Field, and Format tabs is not used.
Use the Rule-Obj-ListView.ShowView activity to support user displays and interactions. Specify one of four values for the pyAction parameter:
Refresh — Execute the entire list view rule, retrieving data from the PegaRULES database, sorting and filtering the data, and presenting the display.Redisplay — Execute the display aspects of list view rule, using data previously retrieved.Sort — Resort the existing data.Prepare — Execute the data retrieval only. (This parameter setting results similar to the Obj-List-View method, except that Obj-List-View ignores paging and always returns all rows, up to the Maximum Value count.) If report paging is enabled, report rows for only one page are returned. Complete these parameters on second and later calls to control the contents of the page:
PageIndex — The index of the page. Leave blank on the first call; set to 2 to retrieve the second page, and so on. PageCount — Set to the value of the pxPageCount property on the pxResults pageTotalRecords — Set to the value of the pxTotalResultCount property from the pxResults pageTo specify that execution is to use a reports database (regardless of the setting of the Use reports database? check box on the Contents tab), set the pyUseAlternateDb parameter to true.
To remove the data page after the initial display (reducing the size of the clipboard), set the removeDataPage parameter to true.
List view rules can accept additional parameters for selection, by referencing them with the notation param.name in the Value column of the Criteria array on the Content tab. Ensure that processing sets values for these parameters before the list view rule executes. For an example, see PDN article 25410 How to use parameters as selection criteria in a list view rule.
Alternatively, you can start a list view execution with a URL that identifies the Rule-Obj-ListView.ShowView activity followed by parameters settings in the standard CGI URL format. For example, this URL executes the standard list view rule Data-Admin-Calendar.ListCalendars:
http://server:8080/prweb/
?pyActivity=Rule-Obj-ListView.ShowView
&pzPrimaryPageName=LISTVIEW_ListCalendars
&pyViewPageName=LISTVIEW_ListCalendars
&ViewClass=Data-Admin-Calendar&showHeader=false
&pyContentPage=CalendarList
To assemble this URL, an activity can set values for these (and other) parameters with the param keyword and the Property-Set method.
To review the URL for an existing list view display (using Internet Explorer):
If your access group identifies a local ruleset, you can use the Customize View feature on those list view rules that offer it. Use the Customize View button to create a personal copy of the list view rule, with your Operator ID as the last key part.
The list view facility works best for queries involving 500 or fewer rows. It does not support queries that contain more than 10,000 rows unless report paging is enabled.
For best performance, limit the properties displayed to exposed columns in the corresponding database table; this prevents the need to load the Storage Stream column. Expose additional properties as columns if needed to improve performance. See the PDN article 23116 How to detect and remedy the performance impact of Obj-List methods and list view reports.
To run a list view rule, users must have the ability to search through instances of the class identified in the Applies To key part. Accordingly, users must have an access role that links to an Access of Role to Object rule (for the Applies To class or a parent class) in which the Search Instances value grants read-only access.
When selected, the Read Only check box (on the Content tab) prevents most changes to the data retrieved from the PegaRULES database during list view process. However, some reports may depend on backward chaining (defined by Declare Expression rules) to derive report contents. To allow such computations, backward chaining is allowed by default and may result in updated values on pages within the Code-Pega-List results page — an exception to the "read only" restriction.
If allowing such backward chaining computations is not desired, you can disallow backward chaining on list view rules where the Read Only check box is selected by adding a setting to your prconfig.xml file:
<env name="clipboard/VirtualListSupportAutoChaining"
value="false" />
If the clipboard/VirtualListSupportAutoChaining element does not appear in your prconfig.xml file, the default value is "true".
Note: As an alternative to updating the prconfig.xml file, you can use Dynamic System Settings to configure your application. See Dynamic System Settings and the prconfix.xml file.
Using an agent and a Connect File rule, your application can produce PDF files of reports, on a regular schedule.
Click Actions > View Java to view the generated Java of a rule. You can use the Java code to debug your application or to examine how rules are implemented.
Through directed inheritance, the immediate parent class of Rule-Obj-SummaryView and Rule-Obj-ListView classes is the Rule-Obj-Report- class. At run time, the system uses stream processing to assemble, format, and present the query results.