Use case: Referencing data in a data page by using parameters
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.
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.
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.
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:
Activity Case Match Collection Constraint | Data Transform Decision Map Decision Table Decision Tree Declare Expression | Property Alias Scorecard Strategy When |
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.
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.
Previous topic Use case: Loading data into a page property Next topic Errors in data sources