On-demand data access
Case processing often requires access to data sourced from other applications or systems. Ensuring the accuracy of sourced data reduces the chance for errors — and undesirable outcomes — for cases significantly. In Pega Platform™ applications, a data page retrieves data from a specified data source and caches that data in memory. A data page manages the integration to the data source, separating business processes from any integration details. This separation allows application developers to use sourced data in an application without knowing the data source and connection details.
Unlike most pages that are used in Pega Platform, applications attempt to populate the contents of a data page only when the page is accessed, rather than through an explicit action. Due to the on-demand nature of data page content, data pages are considered a type of declarative rule. Pega Platform automatically prepends the characters D_ to the name of a data page to differentiate the page from other pages in memory.
Note: Data pages created in versions of Pega Platform before 7.1 begin with Declare_ instead of D_.
In the following image, click the + icons to explore how Pega Platform populates the contents of a data page.
Check your knowledge with the following interaction.
Data page definition
In Dev Studio, you can create data pages. When creating a data page, a developer must provide four key pieces of information:
- The structure of the page contents.
- The object type represented by the contents of the data page.
- The edit mode supported by the page.
- The scope of the data page.
The structure of the page determines whether the data page can contain one item or many items. Set the structure of a data page by selecting an option from the Structure drop-down list.
When using a list structure, the data page embeds the list items in an ordered array named pxResults. To access a specific record within the list, use the syntax DataPageName.pxResults(n), where n is the index of the ordered array that corresponds to the record.
Consider a data page that contains pricing information for a single stock. The structure is set to Page. However, if a data page contains pricing information for all the stocks in an investment portfolio, you set the structure to List.
In the center of the following image, slide the vertical line to compare the page and list structures.
The object type of the page identifies the information contained by the data page. To set the object type for a data page, enter the class of the object in the Object type field. The object type allows the data page to reference any property defined for the class. For example, a data page that lists dental insurance plans provided by an insurer contains the plan name, cost, and deductible. A data page that lists recent orders placed by a customer contains the order number, order date, total cost, and shipping address.
The edit mode of a data page indicates how — or if — an application can manipulate the information on a data page. Set the data page mode by selecting an option from the Mode drop-down list.
Set the edit mode to Read-Only to prevent an application from updating the data page except when loading and updating the contents from the data source. Read-only mode prevents users from editing information sourced from a system of record and ensures that the data page content always matches the content loaded from the system of record. For example, when accessing the accident history of an auto insurance customer from the Department of Motor Vehicles (DMV) database, state or national laws may prohibit editing the sourced data. To comply with this legal requirement, set the page mode to Read-Only.
Note: If a data page mode is Read-Only, the Clipboard tool lists the data page in the Data Pages category.
Set the edit mode to Editable to allow an application to edit the data page contents. For example, a retailer allows customers to save one or more preferred shipping addresses when placing an order. The list of addresses is loaded from the customer database using a data page. To allow a customer to update an address during an order, you set the page mode to Editable.
Note: If the data page mode is Editable, the Clipboard tool lists the data page in the User Pages category.
Set the edit mode to Savable to configure a save plan that allows the application to push the page contents back to the data source. For example, after a customer updates a shipping address, the application copies the updated address to a savable data page configured to update the customer database. When the customer completes the order, the application follows the save plan to connect to the customer database.
The scope of a data page determines the visibility of the page contents within the application. To set the page scope, select one of the supported options in the Scope drop-down: Thread, Requestor, or Node.
In the following image, click the + icons to learn more about the scope options and examine how you can leverage scope settings to manage cached data within Pega Platform applications.
Check your knowledge with the following interaction.
Use the Data sources section of the data page form to specify how Pega Platform populates the contents of a data page when an application references the page. To configure a data source, specify the type of the source and the name of the data source. You can use any of the following options to configure a data source for a data page.
- Data transform
- Report definition
- Database lookup
- Robotic automation
- Robotic desktop automation
For each source type, you identify the data source to query. The following example shows a data source configured to populate a data page with a list structure by running the DataTableEditorReport for the class GoGo-GoGoRoad-Data-Customer.
You must configure a data transform to map the response to the data model for the case type or data type when:
- Using a report definition to source a page structure
- Using a lookup to source a list structure
- Using a robotic automation
- Using a robotic desktop automation
Data sourcing from multiple data sources
If you must combine data from multiple sources to populate a data page, select the Aggregate sources option. Then, identify each of the data sources to query. Pega Platform populates the data page from the specified sources in the listed order.
Conditional data sourcing from a data source
A data page must specify at least one data source. If a data page contains more than one source, configure a logical condition for each source to test whether to query the data source. The condition for the last listed data source is set to Otherwise to ensure that Pega Platform always identifies the data source for the data page. When an application references the data page, Pega Platform evaluates each condition in the data source order and uses the data source for the first condition that returns a result of true.
When populating a data page, you may need to limit the contents of the page to relevant items. For example, a database contains records of all the policies underwritten by an insurance company. If a customer wants to adjust the coverage on their auto insurance policy, you need a way to populate a data page with only the relevant policy record.
You can use parameters to limit the contents of a data page. For example, if you select Lookup as the data source, you must provide the key value to uniquely identify the record to return to the data page. You can also use parameters to pass data to a report filter to limit results to a specific set of records, such as a specific product type in an inventory database. You can pass a parameter to a data page from user interface elements such as a drop-down or radio button, properties, and certain other rule types. For a full list of the rule types that can pass parameters to a data page, see the help topic Passing Parameters to data pages from non-UI rules.
Caution: Using parameterized data pages can lead to multiple instances of a data page on the clipboard. Consider the impact of these multiple data page instances when adding a parameter to a data page. If you do not need an instance for each unique combination of parameters, select the Limit to a single data page check box on the Load Management tab to maintain a single instance of the parameterized page that Pega Platform overwrites when the parameters change.
To use a parameterized data source, add an entry for the parameter on the Parameters tab of the data page record.
To reference a parameterized data page, include the name and value of each parameter in the reference. Use brackets to identify the name and value of each parameter, using the syntax DataPageName[Parameter1_Name:Parameter1_Value,Parameter2_Name:Parameter2_Value,...].
Note: When users attempt to access a parameterized data page, Pega Platform ignores any instance of the data page with a different value for the same parameter.
In the following data page image, click the + icons to learn more about parameter configurations.
Referencing data pages
When data needs to be referenced from a data page, a Query field type is used. While most data objects created by Integration Designer will not have a key or the other needed data pages to create a reference relationship. Query fields require either a list or lookup data page.
A Query field does not store any key values within itself, so any parameters to the data page are external to the field. Consider a case type that manages flight instruction and creates flight plans for students. The case type uses a Query to obtain the weather for an airport by passing an airport code sourced outside of the case, which then returns the weather details and automatically populates them on the flight plan confirmation view.
Note: A Query does not require the parameter to be a field sourced outside of the case. It can have the parameter come from any field in the context of a containing object or a field from an activity.
Parameters for a Query field are defined by the data page or view that the field is configured to use. For example, a data page might use a date range as parameters to determine which transactions should be returned. You can configure a Query to copy the information from the data page into the case on first access. Additionally, you can use a savable data page to push the information back to the system of record, such as when updating a value.
Check your knowledge with the following interaction.