Back Forward Report Definition form
Completing the Design tab

  1. About
  2. New
  3. Design
  4. Data Access
  5. User Interactions
  6. Pages & Classes
  1. Parameters
  2. History
  3. More...

  Show all 

Information on this tab describes the basic content and layout of the report. Complete the Columns To Include section at the top of the tab to define the columns to include, and how to format and display their values, and the Rows To Include section to describe which class instances or records to include.

TipThis tab can become wide if you include many columns on your report, since columns are displayed horizontally. To display more of the content, click the collapse arrow (Row Collapse Arrow) in the portal to temporarily hide the navigation panel. When you finish working with this tab, click the expand arrow (Row Expand Arrow) to display the navigation panel again.

 Columns To Include

This section defines the columns in the report. Grouping and group order are determined automatically.



Column Name

 Choose a Single Value property, identified by a property reference. Properties must be exposed properties.

Instead of an existing single value, you can use the Function Builder to select a function template and provide database columns for it to operate on. The column in the report then displays the result of the SQL function. Process Commander includes an extensive set of SQL functions: see Atlas - Standard SQL function rules. If none of them exactly satisfy application requirements, you can create a custom SQL function template that can be selected in the Function Builder: see About Function Alias rules.

To start the Function Builder, click the Function Builder icon ( Function Builder icon) to the right of the column for which you want to display the results of a SQL function. See Function Builder.

note about declare indexesIf your application has declare index rules, you can choose one as the property for a column. Type part of the declare index name, then click the down-arrow. The rule appears as one of the "Best Bets":

selecting a declare expression

Column Heading

Optional. Enter a column heading to be used for this column on the report. By default, the label defined for the selected property will appear as the Column Heading for the column.

Column Width

Optional. Enter the desired column width for the column as a percentage of the window's width or in pixels. Enter an integer followed by either px or % to indicate the units for the value entered.


Choose one of the built-in functions COUNT(), COUNT DISTINCT(), SUM(), AVG(), MAX(), or MIN() if you wish to aggregate the data in the column.

Format Values

Optional. Select a control rule to use in formatting the values for the column. Leave blank to use the control rule associated with the property rule.
Many control rules accept parameters. Click the magnifying glass icon () to the right of the control value to enter parameters for the control rule.
Click the pencil button (Pencil) to open the control rule.

Sort Type

Optional. For each sorted column, choose one of the following:

  • Ascending (default): Values for the column will be sorted in ascending order, from lowest to highest.
  • Descending: Values for the column will be sorted in descending order, from largest to smallest.
Sort Order

Optional. If you are sorting the values for more than one column on the report, enter a value for each sorted column which is an integer between 1 and the number of sorted columns.

Display Values Across Columns

Optional. If this option is checked, values for the column will be displayed horizontally.  Each value for the column will appear as a column on the report.  Displaying one or more columns horizontally lets you create cross-tab and pivot table reports.


Optional.  If this option is checked, this column is not displayed on the report.  This option lets you, for example, sort rows on a report based on a column that is not displayed.

At the bottom of this section is the Enable Grouping checkbox. This allows you to group report data by one or more of the columns which have numbers in their Sort Order fields. When you check this option, a line of text and a number entry field appear to its right: "Display values in columns 1 - [1] as group headings." This allows you to select as many columns having sort order numbers as you wish. You selection must be something like 1- [3], not 1 - [2, 4]; that is, the selection must start with the first sort-order column and continue without skipping any sort-order column numbers.

The result of using this feature is that report data displays grouped by the specified columns' values, and the column names appear as the heading for each group.

 Rows To Include

This section defines filter conditions, tests which determine which rows qualify to appear in the report display. If you leave this section empty, the report selects all instances of the Applies To class (or instances or records of whatever sources are indicated on the Data Access tab) up to the limit in the Maximum Number of Rows to Retrieve field on the Data Access tab.

At the top of this section is a Remove Duplicate Rows checkbox. When this option is selected, the report discards duplicate row entries.

Each row of this array in this section identifies a filter condition. The order of rows in this array is not significant. Process Commander converts information in this array to an SQL WHERE clause when retrieving data from the database.

Advanced feature If you define filter conditions in this section, you must enter a logical expression in the Conditions text box in the section header. Using the labels entered in the Conditions array, the logical expression defines how the system is to combine the conditions. 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 enter an expression like (A OR B OR C) AND D in this text box. The notation is the same as for the logic statement in When condition rules.

Advanced You can specify only Single Value properties in the Column field. Each property you identify for selection criteria must be exposed as a column in the database table.




Enter a letter or letters that uniquely identifies this row, to reference this row in the Logic field. These can be as simple as A for the first row, B for the second row, and so on. The Logic value must mention the label for each Condition in this section.


Enter a property reference for the conditions. The property referenced must be exposed as a database column in the Apple To class for the report value, or else be a fully qualified value to a clipboard page that is always present on the clipboard, such as the requestor page or process page.

NoteIf the Type of this property is TextEncrypted, special instructions apply to the Condition and Value fields. See Property rules — Implementing and using the TextEncrypted Type.

NoteIf you enter .pxObjClass here and the Applies To key part of this report definition rule is a framework class, at runtime the report execution 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 report definition rule into the implementation class. To enable this capability, select the Report on Descendant Class Instances checkbox on this tab.


Select a logical operator for the comparison condition, such as Is Equal or Starts With.


Enter one of the following options as a comparison value:

  • A literal constant, formatted in accordance with the property type. See Constants in expressions. To compare the Column value with multiple literal constants, surround each with double quote characters and separate each with a comma. Place a backslash character \ before any double quote character that appears within the constant. As described below, you can click the magnifying glass icon () in some situations to review current clipboard values for the property identified in the Column field.
  • A fully qualified property reference to a Single Value property that is present on the clipboard at runtime. The Type of this property must match the Type of the property in the Column field.
  • A fully qualified property reference to a Value List or Value Group property present on the clipboard at runtime. The Type of this property must match the Type of the property in the Column field. To compare the Column value with multiple Value List or Value Group properties, separate each property name with a comma.
  • A reference to a parameter that is defined on the Parameters tab, in the format
  • The name of another Single Value property that is exposed as a column. This allows comparison of the values of two properties in the same instance (database row), if the types are identical or comparable.
  • A symbolic date, for a Date or DateTime value. When the list value rule executes, 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 Relationship 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 runtime if the value of the Column field equals (or is greater than, or is contained in, and so on) any one of the entries.

When the Value field contains a Value List or Value Group property reference, the comparison is true at runtime if the value of the Column 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 runtime, 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 runtime, 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 Pick Values pop-up window

For guided assistance in completing this field, click the magnifying glass icon (). A pop-up window appears with one or more of these tabs:

  • Available Values — The system searches the column in the database corresponding to the property in the Column field to collect and display up to 1,000 values for the Column property in a new window. To add literal values to the Value field, check one or more boxes and click  Apply. (You can also type literal constants directly, whether or not they appear on this list.) This tab appears at runtime only to users who hold the standard privilege @baseclass.ShowStoredValues. For such users, it is visible at runtime when the Display Available Values? box in the Prompt Settings area is selected.
  • Valid Values — The system presents values determined by the Table Type specification on the General tab of the property rule referenced in the Column field. To add literal values to the Value field, check one or more boxes and click  Apply . This tab appears at runtime when the Display Valid Values? box in the Prompt Settings area is selected.
  • Compatible Columns — The system lists exposed properties with the same Type as the property in the Column field, as candidates for this field. This tab appears at runtime when the Display Compatible Columns? box in the Prompt Settings area is selected.
  • Time Periods — For a property of type Date or DateTime, allows the selection of a symbolic date such as Yesterday
    or Current Year.
Prompt Mode added on 3/17/2010

Select a value to determine how a user of this report can modify the condition in this row when the report is run and displayed in the Report Viewer.

  • Full Access — The condition appears in the Filters link in the header of the report. Users can change the Column, Relationship, and Value fields (this is the default Prompt Mode value).
  • Value Only — The condition appears in the Filters link in the header of the report. User can only change the Value field within the condition.
  • Read Only — The condition appears in the Filters link in the header of the report, but cannot be changed by users.
  • Hide — The condition is not displayed in the Filters link in the header of the report, and cannot be changed by users.
Use Null, If Empty?

This box is important only when there is no value at runtime specified in the Value field. By default, when the Value field is empty at runtime, the criterion defined by this row is ignored; processing is the same as if this row is not present.

For example, assume the criteria in a row is:

Use Null
If this report rule executes at a time when Param.Letter has the value "C", this criterion limits the report to contain only instances in which the Lastname property value starts with the letter C. However, if the same rule executes again when the Param.Letter parameter has no value, this criterion is dropped, so instances with any Lastname value (or none) are selected.

In situations where this default behavior is not desirable, select the Use Null* box to force the Condition value to become Is Null when the Value value is blank at runtime. In the above example, the criterion is transformed to "Lastname is null" — which is different from having no restriction on Lastname.

Ignore Case - added on 3/17/2010

Select to have runtime comparisons of the Field value and the Value value be case-insensitive; that is. "Smith" matches "SMITH" and also matches "sMiTH".

If selected, then at runtime "a" matches "A" and is less than "B".

Clear to cause tests of the Field value and the Value value to occur without case conversion. In this case, "a" is greater than both "A" and also greater than "B".

In most cases, leave this box cleared. Select this 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, selecting this box does not affect the report contents, but may add processing.
  • If your PegaRULES database is hosted by Oracle, IBM UDB or most database vendor products, selecting this box may affect which rows appear in the report when values occur in mixed case. Conversion to uppercase can significantly slow database processing.
  • Case conversion is meaningful only for properties of type Text, Identifier, or Password. Regardless of database software, case conversion is not needed for numbers, dates, or text that contains only uppercase or lowercase characters.

See Pega Developer Network article PRKB-25511 How to correct the Case Insensitive warning for list view rules.

 Rank Results

You can limit the number and type of rows of data the report returns. The instruction is in this format: "Display [top ranked / bottom ranked] [QUANTITY] Rows [by group?] based on [COLUMN]":



top ranked/ bottom ranked Depending on your choice, the report will return either the rows of data that satisfy the criteria best or worst.
quantity The maximum number of rows
by group? Choose Overall to apply the maximum number to the whole report. Choose For Each Group in a group-by report to apply the maximum number to each group.
column Choose from the options provided the data column that will be evaluated. Click the function icon to the right of the field to select a function to process the data in the selected column to simplify its ranking; for instance, for a column displaying numbers in text form, you might convert the values using the function [Text Value] converted to an Integer value.

 General Report Settings



Report Title

Enter the title of the report.

Use custom row section for displaying rows

Optional. Check this option to use a custom row section to format the rows in the report this rule generates. A field appears where you can select the section; select the edit icon that appears beside the selection field to create a new custom section.

Display in Report Browser?

Optional. Select to indicate that the report is to be displayed in the Report Browser of the Manager portal. See Manager portal — Using the Report Browser.

Related topics Working with the Report Viewer
Report Definition rules — Defining and Editing Charts
Report Definition form — Completing the Chart Definition dialog
Atlast Atlas — Standard Report Definition rules
definition Filter

UpAbout Report Definition rules