Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Use case: Referencing data in a data page by using parameters

Updated on April 6, 2022

Data pages provide quick, accurate access to the data that your application needs. Calling data pages with parameter values lets the data page provide exactly the data required for a situation, from the most appropriate data source, on demand. The system waits until a user action or some other trigger causes a data request, and then loads the data automatically.

Data pages transform the raw data received from a data source into data that the application needs and can use.

An application that uses data pages, and that passes parameter values to data pages to get the right data to the right place, can build a responsive and rich structure without creating a lot of data pages, activities, and other code. Because Pega Platform supports multiple instances of the same data page, you can use the same design-time definition for multiple contexts simultaneously, within the same or different threads, without affecting other instances that have been loaded into memory. For frequently changing data page references, it is possible to reuse an instance of a data page that is already in memory. There is no need to hard-code and maintain references to data sources.

Data page parameters

Data pages have a Parameters tab on which you can specify the parameters the system can use when referencing that data page.

Specifying parameters for the system to use

Make sure the names are descriptive, so that you and other developers can easily see and understand what sort of values to expect.

You can configure the settings for the individual parameters, including type, requirement, and other settings. Configuring a parameter as required, for example, changes the way the data page provides data to an auto-populated property. An auto-populated property only attempts to load the data page that is supposed to provide data when the required parameters for that data page have values. If there are no required parameters for the data page, an auto-populated property references the data page as soon as one of the listed optional parameters is set.

Passing parameters to data pages using a property

Properties can reference data pages and send parameter values using a section of the property's General tab. For more information, see Passing parameters to data pages from autopopulated properties.

Sending parameter values from a data page

The data page returns information to the property (in this case, a single page) on the customer whose CustomerID the property referenced in the Parameters section. The asterisk beside the field label indicates that a value for this parameter is required when referencing this data page.

In App Studio, you can configure a picklist property with data page parameters to display a list of choices based on a user's selection. For example, display a list of states if the user selects United States from a list of countries.

Passing parameters to data pages

Data pages can provide parameterized data to many other Pega Platform elements besides properties. Any of the following can reference a data page with parameters and receive data appropriate to its situation and requirements:


Case Match



Data Transform

Decision Map

Decision Table

Decision Tree

Declare Expression

Property Alias




How to pass parameters directly to a data page

Each instance of a data page on the clipboard has a fully qualified name, such as D_Customer_pa6671911977865993pz. Do not use the fully qualified name when referencing the data page. Instead, use the name of the data page itself and add the value for any parameters. The data page then determines whether to load a new instance of itself onto the clipboard to respond to the reference, or to refer to the correct instance already on the clipboard.

The syntax is: <data page name>[<comma delimited list of parameter name:value pairs>].

You can refer to a data page with one of several valid forms of this syntax. For example, for D_Customer, you could load or refer to the data page using any of the following forms:

  • D_Customer[CustomerID:“ANTON”,CompanyName:"BigCo"]
  • D_Customer[CustomerID:.CustID]
  • D_Customer[CustomerID:param.CustID]

See Creating a data page and Setting the context of a data page.

How a data page responds to a reference with parameters

When Pega Platform references a data page with parameters, the data page checks whether it can use an existing instance of itself on the clipboard or needs to load a new instance.

Data page checks for an existing instance of itself on the clipboard

If the data page does not find an instance of itself on the clipboard, the refresh strategy defined on the data page requires loading of a fresh instance, or if the parameters passed do not match the parameters used to create an existing instance on the clipboard, then the data page loads a new instance of itself onto the clipboard with the parameterized data required by the current call.

When the data page is able to respond with an existing instance of itself on the clipboard, Pega Platform does not have to retrieve data from the database, which saves time and effort.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us