What is Data Page in PEGA? How to use it to populate a dropdown list?
What is a Data Page?
A data page is essentially a clipboard page — containing the reference data — that is cached in memory. It is loaded once with data from the source, and cached. The system refers to the cached instance for subsequent calls to the data page. This, it saves the unnecessary, reoccurring, costly queries or trips to the data source (database or external system) to retrieve data, and improves performance of the application. It is reloaded from the source after its contents are determined stale as defined by its refresh strategy (read on to learn about it) in order to keep it up to date with the source.
Data Source for a Data Page
Every data page has a data source (a system of records) from where it obtains its data. The data source can be a database table (internal or external), an external system with APIs, etc. A data page can hold a single record or a list of records. In most cases, the record is an object of a data class or integration class.
Critical aspects of a Data Page —
#1 Structure — It indicates the structure of data page. Available structure types are:
- Page — A page-structured data page contains a single record/object.
- List — A list-structured data page holds a list of records/objects.
#2 Mode — It signifies the purpose of data page. Allowed modes are:
- Read-Only — A read-only data page reads from its data source. The contents of the data page can NOT be manipulated via data transform or activity after the data load.
- Editable — The contents of an editable data page can be edited or manipulated after it is loaded from a data source.
- Savable — A savable data page is instead used to write (create or update records) to a system of records.
#3 Scope — It determines the scope of data page in memory. Different scope values are:
- Node — A single instance of the data page is created in memory at node (JVM) level which is shared between all the requestors. It is used to hold data/information that would be same for all the requestors/users. E.g. — a node-level data page containing a list of financial products offered by a bank to its customers.
- Requestor — A separate copy of the data page is created in memory for each requestor. The contents of each copy differ depending upon its respective requestor. E.g. — a requestor-level data page for a list of bank accounts held by a depository. Since, the list would vary from depositor to depositor, so would the contents of the data page.
- Thread — A separate data page copy is created for each thread or case. E.g. — a thread-level data page to read the details of a particular bank account related to a case. The contents of the data page may vary from case to case.
Note — In this article, I’m going to demonstrate a page-structured, read-only mode, thread-level data page. List structure, editable or savable modes, and other scope types — requestor/node are going to be covered in future articles.
Refresh Strategy of Data Page —
The refresh strategy of data page determines when the contents of the data page would be considered stale, and the page would be re-loaded in memory with fresh data from its data source.
The refresh strategy is defined in the Load Management tab of the data page ruleform as shown below.
You can define a refresh strategy to reload data page once per interaction, or reload if it is older than specified no. of days, hours, minutes and seconds. You can also use a WHEN rule to define conditions that if satisfied, the system should not reload the page.
Alright! With the theory out of the way, let’s begin with the practical :)
Step # 1: Create a Case Type
I’ve created a Case Type — Transfer Funds that would allow a user (Account holder) to send money to another person (known as beneficiary).
If you’re curious to learn more about how to create a new Case Type in PEGA, and design its life cycle, then I’ve pinned below an article for you to read through wherein I’ve described the process in detail.
Step # 2: Build a User Interface with a dropdown
In the first step — “Select Beneficiary” of the above case life cycle, the account holder is required to select a beneficiary from a dropdown list. In this article, I’m going to demonstrate how to source the dropdown list with beneficiary records — stored in a Data Type, through a Data Page.
For the first step, I’ve developed a user interface (user screen) with the dropdown. I’ve created and configured the associated flow rule, flow action, and section rule as shown below.
I’ve already covered in detail how to design the user interface for a step in a case life cycle with the help of flow action and section rules in the following two articles. You may check them out to know more.
Step # 3: Create a Data Type
Additionally, I’ve created a Data Type, named Beneficiary — that stores a few beneficiary records. This data type is going to serve as the data source for the data page. It would be loaded with the beneficiary records from this data type.
Note that the data class associated with the Data Type is MyOrg-MyDiv-Data-Beneficiary. I’ve chosen to create the data type in the division layer. You can create in a different layer that suits your requirement.
I’ve added to the data type, the following fields that identify a beneficiary and their bank account.
If you’re interested to learn more about how to create a Data Type in PEGA, and add fields & data records to it, you can checkout the below article.
Step # 4: Create and Configure Data Page
When you add the first record to a data type, PEGA automatically generates three types of data pages, namely —
- Page-structured data page intended to read a single record from the data type.
- List-structured data page meant to read multiple records from the data type.
- Savable data page that can be used to create or update a record in the data type.
You can view the auto-generated data pages in the Sources tab of the Data Type.
The auto-generated data pages can also be seen in the Data Types Explorer.
In my case, D_Beneficiary is the page-structured data page. Note that the Structure is set to Page and the Mode is Read-Only in the Data page definition below.
D_BeneficiaryList is the list-structured data page. Note that the Structure is set to List and the Mode is Read-Only in the Data page definition below.
And, D_BeneficiarySavable is the savable data page. Note that the Mode is set to Savable in the Data page definition below.
Important — The name of a data page, regardless of its structure or mode, always starts with D_
Note — In this demonstration, I’m going to use the auto-generated data page. However, instead of using the auto-generated data pages, you can also create your own data pages.
Since, I need to read all (multiple) of the beneficiary records from the data type, and source the dropdown list with them, I’m going to use the list-structured, read-only mode data page i.e. D_BeneficiaryList.
By default, the scope of a data page is Thread. Watch this short video to avoid common mistakes with the data page scope.
- Identify data source for data page
Let’s go back to the data page ruleform, and take a look at its data source. As shown below, the standard Report Definition of DataTableEditorReport is by default identified as the data source for the data page. It means that the data page would be sourced with the records returned by the report definition rule.
Insight — When you create a new Data Type, the system auto-generates the respective DataTableEditorReport report definition.
Optionally, you can choose a different data source for your data page that helps solve your business problem or requirement. You can choose from the following available options as the data source for a list-structured data page. I’m going to publish an article on how to source the data page through a Connector, Data Transform and Activity in future.
For the time being, let’s continue with the standard report definition as the data source for the data page. I’m also going to explain the report definition more at length in future. For now, all that you need to know about it, is that, it is one of the ways in PEGA to query a database table, and retrieve the records from it, similar to the Obj-Browse activity method. I’ve already published a post on the Obj-Browse activity method. If interested to learn more about it, you can check it out.
In this case, the standard report definition would retrieve the records from the Beneficiary data type (essentially a database table) because it is applied to the associated data class: MyOrg-MyDiv-Data-Beneficiary.
Let’s open the report definition, and run it through Actions -> Run (as shown below) to review its result set.
Note — Click the crosshair icon adjacent to the report definition name in the data page ruleform in order to open it.
As expected, the report definition returns the records added to the Beneficiary data type.
- Run the data page for validation
Now, let’s go back to the data page ruleform, and manually run it to review its contents. Click on [Actions] -> Run as shown below.
This is required only to validate whether the data page configuration is producing expected results or not. It is not mandatory to run a data page manually. The system would automatically run it at run-time when it comes across a reference to the data page.
A window would pop-up as given below. Select the “Flush all instances of this data page before execution” checkbox, and click [Run] in the window.
The contents of the data page would appear in the same window.
Important — The standard pxResultCount property indicates the number of records loaded onto the data page. In this case, it is three records.
Important — Another standard pxResults pagelist on the data page holds the records. In this case, it consists of three pages/elements as shown below. Each element/page in the pagelist represents a record.
Expand the individual node under the pagelist to examine the respective record.
Hence, it can be said that the data page is loaded with the three beneficiary records by the report definition.
- Define Data Page Refresh Strategy
Let’s say that I want the data page to reload its contents from the Beneficiary data type every time I create a new Transfer Funds case in order to populate the latest beneficiary records in the dropdown list (in the Select Beneficiary user screen). To meet this requirement, I’m going to define a refresh strategy to reload the data page once per interaction by selecting the corresponding checkbox as shown below.
Ideally, the refresh strategy should be defined after consultations with business, and having understood how often the data would update in the data type or any other data source in order to keep the data page up to date and in sync with the data source.
Step # 5: Configure the dropdown to use the Data Page
Finally, let’s use this data page as the data source for the dropdown list (in the Select Beneficiary user screen) in order to populate it with the beneficiary names.
Go to the section rule, and view the properties of the dropdown.
In the List source section, change the Type to Data page.
Select the name of the data page.
Since, I want to populate the full name of the beneficiaries in the dropdown, I’ve selected .FullName in the “Property for display text” field.
And, I want to store the beneficiary ID (a code word e.g. B-001 for John Doe) of the selected beneficiary on the case instance (aka work object). For this reason, I’ve selected .ID in the “Property for value” field. Each beneficiary has a unique ID. As a result, it can be used to identify beneficiary.
The ID value would be stored in the property (of the Work class) referred in the dropdown control which is .SelectedBeneficiary in my case as shown below.
Submit the above modal dialog, and save the section rule.
This concludes the configuration. Let’s validate the changes.
Step # 6: Change Verification
Go to the Transfer Funds case type.
Save and run it in order to create a new case instance. On the first screen, the dropdown list would populate with the names of the beneficiaries added in the data type as shown below.
Select a beneficiary in the dropdown, e.g. Jane Doe, and continue.
Launch the clipboard, and verify that the ID of the selected beneficiary is stored on pyWorkPage (case instance). B-002 is the ID of the selected beneficiary — Jane Doe.
Well done! you’ve populated the dropdown with the data type records through a data page.
In the upcoming articles, I’m going to cover Page-structured, Editable, Savable, Node-level and Requestor-level data pages. So, stay connected!
To learn more about Pega, be sure to Follow on YouTube, Instagram, and Facebook
YouTube:
Facebook:
Instagram:
