Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 19 Mapping and Transforming Data : Examples of Mappings

Examples of Mappings
Some mappings require several steps to achieve the desired results. This section describes some complicated mapping scenarios and how to achieve the desired mappings using the tools available.
There are many methods to insert or modify XSLT statements in the function input schema. The examples in this section illustrate the simplest procedures to obtain the desired results. However, you do not have to follow the same procedures outlined in this section to achieve the correct set of statements.
Setting an Element Explicitly to Nil
In some situations, you may wish to set an element explicitly to nil. One situation is when you wish to insert a row into a database table and you wish to supply a NULL for one of the columns. To set an input element explicitly to nil, perform the following:
1.
2.
3.
4.
The element’s formula becomes blank and is not editable (because nil is the value of the element) and the explicit nil qualifier icon appears next to the statement .
Merging Input from Multiple Sources
You may have multiple items in the Scope Variables that you wish to map to one repeating element in the Function panel. For example, you may have multiple formats for customer records and you wish to create a single, merged mailing list containing all customers in one format. In this example, the schemas are the following:
The following procedure describes how to map multiple elements into a single repeating element.
1.
Because you are creating two different formulas for mapping, you need two copies of the repeating element, one for each format. The resulting output contains only one repeating customer element, but the two copies in the Function panel make it simpler to perform two different mappings.
2.
Map one of the elements from the Scope Variables to the first copy of the repeating element in the Function. For example, map $Retrieve-Customer-Type1/Customer to MergeMailingList/CustomerList/Customer.
The Mapping Wizard dialog appears and presents choices for what you would like to accomplish. Choose the For Each option and click Next.
The mapping wizard asks if you wish to automatically map items with the same names. Click Finish to accept the default mappings.
3.
Map the other element from the Scope Variables to the second copy of the repeating element in the Function. For example, map $Retrieve-Customer-Type2/Record to MergeMailingList/CustomerList/Customer.
In the Mapping Wizard dialog, choose the For Each option and click Next.
The mapping wizard presents you with an option to automatically map elements with the same name. Click Finish to accept the default mappings.
4.
Select the Address element and click the XPath Formula Builder icon in the Input tab toolbar. In the XPath Formula Builder, drag a concat() function into the XPath Formula field. This function is used to concatenate the three elements in the Record element in the Scope Variables area to one Address element in the function’s input.
Click the Data tab, then drag the $current()/Address/street element into the << string1 >> placeholder in the concat() function.
Drag the $current()/Address/state element into the << string2 >> placeholder in the concat() function. Then, add a comma to the end of the function to include a third string to concatenate. Drag the $current()/Address/zip element into the position of the third string in the concat() function.
5.
Click Apply, then click Close to dismiss the XPath Formula Builder dialog.
6.
Converting a List Into a Grouped List
You may need to convert a flat list of items into a more structured list. For example, you may have a list of all orders that have been completed. You may want to organize that list so that you can group the orders placed by each customer.
In this example, the schemas are the following:
The following procedure describes how to map the flat list of orders into a list grouped by customer ID.
1.
Choose the repeating element in the function input schema that holds the grouped data. In this example, that element is Orders. Right-click on this element and choose Statement > Surround with For-Each-Group... from the pop-up menu. This is a shortcut to create a For-Each-Group statement with the Orders element as a child element and a Grouping statement to contain the element you wish to group-by.
Adding the Grouping statement creates the $=current-group() element in the Scope Variables area. The Grouping statement creates the list grouped by the desired element, and the current-group() function allows you to access the items in the Requests repeating element that correspond to the group that is currently being processed.
2.
3.
Drag the element you wish to group by from the Scope Variables area to the Grouping statement in the Function panel. In this example, customerID is the grouping element.
4.
Map the current-group() element in the Scope Variables area to the repeating element Order under the Customer element in the Function panel.
The default choice in the mapping wizard for this mapping is to create a For-Each. Choose this option in the mapping wizard.
This creates an item in the Order list for each item in the current customer ID group that is being processed. The mapping wizard asks if you wish to map items with the same name in the current group and the orders group.
5.
Map the remaining element from the current-group() element into the desired element in the For-Each group. In this case, quantity would map to Quantity automatically, and Item must be mapped to ItemName.
6.
Merging Two Corresponding Lists
You may need to merge two lists that have corresponding items. For example, you may have a list of student IDs and a list of grades, each grade corresponds to the student ID in the same position in the student ID list. In this example, the schemas are the following:
The following procedure describes how to merge the two repeating elements containing corresponding data into one repeating element.
1.
Map the first repeating element from the Scope Variables area into the Grades repeating element in the Function panel. In this example, the $RetrieveStudentIDs/Students/Record is the first repeating element.
This brings up the mapping wizard with the default choice of creating a For-Each statement. Click Finish in the Mapping Wizard dialog to create the For-Each statement.
2.
3.
The Mapping Wizard dialog appears asking you to chose an option. Choose the Merge parallel repeating structure option and click Next.
4.
Merging two parallel repeating structures requires two variables. The mapping wizard prompts you to name these two variables. One variable is to hold the position number of the current item being processed, and the other variable is to hold the item in the second list that corresponds to the position of the item in the first list. Create the variables with the default names supplied by the mapping wizard, or choose your own names for these variables. Click Finish to proceed.
The two variables appear in the Scope Variables area once you have completed this step. The two variables also appear in the Function panel with the correct XPath statement to produce the desired result.
The $=[index=] element contains the XPath formula position() to set the element with the current position number of the list item being processed. The $=[item=] element contains a statement to retrieve the item in the second repeating element that corresponds to the position of the item in the first list that is currently being processed.
5.
Map the ID element to the StudentID element in the function arguments.
6.
Map the $=item/Grade element to the Grade element in the Function panel.
Coercions
In some situations, the datatype of a Scope Variables element may be undefined. In these situations, you may know the datatype of the element, and you can coerce the element into a specific type. The Coercions button in the Input tab toolbar allows you to create and manage your coercions.
The following example illustrates a schema with an element defined as the "any element" datatype. The schema is for a generic incoming message that can have any type of body. In the example, however, the any element is coerced into an Order type so that it can be mapped to a choice element.
In this example, the schemas are the following:
The following procedure describes how to coerce the Body element of the incoming message into a specific datatype and map it to a choice element.
There are many ways of accomplishing the same result as this example. This example attempts to illustrate the simplest method to achieve the desired result.
1.
Select the element of type any element in the Scope Variables schema. Click the Coercions button in the Input tab toolbar. In the Coercions dialog, click the Insert button (+) to add a coercion for the currently selected element.
The Coercions dialog allows you to manage all of your coercions for a function in one dialog. You can create, modify, or delete coercions for any element in the Scope Variables schema using this dialog, not just the currently selected element. If you are creating a coercion for an element that is not currently selected, use the XPath field to specify the location of the element.
Click the Element radio button to specify that you are specifying a schema element.
2.
Click the Browse Resources button next to the Schema field to browse a list of schemas that can be used. In the Select a Resource... dialog, select the schema that you would like to specify
Click OK to coerce the element into the datatype of the selected schema element. The following would be the resulting schema where the element of the datatype any element has been replaced with the Order schema.
3.
Map the Name element to the Name element in the Function panel. Then, map the coerced Order element to the choice element in the Function panel.
The Mapping Wizard dialog appears and asks if you wish to create an Order or a CreditLimitIncrease element. Select Order and click Next.
The Mapping Wizard then asks you to create a For Each. Even though there is only one element in the Scope Variables schema (the Message element is not repeating), a For Each is used because this construct allows you to map the individual items of the Order element. Click Next to continue.
The Mapping Wizard then asks if you wish to automatically map elements with the same name. Click Finish to accept the default mappings.
4.

Copyright © TIBCO Software Inc. All Rights Reserved