For data held in read-only, list-structure data pages, you can allow access to embedded pages in the data page by enabling keyed access and using properties to provide values for the key(s). This permits significantly faster response when the system needs to retrieve a single item or subset of items from a large list.

• Overview
• Enabling keyed access
• Load data into a page property from a list-structure data page
• Load data into a page list property from a list-structure data page
• Load data into a page list property from different instances of a list-structure data page

Overview

In general, when the system references a data page:

• The system provides parameters that the data page can use to get precisely 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 loads or reloads its data from the correct data source, using a request data transform if necessary to structure the request so the data source can respond to it.
• The data source uses the information that the data page sends to locate and provide the data that the application requires.
• A response data transform maps and normalizes 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 to the auto-populated property or direct reference.

To provide instant access to a particular page in a list-structure data page (such as a list of products, with each embedded page holding information about a particular product), enable keyed access:

• You establish one or more keys on the data page.
• When the system references the data page, it sends property references (or literal values) to provide values for the page's key or keys.
• The data page uses the values provided for the keys to determine from which embedded page or pages to provide the data that the system wants.

Return to top

Enabling keyed access

1. In the Data Explorer, locate the data page that both retrieves the data for all suppliers from a data source and that loads it into an instance of itself on the clipboard:
2. Click the data page name to open it:
3. At the right of the Definition tab for list-structure data pages is the "Keyed Page Access" section. Check the Access pages with user defined keys checkbox; then, in the "Page List Keys" area, define one or more keys for this data page:
   
4. You can select from the properties in the class of the data page, or click the magnifying glass icon to create a new one.
   • If you want to use multiple keys (.SupplierID and .Industry, perhaps), click the + icon to add additional key fields.
5. Either all or no keys must be passed to the data page at run-time. This allows one data page to serve a dual purpose:
   • It can display all the items it contains (no keys passed).
   • It can return only items that match the keys.
6. The "Allow multiple pages per key" option lets the data page return multiple embedded pages from a single instance to an auto-populated page list property. You might use this option when preparing to display a list of all the products offered by a particular provider.

Reference the data page from a property using a key

The property that requires the data about the specific supplier gets it by referencing the data page and sending a property reference or a literal value to populate the data page key.

In this example, a page property holds the information about the selected supplier:

Select "Refer to a data page" or "Copy data from a data page", then select the data page by name. In the KEYS section, provide a property reference or a literal value for each data page key.

When the property is referenced, the system automatically loads the data page using the value that the property sends as the key.

You can use parameters and keys together.

• The parameters determine the instance of a data page that is loaded and selected.
• The keys determine which embedded page(s) within a given instance to return.

Return to top

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

You have a service that returns information for all customers who have been identified as most likely to call back on a given day, due to open issues they are experiencing.

The system holds the information about these customers in a node-level data page that it updates each day, giving all customer service representatives (CSRs) access to the latest information. The list has data on thousands of customers, and each CSR needs to get the right information quickly to deal with customer interactions.

The solution is to automatically load the correct customer's information from the list structure data page on the clipboard, based on the values of keys passed in.

This scenario requires:

Properties:

• .Customer (a page property of class Data-Customer)
  • On the General tab, select "Copy data from a data page" (to allow using a data transform) or "Refer to a data page" (without a data transform), and specify D_CustomerList as the data page.
  • Set CustomerID = .Customer.CustomerID as the key to the data page. The keyed page list feature allows indexing into a single instance of a list-structure data page.
  • Set LevelOfDetail = .LevelOfDetail as the parameter to send to the data page. When this changes, the data page generates a new instance of itself on the clipboard.
  • You can optionally 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 customers. The data page requires this value to get the correct amount of customer detail.

Data page:

The data page D_Customer has these settings:

• Structure = List
• Class = Data-Customer
• Scope = Node
• Edit Mode = Read Only
• Parameter = LevelOfDetail
• Select the "Access pages with user defined keys" option and specify .CustomerID as the value for the data page key

The data source configuration involves:

• A connector data source of class Int-GetTargetCustomerInfo.
• A request data transform of class Int-GetTargetCustomerInfo 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

What happens

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. This triggers auto-populating 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 data page uses the key passed in to locate the correct page in the list.
6. The CopyCustomerSubset data transform, specified on the property, copies the required data from the correct page in the list to the .Customer property.

• If no data transform is specified, all data from the data page instance is copied into the property.
• If the "Refer to a page property" option is selected, no data is copied into the property. Instead, the system establishes a reference between the property and the correct embedded page in the data page.

Return to top

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

In this scenario, you are creating an order management application that lets users browse products within categories by showcase types: "most ordered", "most viewed", and "most wished-for".

