You are here: Reporting > Deprecated report types > List View rule form > More about List View rules

More about List View rules

  1. About
  2. New
  3. Display Fields
  4. Content
  5. Selectable
  6. Organize
  1. Format
  2. Pages & Classes
  3. Join
  4. HTML
  5. History
  6. More...

A list view rule defines report characteristics that the Pega Platform converts into source HTML when you save the form.

Processing overview

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.

Report title from Full Description field

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.

Testing

If a list view rule requires no parameters, you can test it directly by clicking Run.

Running a list view rule with an activity

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:

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:

To 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 How to use parameters as selection criteria in a list view rule.

Executing a list view rule with a URL

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

  1. Execute the list view rule.
  2. Right-click in the Internet Explorer window.
  3. Select Properties from the context menu
  4. Drag the mouse to select the URL text, which may be only partly displayed.
  5. Press CTRL+C to copy the URL.
  6. Paste the Windows clipboard into Notepad or a text editor.

Personal versions

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.

Results

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 How to detect and remedy the performance impact of Obj-List methods and list view reports.

Access to search instances

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.

Automatic backward chaining and Read Only displays

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

As an alternative to updating the prconfig.xml file, you can use Dynamic System Settings to configure your application. See Dynamic System Settings data instances.

Agent can produce nightly reports

Using an agent and a Connect File rule, your application can produce PDF files of reports, on a regular schedule.

Viewing the Java code of a rule

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.

Parent class

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.