Iterating over a Page List in a Data Transform in Pega 7

In this example, a Data Transform is used to iterate over a data page that uses a list structure. See this example on how to create a data page using the Data Table Wizard. For this example, a data page that is backed by a data table of car makes is used to show how to iterate over it in a data transform.

Related Posts


  1. Description of Data Table for Class ABC-Insurance-Data-Make Used in this Example
  2. List Data Page for ABC-Insurance-Data-Make Rule Instances
  3. Creating a Data Transform for Iterating over the Data Page

  • The screen shot below shows an example of a Data Table. In this case, the rows represent car makes. See the link under Related Posts on how the data table was created.
  • The data table contains instances of the class ABC-Insurance-Data-Make. This class has the properties ID (Integer) and pyLabel (Text).
  • The ID is a unique identifier (Key) and the pyLabel property contains the actual car make values.

Pega 7 Edit Data TAble Instances

  • The below screen shot shows the configuration of a list-structure data page named D_Makes. Its purpose is to store a list of car makes. The Data Page Definition section is configured as follows:
Structure: list
Object Type: ABC-Insurance-Data-Make
Scope: Node
Data Source: Report Definition
  • Node scope causes the data page to be available to all users on a node (i.e. it will be loaded once per PRPC node).
  • The Data Table Wizard creates a default Report Definition. Here it is named dataTableListReport and it returns all rows in the underlying data table.

Pega 7 Edit Data Page - Data Page Definition and Data Sources

  • The data page can be unit tested by clicking on ActionsRun.
  • The XML of the data page will be shown and the node pxResults (a PageList) will contain all of the rows in the data table.

Run DataPage XML Output

  • After running the data page once, it will appear in the Clipboard Tool under Data Pages > Node.
  • Due to its Node scope, the data page D_Makes will remain on the clipboard until the PRPC instance is restarted or the data page is deleted using the Designer Studio or the Clipboard Tool is used to delete it (see the Actions button in upper right-hand corner).

Pega 7 Clipboard Viewer Data Page pxResults

  • In the Designer Studio, a data transform can be created using +Create > Data Model > Data Transform.

Pega 7 Designer Studio - Create New Data Transform

  • The Data Transform Record Configuration form requires the user to enter a name, here it is IterateOverMakes and to select an Apply to class. Here, the class is ABC-Insurance-Data-Make.
  • Click on the Create and open button to create the data transform rule.

Pega 7 Create Data Transform Form - Iterating over Data Page pxResults

  • On the Parameters tab, an output parameter named MakeString of data type String is defined.
  • It will be used to return a comma-separated String of car makes that is created by the data transform while it iterates over the data page D_Makes.

Pega 7 Data Transform - Parameters Tab Output Parameter

  • On the Pages & Classes tab, the data page D_Makes needs to be listed with a class of Code-Pega-List.
  • The class Code-Pega-List has a page list property named pxResults which holds instances of the object type specified when the data page was configured. Here the object type is ABC-Insurance-Data-Make.
  • Specify the class of D_Makes.pxResults as shown below.

Pega 7 Data Transform - Pages and Classes Tab

  • On the Definition tab, the first row will use the action For Each Page In to iterate over the D_Makes.pxResults page list.
  • The checkbox Also use each page as source context in the Source column should be checked so that the . dot operator can be used to refer directly to the current page of the iteration instead of having to use D_Makes.pxResults(<CURRENT>).
  • In the second row, param.MakeString is concatenated with the pyLabel property of the current ABC-Insurance-Auto-Make instance.
  • The third row uses a simple expression to remove the last comma in the comma-separated string after the iteration. The complete expression is:

Pega 7 Data Transform - Definition Tab

  • Save the data transform and open the Tracer. Make sure that the check boxes for Start and End for data transforms under the section Events to Trace are checked.

Pega 7 Tracer Settings - Enable Data Transforms

  • The data transform can be unit tested by selecting Actions > Run and then clicking on the Execute button in the new window. Note: Make sure that the Tracer is running before executing the data transform.

Pega 7 Test Page for Running Data Transform

  • A new window opens and shows XML output from executing the data transform. The pzStatus will contain the value valid if the exeution was successful.

Pega 7 Data Transform - Run XML Output pzStatus is valid

  • Switch to the Tracer window and search for the row where the event type shows Data Transform End and click on that row.

Pega 7 Tracer Window - Data Transform End step

  • A new window opens, showing the properties of the test page that was created for running the data transform. Click on the link =unnamed= link of the Parameter Page Name property in the TraceEvent[8] page.

Pega 7 Tracer - Properties of Page TraceEvent

  • This will open the TraceEvent[=unnamed=] page, showing the output parameter named MakeString which was set by concatenating the car make values while iterating over the data page D_Makes to generate a comma-separated String value of the car makes.
  • The page also shows some Pega out-of-the-box properties, prefixed with py or pz.
  • In the below screen shot, a property named pyForEachCount with a value of 8 is shown. This is the number of iterations that were executed by the For Each Page In data transform action (i.e. the number of items in the D_Makes.pxResults list).

Pega 7 Tracer - Properties on Page TraceEvent - Data Page Entries

  • Note: The tracer also shows that Code-Pega-List maintains the order of the entries in the data table.
  • Pega is implemented in Java and the underlying Java interface- and implementation classes for Code-Pega-List are java.util.List and java.util.ArrayList from the java.util package.

Please register to add comments or feedback!

Example of Pega 7 Auto-Complete Control Backed by Data Table

The following example shows how to create a data table and how to use it to populate an auto-complete UI control in Pega 7. The auto-complete control allows a user to type a search term and it will present matching options in a dynamic list as shown in the screen shot below.

