Use parameters when referencing a data page to get the right data
Summary
Data pages provide quick, accurate access to the data your application needs, when it needs it. 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 the application needs and can use.
An application that uses data pages, and that passes parameter values to them 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 PRPC 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’s possible to reuse an instance of a data page that’s 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 where you can specify the parameters the system can use when referencing that data page.
Make sure the names are descriptive, so you and other developers can see easily what sort of values they expect.
For each parameter you can set its type, whether it is required, and other settings. Setting a parameter to required, for example, changes the way the data page provides data to an auto-populated property (see below). An auto-populated property only attempts to load the data page that is supposed to provide its data when the required parameters for that data page have values. On the other hand, if there are no required parameters for the data page, an auto-populated property references the data page immediately, as soon as one of the listed (optional) parameters is set.
The data page uses the parameters on the Definition tab in two main ways:
- Embedded auto-populate properties. For hierarchical data relationships and contextual referencing, embedded auto-populate properties is the easiest and preferred way to automatically access and source data from multiple hierarchically related data pages.
- Parameterized data pages. When you don't need to maintain hierarchical relationships or case context, you can directly refer to data pages with parameters. See the next section.
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:
The data page returns to the property (in this case, a single page) information related to 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 PRPC elements besides properties. Any of the following can reference a data page with parameters and get back data appropriate to its situation and requirements:
Activity Ant script Batch Case Match Collection Constraint | Data Transform Decision Map Decision Table Decision Tree Declare Expression Function Alias | Infer Interaction 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 (see below) 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 D_Customer, you could load or refer to the data page using any of these:
- D_Customer[CustomerID:“ANTON”,CompanyName:"BigCo"]
- D_Customer[CustomerID:.CustID]
- D_Customer[CustomerID:param.CustID]
When the data page only has one parameter, you don't have to specify the parameter name. You only need to specify the value:
- D_Customer[“ANTON”]
- D_Customer[.CustID]
- D_Customer[param.CustID]
See How to create a data page (declare page) and Tailor data pages to the context in which you use them.
How a data page responds to a reference with parameters
When PRPC 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 there is no instance of the data page on the clipboard, or if the refresh strategy defined on the data page requires loading 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 that the current call requires.
Each time the data page finds it can respond with an existing instance of itself already in the clipboard, PRPC saves time and effort by not having to go back to the database for data.