Choosing a transform to map repeating elements

In the Graphical Data Mapping editor, you can use the For Each transform, the Append transform, the Join transform, XPath functions, the Custom XPath, and the Custom Java transform to map input and output arrays. You can use any of these transforms to choose the set of the elements in the array that you want to transform, and place the result in an output array or single element.

Choose one of the following transforms to map repeating elements:

1. When you have repeating elements as input and output to a transform, you can use the For Each transform to set the output array element.

   The For Each transform iterates over one input array element, which can be either a simple type or a complex type, and enters a nested mapping in which you can provide transforms to populate an instance of the output from the input. You can configure the cardinality to filter which instances to process based on index. Also, you can provide a Boolean expression which will be applied to each instance to determine if it will be mapped.

   

   Additionally, you can also set the Allow empty input option so that the Graphical Data Mapping editor enters the nested transform once when no matches occur. This can be used to implement an outer join by providing a supplementary input to the For Each.

   For more information, see For Each.

2. When you have multiple inputs that are either simple type elements, complex type elements, or repeating elements from which you need to construct an array, you can use the Append transform to add instances to either a simple type output array or a complex type output array.

   For more information, see Append.

3. When you have multiple inputs that are either simple type elements, complex type elements, or repeating elements as input to a transform, and you want to join these elements, you can use the Join transform to combine them into a single repeating output element. The output element can be an array or a single element. You configure an expression to control the match conditions for the join. The Graphical Data Mapping editor provides a link to create a simple match by index expression.

   For more information, see Join.

4. You can use XPath functions to map from an array to a single element. For example, you can use fn:string-join to return a string created by concatenating multiple string arguments or fn:sum to return the sum of a repeating numeric element into a single element.

   For more information, see Built-in XPath transforms.

5. When you want to map a particular instance from an array to a single output you can use a Custom XPath transform that has an XPath predicate expression to select a particular instance.
   For example, if you want to select the "Country" value from the instance of an array of "Address" elements that has a child element "Type" with the value "home", use the following form for your Custom XPath transform:

   $Address[Type = 'home']/Country

   Note: If you want to use an input element value to dynamically select an element of an array by index, you must ensure that your XPath predicate expression yields a singleton numeric value. For example, to select the "Country" value from the instance of an array of "Address" elements at the index that is specified by an input element "Counter" (that is defined as xsd:int), use the following form for your Custom XPath transform:

   $Address[fn:data($Counter)]/Country

   The fn:data() function is used to obtain the numeric value of the input element. If the "Counter" element is defined as xsd:string you must use the following form to explicitly cast the value to a numeric value:

   $Address[xs:int($Counter)]/Country

6. You can use a Custom Java transform to map an array by passing the array as an input or output parameter using a list of MbElement objects.

   For more information, see Custom Java.