Concat

You can use a Concat transform to concatenate data from two or more simple elements into a string output element.

Overview

The Concat transform concatenates two or more simple inputs into a string output element.

When you configure the Concat transform, you can specify a prefix, a suffix, and a delimiter through the Properties page:

You can specify an alphanumeric character to be the delimiter between the strings,. You can also use a string prefix and a string suffix.

For example, you can concatenate the strings from the elements firstname and lastname, and specify a space as the delimiter, a prefix of Mr. , and a comma as the suffix, with the following result: Mr. firstname lastname,

When can you use the Concat transform?

You can use the Concat transform when the following premises apply:

You want to concatenate data from two or more single type inputs.
The input types to the Concat transform can be any simple or primitive data types.

Note: Simple type input elements that are not of type xs:string will be cast to xs:string.
All the inputs to the Concat transform, that are connected as primary connections, are used to calculate the value of the output string element.
You might need to define a prefix.
You might need to define the same delimiter between input values.
You might need to define a suffix.

You cannot select and use the Concat transform when any of the following criteria on inputs applies:

One of the inputs to the Concat transform is a complex type element.
One of the inputs is a repeating element, that is, the input element cardinality is set to [1..*] or [0..*].

Inputs to the Concat transform

The Concat transform takes multiple simple type elements.

You wire inputs to the Concat transform as primary connections.

You can wire the same input into a Concat transform more than once.

The Concat transform concatenates input data in order. The order of inputs into the transform is recognized, and is set in the Order property page.

This figure shows a Concat transform in a map.

Order of the inputs

By default, the order of the inputs to the Concat 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.

Define when the transform is applied at run time

You can define multiple connections between input elements and the Concat 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 only can use inputs that are connected with a primary connection to the transform, and all inputs will be concatenated. It is not possible to have an input that is only used in the condition.

Note: When you need to apply the Concat transform conditionally, use an If transform and place the Concat transform within the nested mapping of the If.

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 Concat 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.

Warning error

By default, you cannot connect a repeating simple element to a Concat transform. However, if you have a map where you have defined a Concat transform, and you change the cardinality of one of the input elements so it becomes a repeatable simple type, the Concat transform will show a warning.

The warning message is the following:

Each input of the string concatenation function expects a single input. Make sure {0} will not pass multiple instances to the function at run time.

The warning is displayed because at least one input is not of single type.

When a Concat transform has such a warning, the run time behavior is the following:

If the input XML has no more than one instance of the repeatable input, the Concat transform produces the expected result at run time.
If the input XML has more than one instance of the repeatable input, the Concat transform results in a run time exception.

Example for a repeating single input element to a Concat transform:

This figure shows the Concat transform warning error when using repeating simple type elements.