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 steps are involved:

1. Properties can automatically reference a data page, that the data page can use to get the data that the case needs from the data source. For more information, see Use case: Referencing data in a data page by using parameters.
2. 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 by using a request data transform.
3. The data source uses the information that the data page sends to locate and provide the data that the application requires.
4. If necessary, a response data transform maps data to the properties that require data. For more information, see response data transform.
5. 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 or copy data from a page-structure data page by using the 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, while they are optional for others. In the example above, the parameter CustomerID is required. Required parameters are designated by placing an asterisk beside the parameter name (for example, CustomerID*). Autopopulated properties require that all parameters have values for the page to be loaded.

To learn about automatic data access for page list properties, see Using the Load-DataPage method.

Load data into a page property from a page-structure data page

In this scenario, you are building an order management application that allows you to store records of customers' orders, which creates a permanent record of customer information at the time each order was placed.

The data source that you are using requires the customer's ID and a "level of detail" (full or minimal) value to retrieve the data.

Configuring property parameters

The property hierarchy is arranged in the following order:

• .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 the following parameters:
    • CustomerID = .Customer.CustomerID (this could also be a sibling property to .Customer or a constant value)
    • LevelOfDetail = .LevelOfDetail
    When either parameter changes or a non-parameter value is referenced, the data page creates a fresh instance of itself on the clipboard.
  • Specify the CopyCustomerSubset data transform to run 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 holds the customer ID at run time.
• .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.

Configuring data sources

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.
• The data page passes the values of the parameters CustomerID and LevelOfDetail to equivalent parameters on 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.

Result

1. The user or the system sets the values for .LevelOfDetail and .Customer.CustomerID.
2. The user or the system references an embedded property on .Customer, which autopopulates the customer data.
3. 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.
4. If the data source executes, it passes data to the response data transform, which maps data into the instance of the data page.
5. 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.

Data transforms

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, see Data pages overview.

For more information about working with data transforms, see Data transforms.