List View form
Completing the Content tab

Description

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 Single Value properties that correspond to optimized columns in a database table, not properties within the Storage Stream (BLOB) column. The selection criteria can depend on properties that are not Single Value mode, on properties that do not correspond to exposed columns, or on more sophisticated comparisons than provided by this tab. You can either:

• Complete fields on the Organize tab to supplement SQL operations defined on this tab.
• Expose properties as columns before referencing them here.

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 PDN article 23116 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 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.

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 TextEncrypted, special instructions apply to the Condition, Value, and Edit Input fields. See Property rules — Implementing and using the TextEncrypted Type.

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.

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 Is Equal or Starts With.

The system converts the Starts With, Ends With, and Contains comparison conditions to the standard SQL LIKE clause. Vendor-specific non-standard optimizations such as the Oracle CONTAINS feature are not used. If your application contains a list view report that requires such comparisons for tables with a very large number of rows, you can create a custom getContent activity that implements optimized SQL for retrieval.

Specify a comparison value. Possible values are:

• A literal constant, formatted in accordance with the property type. See Constants in expressions. To compare the value with multiple literal constants, surround each with quotation marks and separate them with commas. (Place a backslash character (\) before any quotation marks that appears within the constant.) You can click the gear icon in some situations to review current clipboard values for the property identified in the Field field.
• A fully qualified property reference to a Single Value property that is present on the clipboard at run time. The Type of this property must match the Type of the property in the Field field.
• A fully qualified property reference to a Value List or Value Group property present on the clipboard at run time. The Type of this property must match the Type of the property in the Field field. To compare the value with multiple Value List or Value Group properties, separate the names with a comma.
• The keyword param followed by a period, followed by a parameter that is defined on the parameter page of the calling activity.
• A period followed by the name of a Single Value property that is optimized as a column. This option allows selection based on comparing the values of two properties in the same instance (the same database row), if the types of the properties are identical or comparable.
• A symbolic date, for a Date or DateTime value. When the list view rule runs, this symbolic reference is converted to an actual date or date range based on the time zone of the user and the Condition value. For example, if the user selects Last Year and the Condition value is IS EQUAL TO, the result is a date range between January 1 and December 31 inclusive, of the previous calendar year.

If the Condition field is set to IS NULL or IS NOT NULL, leave this field blank.

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 Value List or Value Group property reference, the comparison is true at run time if the value of the Field field is true for any element in the list or group.

When evaluating either of the two Condition values Greater or Greater or Equal at run time, the result is the same as applying the test to the largest value in a list or group. Similarly, when evaluating the Condition values Less or Less or Equal at run time, the result is the same as applying the test to the smallest value in the group or list. The Value List and Value Group options are most useful for other condition values, such as Contains or Starts with.

Using the Select Values button

When you click the Select Values button, a window opens with one or more of the following tabs:

• Available Values — The system searches the column in the database corresponding to the property in the Field field to collect and display up to 1,000 values for the Field property in a new window. To add literal values to the Value field, select one or more boxes, and click Apply. (You can also type literal constants directly, whether or not they are included in this list.) This tab displays at run time only to users who hold the standard privilege @baseclass.ShowStoredValues. For such users, this option is available at run time when the Display Available Values? box in the Prompt Settings area is selected.
• Valid Values — The system presents values from the Table fields on the General tab of the property referenced in the Field field. To add literal values to the Value field, select one or more boxes and click Apply. This tab displays at run time when the Display Valid Values? box in the Prompt Settings area is selected.
• Compatible Columns — The system lists optimized properties with the same Type as the property in the Field field, as candidates for this field. This tab displays at run time when the Display Compatible Columns? box in the Prompt Settings area is selected.
• Time Periods — For a property of type Date or DateTime, this option allows the selection of a symbolic date such as Yesterday or Current Year.

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.

Description

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.

Specify a comparison value to use when you do not specify a value in the Value field.

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:

• If your PegaRULES database is hosted by Microsoft SQL Server, comparisons are always case-insensitive, so selecting this box does not affect the report contents, but might add processing.
• If your PegaRULES database is hosted by Oracle, IBM DB2, or most other database vendor products, selecting this box might affect which rows display in the report when values occur in mixed case. However, conversion to uppercase can significantly slow database processing.
• Case conversion is meaningful only for properties of type Text, Identifier or Password. Regardless of the database software, case conversion is not needed for numbers, dates, or text that contains only uppercase or lowercase characters.

See the PDN article How to correct the Case Insensitive warning for list view rules.

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:

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 Is Null when the Value value is blank at run time. In this example, the criteria is transformed to "Lastname is null".

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

(A OR B OR C) AND D

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.

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 DateTime parameters in the form MM/DD/YY HH:MM AAA.

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 Decimal criteria corresponds to the input 3.142 from a user with a United States locale. Similarly, a user in France can input of 4/7/6 for July 4, 2006. A United States user enters this date as 7/4/6. The French-locale user can enter 1.000.000 for an Integer value of one million.

Description

Select whether to use the default prompt settings or define custom settings.

When you select Custom, the form changes. On the Pages & Classes tab, identify the class and page name of a page that can hold prompt values. Create and reference a section rule in that class to collect each prompt value. Use the standard control Reporting_SymbolicDates if you want to allow the user to select a symbolic date for a Date or DateTime property. You can also identify a section to hold report output and criteria values.

This label corresponds to the label defined in the criteria row.

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:

• No Access — No part of this row is displayed.
• Read Only — The criteria row is displayed but users cannot alter the criteria.
• All Access — The criteria displays. Users can change the Field, Condition, and Value fields.
• Value Only — The criteria displays. Users can change the Value field. This is the default value.

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 No Access or Read Only.

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.

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.

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.

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.

Specify a text string to display on the search button.

Description

Click the plus icon to add a 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.

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 Platformserver, as specified in the Organize tab.

Select to eliminate duplicate records in the view.

Select to display the key field for each row in the report.

Description

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.

Description

Specify a clipboard page name to contain the report contents. (You cannot use pxResults as the name of this page.)

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 getContent, and identify the activity in this field. Your activity can derive report contents from various means and sources, such as access to external databases through connector rules and calculations, but must place the results on the page named in the Content Page Name field and enforce the Maximum Value limit.

The standard activity getLookUpList, referenced in list view rules that support Designer 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:

• Design the activity to use an SQL alias named pxInsHandle for the key of the external table. For example:

SELECT CUSTOMERID as "pxInsHandle"

• Use only columns of the external table that conform to Pega Platform data type conventions, as follows:

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.

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:

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

Select to have list view processing use the database identified in the Reports Database field of the Data-Admin-DB-Table instance that supports the Applies To class of this list view. See How to use a 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.

Select to use an implementation class derived from the current rule's Applies To 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.

Description

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.

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.

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.