Pega 7 Auto Complete Control Example

Related Posts


  1. Creating a new Data Table Using the Data Table Wizard in Pega 7
  2. Populating an Auto-Complete Control from a Data Table in Pega 7

  • Open the data tables view by clicking on Designer Studio > Data Model > Data Tables > Data Tables:

Pega 7 Designer Studio - View Data Tables List

  • The data tables view shows a list of existing data tables:

Pega 7 Data Model List of Available Data Tables

  • Click on the Add a new Data Table button. This will open the Data Table Wizard.
  • In this example, a new data table will be created for storing car makes.
  • The class name should be derived from the organization name, here ABC and the application name, here Insurance and the derived class, here -Data.
  • Therefore, the class name in this example is ABC-Insurance-Data-Make.
  • The class for this data table should derive from the -Data class, so the DERIVES FROM field will be ABC-Insurance-Data.

Pega 7 Data Table Wizard - Generate Data Table

  • The check box CREATE DATA PAGES? must be checked in order to see the LOOKUP DATA PAGE and LIST DATA PAGE fields. Completing these fields will cause the wizard to create data pages that can be used to retrieve a single instance of ABC-Insurance-Data-Make or a list of instances.
  • The check box CREATE DEDICATED DATABASE TABLE? should be checked since this data tables provides reference data and should be included when migrating the application.
  • In this example, the intention is to display an auto-complete UI control that allows a user to select from a list of car makes.
  • The ABC-Insurance-Data-Make class will have 2 properties: ID and pyLabel.
  • The ID will be a unique numeric identifier and the inherited pyLabel property of type text will store the car makes such as Honda and Toyota. After entering the configuration data, click on the Generate button to continue.


  • The wizard generates the data table and Associated Rules such as a default data transform, a validate rule and the lookup data page (D_Make) and list data page (D_Makes) using the names specified in the configuration name.
  • After clicking on the Close button and refreshing the data table view, the new data table appears.
  • At this point, the row count is 0 since no data records have been created yet.

Pega 7 Data Table View - New Data Table Available

  • Click on the cogwheel icon in the EDIT column in order to open a view that allows adding rows to the data table.

Pega 7 Data Table View - Edit Data Table Instances

  • Click on the + icon to insert ABC-Insurance-Data-Make instances into the data table.

Pega 7 Data Table View - Insert Data Table Instance

  • Clicking on the check mark icon to the right of the Label text box will insert a new record into the data table.
  • The data table will enforce the unique constraint for the ID column and display an error icon and a tool tip when the user attempts to insert a row with an existing identifier.

Pega 7 Data Table View - Insert Instance Error - This instance already exists

  • Once the data has been added, the dialog showing the data table instances can be closed.
  • Refreshing the data table’s view shows the new row count:

Pega 7 Data Table View - Showing Row Count

  • Here, we want to set a case instance property from a selected value of an auto-complete control.
  • In the sample application, there is a case type rule called ABC-Insurance-Work-Auto that will be used to encapsulate auto policy work.
  • This case type rule has a property called Make that is a single value property of type text.

Pega 7 Application Explorer - Case Type Property

  • Create a new Section rule for the ABC-Insurance-Work-Auto case type and insert e.g. a Dynamic Layout.
  • Click on the Advanced drop down control in the Deign tab and drag and drop the Auto-Complete control into the dynamic layout.

Pega 7 Designer Studio - Edit Section - Advanced - Add Auto Complete Control

  • Click on the auto-complete control and then on the cogwheel icon in the upper right hand corner.

Pega 7 Designer Studio - Edit Section - Configure Auto Complete Control

  • This will open a dialog for configuring the auto-complete field. In the Property field, type a . (dot) to see all available properties of the ABC-Insurance-Work-Auto case type and select the Make property as shown below.

Pega 7 Designer Studio - Auto Complete Control - General tab

  • A Placeholder can be used to display a default text in the auto-complete control, when no value is selected.
  • In the LIST SOURCE section, select Data page in the type drop down field and enter the name of the list data page that was created using the Data Table Wizard, in this case: D_Makes.

Pega 7 Designer Studio - Auto Complete Control - General tab - Placeholder and List Source

  • Alternatively, instead of using the data page, the default Report Definition, here named dataTableListReport, which was also created by the Data Table Wizard can be used.

Pega 7 Designer Studio - Auto Complete Control - List Source Configuration

  • Caution: Using a data page has performance advantages since it can be configured to be cached (see Load Management tab of edit data page view), whereas the report definition is run every time the auto-complete is loaded.
  • When using a report definition, the SEARCH RESULTS CONFIGURATION section of the dialog is used to select the data source property that will be used for the search and for displaying the auto-complete suggestions list.
  • In this case, the auto-complete needs to search the pyLabel property of the ABC-Insurance-Data-Make instances in the data table.
  • The Match start of string check box causes the auto-complete search to show suggestions where the entered string matches the beginning of Makes instances.
  • E.g.: When the user enters Me in the auto-complete control, the list of suggestions should show all car makes where the pyLabel value starts with Me.

Pega 7 Designer Studio - Configure Auto Complete Control - Search Results Configuration

  • Click on OK to close the dialog and then click on Save to apply the section changes.
  • The auto-complete can be unit-tested by clicking the Actions button and selecting Preview.

Pega 7 Auto Complete Control Example

  • The section will be rendered and display the auto-complete control. Here, the user entered Me and the list of suggestions shows one item: Mercedes-Benz since it is the only make that starts with Me.
  • When the user click on an item in the suggestions list, that item’s pyLabel value is used to set the value of the Make property of the ABC-Insurance-Work-Auto instance on the Clipboard.