Content tab on the List View form
Complete this tab to define:
- Which instances are selected
- How the instances are sorted by database software
- When and how users requesting to run a report can alter the selection criteria
- Any privileges required for running the report
If you leave the Criteria array empty, the list view selects all instances of the class, up to the limit in the Page Size field. If the Page Size field is blank, the limit is the value of the Maximum Value field.
field, you can specify only properties that correspond to optimized (exposed) columns in the PegaRULES database. By default, custom properties in your application are not optimized . They are stored in a Storage Stream (BLOB) column. However, in many cases you can expose a
property as a database column, after which you can specify it. See
Planning for property optimization.
Each row of this array identifies selection criteria. The order of rows in
this array is not significant. The system converts information in this array to an
SQL WHERE clause.
In the Field field, you can specify only
As a best practice for performance, using optimized (exposed) properties as criteria on this tab is preferred over selection with fields on the Organize tab. See the Pega Community article How to detect and remedy the performance impact of Obj-List methods and list view reports.
Optional. If you enter multiple criteria, enter a letter or letters that uniquely identify each row. This label identifies this row in the
For example, enter A for the first row, B for the second row, and so on. The Logic value must mention each label.
Specify a property reference for a comparison. For optimized properties defined in the class corresponding to the Applies To key part of this list view rule, start the property reference with a period. You can also identify fully qualified values on other clipboard pages that are always present on the clipboard, such as the requestor page or process page.
If the type of this property is
If you specify pxObjClass and the Applies To key part of this list view rule is a framework class, at run time the report can use the corresponding implementation class, not the framework class, for comparisons and report content. This feature eliminates the need to copy each framework class-based list view report into the implementation class. To enable this capability, select the Report on Descendant Class Instances check box on this tab.
|Caption||Optional. Specify text to name this row of the array. If you do not specify a caption, the Field name is used.|
Select a comparison condition, such as
The system converts the
Specify a comparison value. Possible values are:
field is set to
Commas correspond to an OR test. If the Value field contains two or more entries separated by commas, the comparison is true at run time if the value of the Field field equals (or is greater than, or is contained in, and so on) any one of the entries.
Similarly, when the
field contains a
When evaluating either of the two
Using the Select Values button
When you click the Select Values button, a window opens with one or more of the following tabs:
Use the search field to find the value you want from a long list.
For security reasons, list view rules that run on a web node as part of a composite application cannot use parameter values as selection criteria.
Click the gear icon at the end of a row to display optional fields:
|Field Value Key||
Optional. To localize this value for the convenience of users speaking a language other than English, specify the Field Name of the
that contains the value's localization. If the field is blank, the value is not localized.
To enable localization, select the Localize? check box on the HTML tab.
|Default Value||Specify a comparison value to use when you do not specify a value in the Value field.|
|Edit Input||Optional. Identify an edit input rule to convert the value from the format supplied by the Value field to another format. (If you identify a custom activity in the Activity Name field, the activity must access and apply these rules to input values.)|
Select to test or compare the Field value and the Value value at run time
after the system converts both to uppercase. If selected, at run time "a" matches
"A" and is less than "B".
If this option is not selected, tests of the Field value and the Value value occur without case conversion. In this case, "a" is greater than "A" and also greater than "B".
In most cases, do not select this option. Select this check box only when necessary to obtain the rows of the report:
See the Pega Community article How to correct the Case Insensitive warning for list view rules.
This option is meaningful only when the entry in the
field is not a constant. By default, if the value for the
field is null at run time, the system ignores the criteria defined by this row. Processing is the same as if this criteria is not present.
For example, assume the criteria in a row is:
If this list view rule runs when the value of Param.Letter is "C", this criteria limits the report to contain only instances in which the Lastname property value starts with the letter C. However, if the same rule runs again when the Param.Letter parameter has no value, this criteria is not applied. Instances with any Lastname value (or none) are selected.
If you do not want this default behavior, select the
box to force the
value to become
If this list view rule runs on a web node as part of a composite application, the Use Null* setting is selected for all criteria.
Optional. Using the labels entered in the
array, specify a logical expression that defines how the system combines the criteria into an overall Boolean value at run time. The expression can include parentheses and the operators AND and OR.
For example, if the table contains four rows labeled A, B, C, and D, you can specify:
This notation is the same as for the logic statement in when condition rules.
If you leave the Logic field blank, the system selects only instances for which all criteria rows are true.
|Convert criteria values from Locale values?||
Select to convert user-supplied values for parameters from a locale-specific format to the internal representation at run time. The system attempts to convert literal values, or parameter values for numbers (
If not selected, users must enter parameter values and literal values for
When selected, the system converts user inputs from the locale-specific format before the activity specified in the Activity Name field runs. The system applies any edit input rules specified in the Criteria array after the conversion but before the activity runs.
For example, if the user's locale is FR (France), an input of 3,142 for a
Click the Configure button to view or alter prompt settings. These settings determine the extent to which report users can view or alter report criteria at run time.
When one or more criteria allow
Value Only, the user can review or enter criteria at run time.
Select whether to use the default prompt settings or define custom settings.
When you select
|Label||This label corresponds to the label defined in the criteria row.|
|Property||This field is corresponds to the field specified in the criteria row.|
Select a value to determine how a user of this report can modify the criterion in this row, when prompted before the report runs:
|Prompt user before executing the report?||
Select to display the criteria to users who request this report, before the system runs the list view report.
When selected, at least one
row must allow user input, and the
for at least one row must not be
|Display criteria with the results?||
Select to cause the criteria (both prompts and values) to display as part of the report output.
As a best practice, select this option if the report user is allowed to change report selection criteria. If not selected, the output for a single report might vary from user to user for no easily detected reason, because the users saved different criteria.
|Display Available Values?||
Select to display a list of up to 1,000 values for a property referenced in the
field at run time. The system searches saved instances of the class until it finds 1,000 distinct values.
User selections apply to the Value field for the current execution of the report. This check box is meaningful only when Prompt user? is selected, and one or more rows of the criteria allow users to enter values.
|Display Valid Values?||
Select to make available at run time a list of values based on the
fields on the
tab of the property referenced in the
The user's selections apply to the Value field for the current execution of the report. This check box is meaningful only when Prompt user? is selected, and one or more rows of the criteria allow users to enter values.
|Display Compatible Columns?||
Select to make available at run time a list of properties eligible for comparison. These are properties in the
class (or an ancestor class) that are optimized as columns and match the
of the property referenced in the
The user's selection at run time applies to the Value field, for the current execution of the report. This check box is meaningful only when Prompt user? is selected, and one or more rows of the criteria allow users to enter property names.
|Search Button Label||Specify a text string to display on the search button.|
Get These Fields
Identify the properties to be retrieved for instances selected by the specified criteria. Include the properties listed on the Display Fields tab (or the properties needed to compute or derive those listed on the Display Fields tab).
If you specify sorting, the order of rows in this array is significant. The first sort listed is the major sort.
For optimal performance, list only the properties needed to support the presentation, computations, filtering, and sorting of the report. Including unused properties in this array increases the processing, bandwidth, and memory demand of this list view rule.
|Get These Fields||Click the plus icon to add a field.|
Specify a property reference in the class corresponding to the
key part, or in an ancestor super class. Start the property reference with a period.
You can specify any property in the class, including aggregate properties. However, performance is better when the properties correspond to optimized columns in the PegaRULES database table.
Sorting that is specified in this field occurs within the database software and uses sort algorithms provided by the database software vendors. In unusual cases, the sort sequence might not match your needs. Additional sorting can occur later on the Pega Platform server, as specified in the Organize tab.
|Get DISTINCT records||Select to eliminate duplicate records in the view.|
|Get Row Key||Select to display the key field for each row in the report.|
Key Of A Row
A report based on an internal class can support this capability. Reports on external classes can support this capability if a single property is the unique key of instances.
To support processing after users select a row, identify the property that forms the key to rows of the database table on which this list view operates.
- For an internal class, enter the pzInsKey property, with no leading period. The value of this property is the handle or full key of instances in the PegaRULES database.
For an external class, identify the property that holds the key to a row. In a custom GetContent activity, copy the value of this property to the property
on each page in the
pxResultslist. For example, if the key of the row is named customerID, the custom activity can use the following SQL syntax to return data from the database:
Select customerID as “pxInsHandle”
|Key of a Row||
For an internal class, enter
with no leading period. For an external class, enter the name of the property that uniquely identifies a row, with no leading period.
For an example, see the standard list view rule Log-License-Usage-Daily.List.ALL, which identifies rows by the pzUsageDay property, a time stamp.
|Content Page Name||
Specify a clipboard page name to contain the report contents. (You cannot use
In most cases, accept the default getContent activity. Identify an activity that applies to the Embed-ListParams class to support processing of results from the database operation.
When reporting on rules, you can select getContentForProfile to limit rules to those that are accessible on the requestor's RuleSet list.
If you implement a custom activity for unusual reporting needs, specify a name
The standard activity getLookUpList, referenced in list view rules that support Dev Studio tools, performs specialized processing that bypasses or ignores many fields on the List View rule form. In most situations, if you copy a list view rule that calls getLookUpList, results are more predictable if you change the ActivityName to getContent in your list view rule.
A few list view capabilities are disabled when an activity other than getContent is used.
GetContent activities and external classes
The following additional considerations apply when an activity accesses instances of an external class:
Optional. Specify a maximum number of instances to retrieve for the report contents. As a best practice during testing, accept the default value 500. If you leave this option blank, the system enforces a limit of 10,000.
This field is disabled and the value is ignored, when the Enable Paging? field on the Organize tab is selected.
You can set another default value for this field. Override the default Rule-Obj-ListView.pyDefault data transform, and set the initial value of the pyContentSource.pyMax property to the desired limit.
|Display Count of Records?||
Select to include a message at the top of the output display if not all rows that meet the selection criteria are included in the report output. The message is:
where nnn is the Maximum Value limit. If all records are displayed, a record count displays.
If not selected, the message is disabled.
This option is enabled by default for new reports that you create, but disabled for reports created in versions prior to Version 5.5.
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.
Do not select this check box if the Edit In Excel option (on the Organize tab) is selected, or if your application requires processing of the embedded pages.
If this list view uses the facilities of the Join tab, you must select this option.
As a best practice, select this check box. This option 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. Pega Platform and application rules each have a setting:
When true, these dynamic system settings override the Use Lightweight List check box setting on the Activity rule form.
|Use alternate database?||
Select to have list view processing use the database identified in the
field of the
instance that supports the
class of this list view. See
Setting up reports database.
Chose this option only if the Reports Database field is not blank and identifies a database table that is replicated from the production PegaRULES database. If the report uses JOIN operations that draw from multiple database tables, all tables must be in the same reports database.
When this option is selected, at run time the report uses data from the alternate database. Property pyUseAlternateDb is set to true on the top-level output Code-Pega-List page.
|Report on Descendant Class Instances||
Select to use an
derived from the current rule's
class as the source of report contents at run time.
Select this to allow one list view rule, saved in a framework class, to run against the work items in an implementation class. This capability reduces the number of rules needed when building an implementation of a framework.
This check box is effective only if the Applies To class of this list view rule is derived from the Work- base class.
To determine the Work- class that is used when the report runs, use the Tracer tool, or from the list view display, right-click and select View Source from the browser menu. Search for ViewClass.
This array appears only when the Applies To key part of the list view corresponds to a class group.
Optional. Identify a work type within the class group. The list view output might include properties from this class (work type) when they exist. For example, if the class group has three work types, you can report on the properties defined in the first type, even though these properties do not exist for the other two types.
If this work type is derived from Work-, decide whether you want to join to an implementation class, or in a framework class. At run time, list view rules with a framework class in this field can report on work items in the associated implementation class, if the Report on Descendant Class Instances option is selected.
To run a list view rule, users must hold an access role that provides:
- The ability to execute rules that apply to the Applies To class
- The ability to search instances of the Applies To class
Optionally, you can further restrict the ability to run a list view rule to only those users who hold any one of a list of privilege rules. Order is not significant in this array.
|Class||Optional. Select a class that the system can use to find the Applies To key part of a privilege rule.|
Optional. Select the
key part of a privilege rule.
The system uses the Class and Privilege values with class inheritance to look for the privilege rule.
Optional. Select to allow this list view rule to run on a web node, as part of a
composite application. If selected, users of a composite application can display this report, if the normal access roles, RuleSet list, and privileges requirements are met.
If not selected and a user at a web node attempts to run the list view rule, the rule does not run and a security exception is added to the Alert log.
For security reasons, list view rules that run on a web node as part of a composite application cannot use parameters.
When this list view rule runs on a web node as part of a composite application, the Use Null* setting is selected for all criteria.
- List views
When using the List View rule form, complete the tabs in the following order: