Use case: Loading data into a page list property
In Pega Platform, data pages provide automatic data access, populating page and page list properties with relevant data. Cases, other data pages, and data objects can use a property to automatically access the data needed from a data page.
The following diagram outlines the stages and steps involved with loading data into a data page or page list.
When a system references a data page, the following process occurs:
- Properties automatically reference a data page by using parameters to obtain the data that the data object needs from the data source. For more information, see Use case: Referencing data in a data page by using parameters.
- The data page verifies whether an instance of itself, created by an earlier call
using the same parameters, exists on the clipboard.
- If the data page's refresh strategy permits, the data page responds to the request with the data on the existing clipboard page.
- Otherwise, the data page calls a data source, using a request data transform.
- The data source uses the information that the data page sends to locate and provide the data that the application requires.
- If necessary, a response data transform maps data to the properties that require data. For more information, see Configuring a data transform for a JSON output mapping.
- The data page creates an instance of itself on the clipboard to hold the mapped data and provides the data as a response to the request.
Properties can automatically reference a list-structure data page using the new Data access section on the General tab on the property form.
In the Data access section, you specify how the property accesses the data. The choices include:
- Manual- The user or system procedurally provides the data.
- Refer to a data page- The system references a data page.
- Copy data from a data page- The system copies data from a data page instance into the property.
When the system references a data page, the data page checks whether an instance of itself that satisfies the reference exists on the clipboard.
- If a recently refreshed instance of the data page is on the clipboard, the data page responds to the reference.
- Otherwise, the data page creates a fresh instance of itself on the clipboard, populates it with data relevant to the reference, and uses it to respond to the reference.
Values are required for some parameters and are optional for others. Required parameters are designated by an asterisk beside the parameter name (for example, CustomerID*). Autopopulated properties require that all required parameters have values for the page to be loaded.
To learn about automatic data access for page properties, see Using the Load-DataPage method.
Load data into a page list property from different instances of a page-structure data page
In this scenario, you are building an order management application that allows users to order products. A service retrieves highly detailed product information required for order processing once the customer checks out.
The customer starts by browsing a product catalog that contains only descriptions of the products. The product list that the customer is browsing lives outside of the case. As the customer adds items to their shopping cart, the items are moved into the case, and the system retrieves the more detailed product information that is necessary to complete the order. The ordered products must live with the case, so that the case can maintain an exact record of the ordered products.
There are two services available to this application, both of which return information for a single product.
- The first retrieves the brief customer-facing product information.
- The second retrieves the more detailed product information that is necessary to complete the order.
The following figure illustrates the process of how the products selected by the customer are moved from the external product catalog into the case.
Configuring property parameters
The following illustrates a scenario that requires properties.
The property hierarchy is arranged in the following order:
- .ShoppingCart(page property)
- .LevelOfDetail (single-value property)
- .Products (auto-populated page list property)
- ID(single-value property)
Configuring the products property
Perform the following procedure to configure the .Products property:
- Select the Copy data from a data page option.
- Set Load each page in this page list individually to true and specify D_Product as the data page.
- Set the following parameters:
- .DetailLevel = .LevelOfDetail
- ID = .Products.ID
Configuring data sources
The settings for the D_Product data page are as follows:
- Structure = Page
- Class = Data-Product
- Scope = Requestor
- Edit Mode = Read Only
- Parameters = DetailLevel and ID
Configuration of a data source requires the following resources:
- Two connector data sources, one of class
Int-GetFullProductDetail, and the other of class
Each data source has a When condition that checks the value of param.DetailLevel. This allows the data page to create instances of itself that hold full or minimal product detail, depending on the value of param.DetailLevel received with each reference.
- One request data transform per data source.
- The data page passes the values of the parameters DetailLevel and ID to the request data transform, which passes the values to the service.
- One response data transform per data source, of class Data-Product, to map from the integration to the data class properties.
- While the user is shopping, the system sets .LevelOfDetail to return minimal product information. When the user is ready to check out, the system sets .LevelOfDetail to return full product data.
- Either the user or the system references an embedded property on .Products , which autopopulates of the product list.
- The system passes parameters to the data page.
- If there are instances of the data on the clipboard, which correspond to the parameter values passed in, and the data page's refresh strategy permits, the data page returns data from the existing instances.
- Otherwise, the data page creates separate instances of itself for each page in .Products. Each data page instance uses the same .LevelOfDetail value.
- Since the data page has two data sources, the When condition associated with the first source in the list checks whether it should be used, based on param.DetailLevel. If it is not to be used, the system uses the second data source.
- If the data source executes and returns data, the response data transform maps the data into the data page.
- For each .Products(n), the system passes the .ID of the product. The data page creates a new instance of itself for each product and copies the data from the correct instance to the corresponding page in the page list.
A data transform defines how source data values are transformed into the target format. Using a data transform accelerates the development process and is easier to maintain than setting property values with an activity. This is because the data transform form and actions are easier to understand than the activity form and methods, especially when the activity includes custom Java code.
The following data transforms are involved in data management when using data pages:
- Optional data transform on the property form.
- Request data transform allows you to map Pega Platform data to the fields required by a connector to communicate with the data service.
- Response data transforms normalize data provided by the data sources into the common application data model. For more information on this topic, see Data pages overview.
For more about working with data transforms, see Data transforms.