A service returns products of a given showcase type, but does not group them by category. The requirement is to let the user select both the showcase type and the product category.

This scenario requires

Properties

• .Products (a page-list property of class Data-Products)
  • On the General tab, select "Refer to a data page" (a data transform is not required) and specify D_Customer as the data page.
    • Set the CategoryID = .SelectedProductCategoryID as the key to the data page (the keyed page list feature, noted above, allows indexing into a single instance of a list-structure data page).
    • Set the parameter ShowcaseType = .SelectedProductShowcaseType. When this parameter changes, the data page makes a fresh call to the data source and loads to the clipboard a new instance of itself with the relevant data.
• .SelectedProductCategoryID (sibling to .Products)
• .SelectedProductShowcaseType (sibling to .Products)

Data page

The data page D_ProductList has these settings:

• Structure = List
• Class = Data-Product
• Scope = Node
• Edit Mode = Read Only
• Parameters = ShowcaseType
• Select the "Access pages with user defined keys" option and specify .CategoryID as the page list key. Select "Allow multiple pages per key".

The data source configuration involves:

• A connector data source of class Int-GetShowcaseProductList.
• A request data transform of class Int-GetShowcaseProductList to form the request so the service can use it.
• A response data transform of class Data-Product to map the data from the integration to the the data class properties

What happens

1. The user or the system sets the values for .SelectedProductShowcaseType and .SelectedProductCategoryID.
2. The user or the system references an embedded property on .Products. This triggers auto-populating the product data.
3. The system passes parameters to the data page.
   • If there exists on the clipboard an instance of the data page that corresponds to the parameter values passed in, and if the data page's refresh strategy permits it, the data page returns data from the existing instance (jump to step 6).
   • Otherwise, it requests data from the data source so it can load a new instance of itself.
4. If there is a request to the data source, the data source uses the parameters passed to get and provide the relevant data.
5. If the data source has provided data, the response data transform maps the data into the data page.
6. The key identified on the data page is used to index into the correct pages in the list of data. Because "Allow multiple pages per key" is selected, the data page returns all pages that match .ProductCategoryID.
7. The system creates a reference between the .Products page list property and the products identified in step 6 in D_ProductList.pxResults().
   • The requested list of products displays for the user.
   • The system does not copy anything to the case, since in this scenario you do not want to store the list of products with the case.

Return to top

Load data into a page list property from different instances of a list-structure data page

You are building an order management application that lets users order products from different suppliers. The system has a data service for each supplier, from which the application can request data about that supplier's products.

When a user adds a product to the shopping cart, the system needs to retrieve more detailed product information than is displayed to the user from the correct database, and to store that information with the order.

This scenario differs from the previous one in having a separate service for each supplier that returns a list of all products for that supplier. The system uses parameters to load lists of products specific to a supplier, and keyed data access to get specific product information from the correct supplier's product list.

This scenario requires

Properties

The properties are in this hierarchy:

• .ShoppingCart (page property)
  • .Products (auto-populated page list property of class Data-Product)
    • .SupplierID (single value property)
    • .ProductID (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_ProductsList as the data page.
• Set as parameters:
  • DetailLevel = .LevelOfDetail
  • SupplierID = .Products.SupplierID
• Set .ProductID = .Products.ProductID as the key to the data page.
• Select the "Retrieve each page separately" option. The data page either creates new instances of itself for each unique .Products(n) based on .Products(n).ID, or copies different embedded pages from the same data page instance.

Data page

The data page D_ProductList has these settings:

• Structure = List
• Class = Data-Product
• Scope = Node
• Edit Mode = Read Only
• Parameters = DetailLevel and ProductID
• Select "Access pages with user defined keys" and select .ProductID as the page list key

The data source configuration requires a connector data source for each supplier.

What happens

1. When a user adds a product to their shopping cart, the system sets .LevelOfDetail to return full product data for that item.
2. The user or the system references an embedded property on .Products that triggers autopopulation of the product list.
3. The system passes parameters for each supplier 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 an instance of itself for each supplier based on the value of the supplier parameter passed in.
     • Each page contains the appropriate level of detail about that provider's products.
     • The data page uses the SupplierID parameter value with the When conditions associated with each data source to locate the data source that matches the supplier in question.
4. If a data source executes and returns data, the response data transform maps the data into the instance of the data page.
5. For each page in the .Products page list property, the system uses the .LevelOfDetail and .SupplierID parameters to locate or load the correct data page instance in memory, then uses .ProductID to key into that instance and return the embedded page containing the correct product information.
6. As the user adds products to their cart, the simple act of the section rendering the shopping cart causes steps 1 through 5 to repeat for each product added.

Return to top