Parameterized Data Page in PEGA. Know all about it.
In the following article, we’ve learnt that the data pages in PEGA are used to read the record(s) from a system of records (aka data source).
In this post, I’m going to cover parameterized Data Pages in PEGA.
What is a parameterized data page?
Data page can also be configured to return a particular record(s) based upon an input value. Such a data page that accepts an input parameter is known as a parameterized data page.
Examples —
- User selects a product name e.g. ABC air-conditioner in a dropdown on an e-commerce website. A parameterized data page accepting the product name as the input — queries a system of records (SOR), and returns the details such as product description, manufacturer, unit price, specifications, etc. — of the selected product.
- User chooses a Province/State in a dropdown list. The selected Province value is passed as input into a parameterized data page that queries a SOR, and returns all of the cities belonging to the selected Province. This data page can be identified as the data source for another dropdown list that would display the cities in the Province selected in the first dropdown.
Problem Statement
In the above article, I’ve described how to populate a dropdown with beneficiary names via a list-structured data page. The user would select a beneficiary name in the dropdown. In this article, I’m going to build on the same example to illustrate how to retrieve the details of the selected beneficiary from the data type through a parameterized data page, and populate those details in the UI. The parameterized data page would accept beneficiary ID as the input parameter, and return their bank account number, bank name, branch, IFSC code from the Beneficiary data type.
The retrieved beneficiary details should be populated in the same screen — Select Beneficiary of the Transfer Funds case type — used in the previous article.
After user selects a beneficiary name in the dropdown, the corresponding details should populate below the dropdown.
Let’s begin!
Step# 1 Create and Configure Parameterized Data Page
a) Create Data Page
Let’s create a new data page from the Create menu -> Data Model -> Data Page as illustrated below.
- Note that the data page identifier always starts with D_, e.g. D_GetBeneficiaryDetails.
- Since, this data page is intended to read a record from the Beneficiary data type, I’ve applied it to the data class linked with the data type, i.e., MyOrg-MyDiv-Data-Beneficiary. Similarly, you can apply your data page to an appropriate class.
b) Data Page Configuration
You need to configure the data page to define its structure, mode, scope, data source and refresh strategy. You also need to parameterize it by specifying an input parameter of Beneficiary ID.
Let’s look at these aspects one by one.
As depicted above, I’ve selected —
- Structure = Page, because the data page is intended to retrieve a single beneficiary record from the data type whose ID matches the input parameter value.
- Object type = MyOrg-MyDiv-Data-Beneficiary, since it would look up in the Beneficiary data type.
- Mode = Read-Only, as it is meant to READ a beneficiary record.
- Scope = Thread. For simplicity, I’ve gone with the default scope of thread. Meaning that the system would load a separate data page instance in memory for every case instance; it would query the data type (database table) once for each case instance. Whereas, you can choose a more appropriate scope for your data page that guarantees minimum queries to database or any other data source, and promotes application performance.
Refer to the below post to learn more about the data page structure, mode, and scope.
- Parameterize Data Page
Let’s configure the data page to accept beneficiary ID as input parameter. Change to the Parameters tab, and add an In-type parameter named BenID as shown below. BenID parameter would hold the beneficiary ID value passed to the data page.
- Identify Data Source
Specify the data source for the data page. I’ve selected the Lookup as the data source as shown below.
Lookup type allows to “look up” a class object by its key. The act of retrieving a record from the Beneficiary data type by beneficiary ID equates to looking up an object in the associated MyOrg-MyDiv-Data-Beneficiary class by its key. Note that I’ve identified beneficiary ID as the class key while creating the data type.
You can read through the following article to learn how to define class key when setting up a data type.
Hence, the Lookup is a suitable data source type in this case.
Next, you need to instruct the data page to look up that particular beneficiary record (object) whose ID equals the beneficiary ID value passed to the data page as the parameter. In the Data Sources section, click on the Parameters link below the Class name field.
It would open a modal dialog. Set Class Key ID = Param.BenID as shown below, and submit.
Note — When referring to a parameter in PEGA, prefix the parameter name with Param keyword.
- Specify Refresh Strategy
Lastly, let’s define the Refresh strategy for the data page. I’ve configured my data page to reload once per interaction as shown below. In other words, it would reload every time a new Transfer Funds case instance is created.
You can choose a different more appropriate refresh strategy for your data page. Read through the following post to know more about other refresh strategy types.
Remember to Save the data page after you’re done with the configuration.
- Test-Run Data Page
Optionally, let’s manually run the data page stand-alone from Actions -> Run to verify whether it’s working as expected or not. Note that this step is not mandatory. The system would automatically run the data page at runtime.
Pass a valid beneficiary ID value (existing in the data type) as BenID parameter to the data page in the Run Data Page window. And, click on the [Run] button.
If there are no configuration issues, the data page would return the matching beneficiary record as shown below.
Step# 2 Create and Configure Single Page Property
a) Create Single Page property
You need to create a Single Page property of type MyOrg-MyDiv-Data-Beneficiary in the Work class (associated with the Transfer Funds case type) i.e. MyOrg-MyDiv-Alpha-Work-TransferFunds, as shown below. I’ve named the Single Page property as BeneficiaryDetails.
Note that the Page definition is set to MyOrg-MyDiv-Data-Beneficiary which means that this property can be viewed as an object of the Beneficiary data class. Since, the property is created in the Work class, the data class object can be perceived as being embedded in another object of the Work class i.e. pyWorkPage. It may sound confusing at this moment, but, don’t worry. It would become more clear when we look at the page structure in the clipboard later on.
b) Source Single Page property through Data Page
Thereafter, you need to configure this Single Page property to source it with data through the parameterized data page. In other words, the beneficiary record returned by the data page would be copied to the Single Page property.
In the Data access section of the property ruleform, select “Copy data from a data page” radio button, and select the Data Page D_GetBeneficiaryDetails as shown below.
Provide the BenID parameter value. The selected beneficiary ID is stored in SelectedBeneficiary property (referred in the dropdown control) of the Work class. Pass the property value as parameter to the data page as depicted below.
It would load the data page with the beneficiary record in the data type that matches the input beneficiary ID, and in turn copy the contents of the data page to the BeneficiaryDetails Single Page property.
Save the Single Page property.
Step# 3 Configure Section Rule
Lastly, you need to configure the section rule to refer the above Single Page property in order to populate in the UI, the details of the beneficiary — selected in the dropdown — retrieved through the parameterized data page.
Open the section rule associated with the “Select Beneficiary” step of the case life cycle.
a) Include another section
In this section, I’m going to include another section below the dropdown.
The included section is required to execute in the page context of BeneficiaryDetails Single Page property. Thus, I’ve selected the Page context, and provided the Clipboard page accordingly as depicted below.
Note that I’ve specified Class as MyOrg-MyDiv-Data-Beneficiary because the Single Page property is an object of this class. I’ve chosen SelectedBeneficiaryInfo as the name of the section.
If you want to learn in more detail about how to include a section in another using a Single Page property as the page context, I would suggest you to go through the below post. I’ve also shared more basic information about section, flow action and flow rules in the same article.
b) Create and configure included section
Now let’s create the included section by clicking on the crosshair icon adjacent to the section name in the above modal dialog.
And, configure it to include the fields to display beneficiary information such as Account Number, Bank Name, Branch and IFSC code.
Note — I’m going to convert to full section editor before adding the fields.
Since, user is required to only read beneficiary information in UI, and not edit it, we can add relevant controls from the Data display menu (shown below) to display the information.
I’ve used Data display -> Text control for all of the fields, and configured them as depicted below.
I’ve also changed the Dynamic Layout format to Inline grid double.
It would arrange the fields in the 2 rows X 2 columns format as shown below.
Save the included section rule.
Move back to the main wrapper section (SelectBeneficiaryForm), submit the already open “Section Include” modal dialog, and save the main section.
c) Add Action set to Dropdown
In the main wrapper section, add an action set to the Beneficiary Name dropdown as shown below. It would trigger Post value and Refresh-This section actions on change of the selection in the dropdown.
On change of the dropdown selection, the Post value action would update the selected beneficiary ID value on the server side without having to submit the Select Beneficiary user screen. The data page would then use this beneficiary ID to retrieve the respective beneficiary details from the data type, and copy to the Single Page property. Thereafter, we need to reload the part of the screen in order for it to reflect the last copied details. This is achieved by the Refresh-This section.
Note — Remember to save the section rule after adding the action set.
Again, you can read through the following two articles to learn more about how to convert section to full editor, and add fields to it, change the dynamic format layout, and add an action set to a control.
This completes the rule configuration part.
Step# 4 Validation
Let’s move to the validation part.
I’m going to start by creating a Transfer Funds case through Create menu -> New -> Transfer Funds as shown below.
Alternatively, you can also create the case instance by clicking on the [Save and Run] button on the Transfer Funds case type.
The Select Beneficiary screen would come up. Select a beneficiary name in the dropdown.
With Jane Doe selected as beneficiary, the system fetches and displays their respective details as depicted below.
Change to a different beneficiary name in the dropdown. The details would also change in the screen.
Optionally examine page structure in clipboard
You can optionally take a look at the page structure in clipboard for a better understanding of what pages are created in memory.
As we already know that pyWorkPage is an object of the Work class i.e. MyOrg-MyDiv-Alpha-Work-TransferFunds.
Expand the pyWorkPage node. You would find BeneficiaryDetails node under it. This means that the BeneficiaryDetails Single Page property is created as an object of the MyOrg-MyDiv-Data-Beneficiary class, and is embedded in pyWorkPage.
Additionally, let’s look at the parameterized data page in clipboard. Expand the Data Pages node. Thereafter, the Thread node under it (because the data page has the scope of thread).
You would find a separate instance of the data page for each beneficiary name selected in the dropdown. Note that for each instance, the respective beneficiary ID parameter value is different.
Click on the individual instance to review the contents.
Step# 5 Optionally limit to a single data page
As we saw earlier that multiple data page instances are present in clipboard at same time for the different beneficiary names selected in the dropdown. You can also choose to limit to a single data page instance at a time by selecting the corresponding checkbox in the Data Page ruleform as shown below.
Note — Remember to save the data page after making the change.
In the upcoming article, I’m going to cover another common use case on the parameterized data pages of populating a dropdown with options based upon the value selected in another dropdown. You may, for example, want to populate a dropdown with a list of cities bases upon the State/Province value selected in another dropdown. So look out for it!
To learn more about Pega, be sure to Follow on Instagram, Facebook & YouTube
YouTube:
Facebook:
Instagram:
