Load data into a page 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.
The diagram below shows, at a high level, what happens when the system references a data page:
- Properties can automatically reference 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 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 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.
The object can reference or copy data from a page-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 CustomerID has an * beside its name to indicate that it is required. 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 list properties, see Load data into a page list property.
In this example, you are building an order management application.
- You have a Customer property in your Order case that you want to retrieve from an external service.
- You want the Customer data to be stored with each order so you have a permanent record of customer information at the time the order was placed.
- The data source you are using requires the customer's ID and a "level of detail" (full or minimal) value to retrieve the data.
This scenario requires:
- .Customer (a page property of class Data-Customer)
- On the General tab, select "Copy data from a data page" or "Refer to a data page" (to establish a reference to the data page without copying any data into your case), and specify D_Customer as the data page.
- Set as the parameters:
- CustomerID = .Customer.CustomerID (this could also be a sibling property to .Customer, or a constant value)
- LevelOfDetail = .LevelOfDetail
- Specify the CopyCustomerSubset data transform to execute after the data page returns data to copy a subset of the data from the data page to the property.
- .Customer.CustomerID: a single value integer property defined at the page class of .Customer that at run time holds the customer ID.
- .LevelOfDetail: a single value integer property defined at the page class of .Customer that contains the LevelOfDetail setting for this customer. The data page passes this value to the integrator to get the correct amount of customer detail.
The data page D_Customer has these settings:
- Structure = Page
- Class = Data-Customer
- Scope = Thread
- Edit Mode = Read Only
- Parameters = CustomerID and LevelOfDetail
The data source configuration involves:
- A connector data source of class Int-GetCustomerInfo.
- A request data transform of class Int-GetCustomerInfo to form the request for the service. The data page passes the values of the parameters CustomerID and LevelOfDetail to the request data transform, which in turn passes them to the correct properties for the connector.
- A response data transform of class Data-Customer (the class of the data page) to map from the integration to the data class properties
- The user or the system sets the values for .LevelOfDetail and .Customer.CustomerID.
- The user or the system references an embedded property on .Customer. This triggers auto-populating the customer data.
- The system references the data page, passing the parameter values.
- If an instance of the data page that corresponds to the parameter values exists on the clipboard, and the data page's refresh strategy permits, the data page responds to the reference with the existing instance.
- Otherwise, it passes the parameters to the appropriate data source.
- If the data source executes, it passes data to the response data transform, which maps data into the instance of the data page.
- The CopyCustomerSubset data transform specified on the .Customer property copies data from the data page instance into the property. If no data transform is specified, all data from the data page instance is copied into the property.
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.