Summary

V6.2 introduces powerful data mapping and transformation using the data transform rule. With a data transform, you can easily copy, map, and transform clipboard data values from one clipboard page to another.

As shown in this example, you can cause a flow action to have the system apply a data transform at runtime before the user submits the flow action, after the user submits the flow action, or at both times.

The data transforms in this example demonstrate use of these actions: Set, Remove, When, Otherwise, For Each Page in, and Exit For Each.

Suggested Approach

The scenario for this example is an order management application. At a certain point in the ordering process, users add products and quantities of those products to a shopping cart using an Add to Cartbutton.

The application designer has designed the following user experience for the application's users:

1. When a user selects to add a particular product to the shopping cart, the system must check to see if the cart already contains that product item.
2. If the item is found in the shopping cart, the system shall notify the user and present the user with fields to update the quantities of that item in the cart.
3. If the item is not found in the shopping cart, the system shall add the product and ask the user for the quantity to add.

The flow action associated with the Add to Cart button is named AddProductToCart. If the selected item is not already in the cart, the following dialog is presented to the user:

If the selected item is already in the cart, this screen is presented to the user, with the current quantity displayed in the Quantityfield:

The product data is stored in an external database, in a table named Products. The OrderManagement-Int-Products class is mapped to that table. The following illustration shows the OrderManagement-Int-Products class in the Application Explorer, with the Property, Data Transform, and Flow Action categories expanded to show the rules that are involved in this example.

The Action tab for the AddProductToCart flow action form looks like this:

To have the system check whether the item is already in the user's shopping cart, the designer has specified CheckForProductInCart data transform in the Before This Action area of the flow action form's Action tab:

The designer has a Page List property named Items on the work item page (pyWorkPage) that is the set of all product items in the user's shopping cart. Each page in Items corresponds to a specific product in the cart, and the data for each page is the information about that product, including the current quantity in the cart.

A Page property named ItemToAdd on the work item page holds the data about the product item for which the user just clicked Add to Cart in the work form. Some of the embedded properties on the ItemToAdd page are used as fields in the Add Product to Cart window (for example, the Quantity field). An embedded property (Found) on the ItemToAdd page is a flag that indicates whether the item is already in the cart or not.

The CheckForProductInCart data transform uses a For Each Page In action to set the context to Items for a set of When and Otherwise actions.

For each page in Items, the system checks to see if there is already a page for the selected item. When the system finds that page (When.Name == Primary.ProductName), it sets values on the ItemToAdd page so that the current values related to that product in the cart are displayed to the user in the Add Product To Cart window.

Note: The keyword Primary is used in the When action before the ProductName property because the preceding For Each Page In action has set the clipboard page context to pyWorkPage.Items. Because the Name property is on the Items page list, you do not need to include the page name before the .Name in the When action.

However, the ProductName property is not on the Items page list, but is on the clipboard page associated with the OrderManagement-Int-Products class. Therefore, the keyword Primary must be specified to tell the system to locate the ProductName property on the data transform's primary page (the page for its Applies To class), because the page context in the For Each Page In branch is different than the class of the data transform rule itself.

For example, ItemToAdd.Quantity is set to the Quantity value for the page that meets the When criteria, so that the current value is displayed to the user. In this When branch, the data transform also sets the Found property to "true". When a page for that item is found, the Exit For Each action in the data transform is used, because once the particular product's page is found, the system does not have to go through the rest of the pages in the Items page list.

In the Otherwise branch, the Found property is set to "false", to indicate the product is not already in the shopping cart.

The Pages & Classes tab of this data transform specifies the pyWorkPage name and its class, so that the system can locate the Items page list, the ItemToAdd page, and the other properties from the work item that exist on the pyWorkPage.

The CheckForProductInCart data transform provides the flow action with the appropriate values to meet the desired user experience in the Add Product To Cart window. Then, in the After This Action area of the flow action's Action tab, the designer specifies the AddProductToCart data transform. This data transform:

• Updates the existing product page in Items to set the product's Quantity, if the product is already in the cart (when pyWorkPage.ItemToAdd.Found is "true").
• Adds a new page to Items and sets the values on that page, if the product is not already in the cart (the Otherwise branch).

AddProductToCart data transform:

The When-branch of actions when selected product is already in the shopping cart:

The Otherwise-branch of actions when selected product is not already in the shopping cart:

The Remove action at the end of this data transform removes the ItemToAdd page from the clipboard after the data has been copied to the Items Page List for the shopping cart contents.

Results

Using a data transform from a flow action provides the ability to map values between clipboard pages, so that those values can be displayed and updated in the flow action's user interface.