Append

You can use the Append transform to create an output array in the order of the inputs.

Overview

The Append transform is not available in the list of available transforms until you wire at least two inputs to a transform.

To build an output array of N elements where you have N inputs available in a flat structure, you wire each input to the Append transform.

For example, the following figure shows two flat structures, HomeAddress and OfficeAddress wired into an Append transform to create the Address array.

Figure that shows two flat structures wired to the Append transform to create an output array.

To build an output array of N elements where you have less than N unique inputs to wire into the Append transform, you can wire the same input multiple times.

If your input to the Append transform is repeating, you can use the For Each transform.

The only way to control the order of populating an output array is by using the Append transform. You must provide input connections to the Append transform and set their order in the Properties page.

Note: You must use the For Each transform, instead of the Append transform, when you need to create an output array where the input element is repeating. In the nested map of a For Each transform, you can use an If transform to define the condition under which the Append transform is applied for each instance of the input element.

Inputs to the Append transform

The Append transform takes multiple inputs of either simple type or complex type.

Inputs of single, non-repeating elements are also allowed. Each single input element adds an extra occurrence to the output array.

You wire inputs to the Append transform as primary connections.

You can wire the same input into an Append transform more than once if you need to produce more than one array instance from a single input.

The Append transform iterates over multiple inputs in the specified order to append data. The order of inputs into the transform is recognized, and is set in the Order property page.

The Append transform provides a nested transform for each input in the output array.

The nested transforms are performed for each input sequentially, producing occurrences of the output array. First over all elements in the first input, then over all elements in the second input.

When you connect a repeating input, each instance adds an extra occurrence to the output array. You can use the Cardinality property page on the transform to specify a subset of indexes the transform should process. The first index element is 1.

Output of the Append transform

The output of an Append transform can be a simple type array or a complex type array.

The output array size is the sum of the input elements wired to the Append transform.

Note: You can define any number of inputs to the Append transform. The Graphical Data Mapping editor does not validate the number of inputs. You must ensure that the number of wired inputs to the Append transform correspond to the value configured in the Maximum occurrence property of the output array.

Order of the inputs

By default, the order of the inputs to the Append transform is the order in which you wire the inputs.

You can modify the order by reordering the inputs in the Order tab of the transform properties.

Note: You can only order inputs that are connected with a primary connection to the transform.

This figure shows the Order tab of the Append transform properties.

Inside the nested map

When you define a transform inside the nested map of an Append transform, you can only connect one input element to any transform that you define.

The Graphical Data Mapping editor reports error CWMSL259E if you connect multiple inputs to a transform inside the nested map.

If your input element is a repeating element, you can only use a For Each transform or an If transform on the repeating input.

You can use the For Each transform to build an output instance for every index that is applied. The Cardinality and Filter Inputs properties determine which indexes of the repeating input are applied.
You can use the If transform to build a single output instance. The If condition determines which index of the repeating element is applied to calculate the output value.

If the input element and the output element to an Append transform have a global type, you can use a Submap instead of a Local map.

Define when the transform is applied at run time

You can define multiple connections between input elements and the Append transform. You can then use one or more of these input elements in a conditional expression that defines the condition under which the transform is applied. If the condition evaluates to true, the transform is applied.

Note:

You can use only inputs that are connected with a primary connection to the transform.
All inputs will be present in the nested map of the Append transform and by default mapped to produce an occurrence of the output.

If you need an input element to define a condition and you do not want the input element to be part of the output array, complete the following steps:

Connect the input element with a primary connection to the Append transform.
Define your condition.
In the nested map associated with the Append transform, a Local Map is added. Within the Local Map, a Move transform is defined for each input element. Delete the Move transform associated with the input element so that the input element is not appended to the output value.

To define the conditional expression, you can define an XPath expression or a call to a static method on an imported Java™ class. You can also create a complex expression comprising XPath, Java and extension functions such as iib:getUserDefinedProperty("propertyname").

You configure the expression in the Condition tab that is available in the Properties page of the transform.

For more information, see Configuring the properties of a transform, Defining an XPath conditional expression for a transform and Defining a Java conditional expression for a transform.

If your conditional expression requires the value of an input element that is not used in the Append transform to set the output element, you must use the If transform to define when the transform is applied at run time. For more information, see If, Else if, and Else.

Example

This example shows how to create an output array with two indexes by using the Append transform.

You connect two input elements (HomeNumber and Mobile) to the Append transform. These inputs will be used to set the value of multiple indexes in the output repeating element Phonedetails.

You also define a connection from the Append transform to the repeating element Phonedetails.

This figure shows the Append transform.

When you open the nested map associated to the Append transform, you get two Local Map transforms, one per input element.

This figure shows the Append transform nested map.

Inside each Local Map transform, you define the transformation logic that sets the output values for one index of the output repeating structure Phonedetails.

The following figure shows the nested map associated with the Local Map transform for the input element Mobile:

This figure shows the Local Map transform nested map for one input element.

The following figure shows the nested map associated with the Local Map transform for the input element HomeNumber:

This figure shows the Local Map transform nested map for an input element.

You can configure the order in which the indexes are created. You set the order in which indexes are created in the Order tab of the Properties view of the Append transform.

In this example, the first index contains the information of the home number. The second index contains the information of the mobile number.

This figure shows the Append transform properties page.