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
Criteria
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.
In the
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
Single Value
property as a database column, after which you can specify it. See
Property optimization.
Field | Description |
Criteria |
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. |
Label |
Optional. If you enter multiple criteria, enter a letter or letters that uniquely identify each row. This label identifies this row in the
Logic
field.
For example, enter A for the first row, B for the second row, and so on. The Logic value must mention each label. |
Field | 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. |
Condition |
Select a comparison condition, such as
Is Equal
or
Starts With .
The system converts the
|
Value |
Specify a comparison value. Possible values are:
If the
Condition
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
Value
field contains a
When evaluating either of the two
Condition
values
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 | Description |
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
Field Value
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.) |
Ignore Case |
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. |
Use Null* |
This option is meaningful only when the entry in the
Value
field is not a constant. By default, if the value for the
Value
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: IsNull Example 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
Use Null*
box to force the
Condition
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. |
Logic |
Optional. Using the labels entered in the
Criteria
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 (
Integer ,
Double , or
Decimal
),
DateTime , and
Date
specified in the
Criteria
section or trend section from a locale-specific format.
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
|
Prompt Settings
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
All Access
or
Value Only
, the user can review or enter criteria at run time.
Field | Description |
(no label) |
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. |
Prompt Mode |
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
Criteria
row must allow user input, and the
Prompt Mode
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
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
Table
fields on the
General
tab of the property referenced in the
Field
field.
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
Applies To
class (or an ancestor class) that are optimized as columns and match the
Type
of the property referenced in the
Field
field.
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.
Field | Description |
Get These Fields | Click the plus icon to add a field. |
Field |
Specify a property reference in the class corresponding to the
Applies To
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. |
Sort |
Select
Ascending ,
Descending , or
No Sorting
to control whether and how this property affects sorting the rows of the report.
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 list view report can allow users to select a row and operate on that row, running an activity or JavaScript function specified in the Events Handling area of the Format tab.
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
pxInsHandle
on each page in the
pxResults
list. 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”
Field | Description |
Key of a Row |
For an internal class, enter
pzInsKey
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. |
Report Source
Field | Description | ||||||||||||||||||
Report Source | |||||||||||||||||||
Content Page Name |
Specify a clipboard page name to contain the report contents. (You cannot use
pxResults
as the name of this page.)
| ||||||||||||||||||
Activity Name | 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
other than
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:
|
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.
Found more than the maximum number of records (nnn)
where nnn is the Maximum Value limit. If all records are displayed, a record count displays.
Displaying nnnn records
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:
- clipboard/lightWeightList/enableForCorePRPCRules - This setting is true by default.
- clipboard/lightWeightList/enableForCustomerRules - This setting is false by default.
When true, these dynamic system settings override the Use Lightweight List check box setting on the Activity rule form.
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.
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.
Sub-classes
This array appears only when the Applies To key part of the list view corresponds to a class group.
Field | Description |
(n) |
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. |
Security
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. |
Privilege |
Optional. Select the
Privilege Name
key part of a privilege rule.
The system uses the Class and Privilege values with class inheritance to look for the privilege rule. |
Web Enabled? |
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. |
Previous topic List views Next topic Display Fields tab on the List View form