Load data into a page list property
In Pega 7, data pages can provide automatic data access, populating page and page list properties with data relevant to the circumstances. A case, another data page, or some other object can use a property to automatically access the data it needs from a data page.
- Load data into a page list property from different instances of a page-structure data page
- Data transforms
The diagram below shows, at a high level, what happens when the system references a data page:
- The object references a data page, providing parameters that the data page can use to get the data that the object needs from the data source.
- 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 makes a call to a data source, using a request data transform to structure the request so the data source can respond to it, if necessary.
- The data source uses the information the data page sends to locate and provide the data the application requires.
- If necessary, a response data transform maps the data to the properties that require it.
- The data page creates an instance of itself on the clipboard to hold the mapped data, and provides it 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:
Here you specify how the property gets its data:
- Manual - the user or system procedurally provides the data.
- Refer - the system references a data page.
- Copy - 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 already exists on the clipboard.
- If it does, and if the data page's refresh strategy allows it, the data page uses the existing instance to respond to the reference.
- Otherwise, it 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.
Each reference may require parameter values. In the example above, the parameter ProductType is optional; a required parameter would have an * beside its name. Auto-populated properties do not try to load a data page unless all required parameters have values.
To learn about automatic data access for page properties, see Load data into a page property.
In this scenario, you are building an order management application that allows users to order products. A service can retrieve highly-detailed product information that is required for order processing once the customer checks out.
Initially the customer browses a product catalog that contains only the information necessary for them to learn about the product. The product list that the customer is browsing lives outside of the case. But as a customer adds products of interest to their shopping cart, the items are moved into the case, and the system retrieves more detailed product information necessary for completing the order. Ordered products must live with the case so it can maintain an exact record of the product as it was ordered.
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 for completing the order.
This scenario requires
The property hierarchy is:
- .ShoppingCart (page property)
- .LevelOfDetail (single value property)
- .Products (auto-populated page list property)
- .ID (single value property)
The configuration of .Products is as follows:
- Select the "Copy data from a data page" option (a data transform is required) and specify D_Products as the data page.
- Set as parameters:
- DetailLevel = .LevelOfDetail
- ID = .ProductsID
- Select the "Retrieve each page separately" option. The data page creates a new instance of itself for each unique .Products(n) based on .Products(n).ID.
The data page D_Product has these settings:
- Structure = Page
- Class = Data-Product
- Scope = Requestor
- Edit Mode = Read Only
- Parameters = DetailLevel and ID
The data source configuration involves:
- Two connector data sources, one of class Int-GetFullProductDetail, and the other of class Int-GetMinProductDetail.
- Each data source has a When condition that checks the value of param.DetailLevel.
- This allows the data page 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 to form the request so the service can use it.
- The data page passes the values of the parameters DetailLevel and ID to the request data transform, which passes the values to the service so they can be used.
- One response data transform per data source, of class Data-Product, to map from the integration to the data class properties.
- If the user is shopping, the system sets .LevelOfDetail to return minimal product information. If the user is ready to check out, the system sets .LevelOfDetail to return full product data.
- The user or the system references an embedded property on .Products that triggers autopopulation of the product list.
- The system passes parameters to the data page.
- If there exist on the clipboard instances of the data page that correspond to the parameter values passed in, and if the data page's refresh strategy permits it, 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 .ProductDetailLevel 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 to take source data values — data that is in one format — and transform them into data of another format (the "destination" or "target"). Using a data transform speeds development and is easier to maintain than setting property values with an activity, 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.
There are three main data transforms involved in data management using data pages:
- Optional data transform on the property form.
- Request data transform that lets you map PRPC data to the fields a connector requires to communicate with the data service.
- Response data transforms normalize data provided by the data sources into the common application data model. For more on this topic, see Data virtualization in PRPC.
For more about working with data transforms, see Introduction to data transforms.