Data page reference

Rules can reference data pages directly or by using auto-population properties to obtain quick access to data.

For example, a section that displays customer information can reference the D_Customer data page instead of getting the information directly from the database.

Data page reference methods

You can reference data pages with or without parameters, or by using keys.

If a data page does not have parameters defined, you should reference the data page by using the data page name, for example, D_Customer. When you reference a data page, the data page verifies whether an instance of itself, created by an earlier call, exists on the clipboard. If the instance exists, the system returns the data on the existing clipboard page. If the instance does not exist, the data page loads or reloads its data from the appropriate data source and then returns the data.

If a data page has parameters defined, you can reference the data page by passing parameter values to get accurate data more quickly. For example, if the D_Customer data page has a CustomerID parameter, you can reference the data page as D_Customer[CustomerID:"PEGA101"] to obtain data more quickly for the customer with ID PEGA101. When you reference a data page by passing parameter values, the data page verifies whether an instance of itself, created by an earlier call by using the same parameters, exists on the clipboard. If the instance exists, the data page responds to the request with the data on the existing clipboard page. If the instance does not exist, the data page loads or reloads its data from the appropriate data source. The data source then uses the information that the data page sends to locate and provide the data that the application requires. The data page creates an instance of itself on the clipboard to hold the mapped data, and provides it to the application.

If a data page has keys defined, you can use the keys for instant read-only access to a particular page in a data page that has a list structure, for example, a list of suppliers, with each embedded page holding information about a particular supplier. You can specify one or more keys on a data page and allow the system to reference the data page by using the keys. When the system references the data page, it sends property references or literal values to provide values for the keys. The data page uses the values provided for the keys to determine the embedded page or pages from which it can provide the data that the system wants.

You can use parameters and keys together. The parameters determine the instance of a data page that is loaded and selected, and the keys determine which embedded pages within a given instance to return.

Direct data page reference

Referencing data pages directly from rules allows the system to retrieve accurate data from the appropriate data source on demand. You can reference data pages with parameters when you do not have to maintain hierarchical relationships or case context.

For example, if the D_Customer data page is a part of the D_Organization data page, the relationship between the data pages is hierarchical. Additionally, if the D_Address data page is a part of the D_Customer data page, the data pages are multiple hierarchically-related. You cannot use parameters to reference these data pages; however, you can reference them by using auto-populated properties, which are described in the next section.

The syntax to reference a data page is <Data page name>[<Comma delimited list of parameter name:value pairs>].

You can reference a data page by using one of several valid forms of this syntax. For example, you can reference the D_Customer data page by using the following formats:

  • D_Customer[CustomerID:"ANTON"]
  • CompanyName:"BigCo"] D_Customer[CustomerID:.CustID]
  • D_Customer[CustomerID:param.CustID]

When the data page only has one parameter, you can exclude the parameter name, as shown in the following examples:

  • D_Customer["ANTON"]
  • D_Customer[.CustID]
  • D_Customer[param.CustID]

For more information about referencing data pages by using parameters, see Use parameters when referencing a data page to get the right data on Pega Community.

Data page reference by using auto-populated properties

Auto-populated properties are page or page list properties that automatically obtain data directly from specified data pages. As a best practice, use these properties to access and source data from multiple hierarchically-related data pages more easily.

An auto-populated property can refer to a data page or copy data from a data page on the General tab in the Data access section of the property form:

  • When the property refers to a data page, the system loads a new data page when data page parameters change and a reference to a non-parameter value is made. The system reads from and writes to the property on the new data page.
  • When the property copies data from a data page, the system loads a new data page and copies it into the property when parameters to the data page change and a non-parameter value is referenced. Interactions with the property happen on the copied data. Use this option only if you need to copy data into your case.

You can reference data pages from auto-populated properties by passing parameter values. The system processes the reference to a data page as described in the Direct data page reference section.

For example, you can configure a page property to load supplier data on the General tab of the property. Refer to the D_Supplier data page and enter “Boston” for the SupplierArea parameter. At run time, the system populates the property with data for the suppliers in the Boston area.

You can use keys to allow instant read-only access to a particular page in a data page that has a list structure, for example, a list of suppliers, with each embedded page holding information about a particular supplier. You can specify one or more keys on a data page and allow the system to reference the data page by using the keys. When the system references the data page, it sends property references or literal values to provide values for the keys. The data page uses the values provided for the keys to determine the embedded page or pages from which it can provide the data that the system wants.

For example, you can load the information for a specific supplier from the D_Supplier data page, which has a key .SupplierID. Specify the D_Supplier data page and value “XYZ123” for the .SupplierID key on the General tab of the page property. When the property is referenced, the system automatically loads the D_Supplier data page by using the value “XYZ123” for the .SupplierID key, or, the information for the supplier whose ID is “XYZ123”.

For more information about referencing data pages by using keys, see Instantly access embedded pages in a list-structure data page using keyed page access on Pega Community.