fn:concat

In the Graphical Data Mapping editor, you can use the fn:concat transform to create a string output element that is the result of concatenating simple input elements.

Overview

The XPath 2.0 function fn:concat(arg1, arg2, ,,,) takes two or more arguments, converts them to their string representation, and concatenates them, returning a single string.

The fn:concat transform is the representation of the fn:concat XPath function in the Graphical Data Mapping editor.

You can have any number of inputs to the fn:concat transform. These inputs are used to define the arguments of the fn:concat function.

For more information about XPath, see XPath tutorial or W3C XML Path Language (XPath) 2.0.

When to use the fn:concat transform

You can use fn:concat to concatenate input elements.

You can configure the arguments to the fn:concat transform to represent a prefix, a suffix, and delimiters.

You can use the first argument as the prefix.
You can use the last argument as the suffix.
You can insert a delimiter as an argument between any two arguments you want to delimit.

Inputs to the transform

You can connect simple elements to the fn:concat transform.

Simple input elements that are not of type xs:string will be cast to xs:string.

The following figure shows two inputs connected to the fn:concat transform:

This figure shows the fn:concat transform between simple input type elements.

Note: The Graphical Data Mapping editor does not display an error or a warning on a fn:concat transform when the input to the transform is not a single type element, or is repeatable.

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

Arguments of the XPath function

The fn:concat function has two or more non-repeating arguments.

Note: A run time failure occurs complaining that a sequence is not valid if you do not ensure that each argument is non-repeating.

You define the number and the order of the arguments to the fn:concat function in the General tab of the fn:concat transform properties view.

You can use the Add button on General tab to create additional arguments:

You can add a literal value entered in single quotes.
You can add a Custom XPath expression.

In the following figure, the fn:concat transform has two inputs. Each input is used as an argument of the fn:concat function:

This figure shows the fn:concat transform with 2 inputs and 2 arguments.

In the following figure, the fn:concat transform has three inputs, whilst the fn:concat function only requires two arguments. Two of the inputs are used to define one of the arguments of the fn:concat transform:

This figure shows the fn:concat transform with 3 inputs and 2 arguments.

Define a conditional expression

You can use any of the input elements to the fn:concat transform to define a conditional expression that defines the condition under which the transform is applied. If the condition evaluates to true, the transform is applied.

For more information, see Configuring the properties of a transform.

Example

This example shows how to use the fn:concat transform to concatenate multiple input elements and set the value of a string element by using the fn:concat function.

The arguments to the XPath function include a prefix, two elements, and one suffix. One of the arguments is set by an XPath function base on calculations from data from two inputs. One of the arguments is set with data from an input. The prefix and the suffix are literals.

This figure shows the fn:concat transform with 3 inputs, a prefix, 2 arguments, and a suffix.

When you run the following message and transform the data with the fn:concat transform:


<NewElement>
  <A>My FieldA</A>
  <B>B1</B>
  <C>Field_1</C>
  <D>4</D>
  <E>FIELD_E</E>
</NewElement>

You obtain the following result:


<NewElement1>
    <a>MyPrefixtrueFIELD_EMySuffix</a>
</NewElement1>