In the Graphical Data Mapping editor, you can use the fn:string-join transform to create an output element that is the result of concatenating a sequence of input elements with a delimiter as optional.
The XPath 2.0 function
fn:string-join(arg1, arg2) takes two arguments, converts
them to their string representation, and concatenates them, returning a single string.
The fn:string-join transform is the representation of the fn:string-join XPath function in the Graphical Data Mapping editor.
You can have any number of inputs to the fn:string-join transform. These inputs can be used to define the arguments of the fn:string-join function.
Inputs to the transform
- One of the primary inputs must be a repeatable simple element. This input is used to define the
first argument of the fn:string-join function. It defines the sequence of
elements that you want to concatenate.Note: When the type of the repeating elements is different from xs:string, the Graphical Data Mapping editor will cast the element to a xs:string type.
- One of the primary inputs can be a simple type element. This input is used
to define the second argument of the fn:string-join function. It defines the
delimiter used between the elements that you want to concatenate.Note: If the simple type is not of type xs:string, the transform will fail at run time with BIP3945E. Cast the element to a string if you want to use a non-string input element as your delimiter. For more information, see Cast type (xs:type).
- More inputs can be connected to the fn:string-join transform. You can use these inputs as additional information to the transform. For example, you can use these inputs as arguments of the XPath expression that you can define in the Condition tab to determine whether the transform is applied at run time.
Arguments of the XPath function
- The first argument is a sequence of elements.
- The second argument is a delimiter. The delimiter is optional. If the separator defined for the fn:string-join function is a zero-length string, no delimiter is used.
In the following figure, the fn:string-join transform has one input. The input is used to define the first argument of the fn:string-join function. No delimiter is configured.
The following figure shows the fn:string-join transform with one repeating element as input, and a separator. To add the delimiter, you must select the General tab in the Properties view, click Edit, and then enter the value.
The Cardinality property determines the elements (also known as indexes) in the repeating input element that are processed by the fn:string-join transform.
You can configure the Input array indexes section to select specific instances of the input array. For more information, see Selecting the indexes of input array elements.
Control the instances to be concatenated
When the instances that you need to concatenate need to be calculated at run time based on a condition, you can filter dynamically the input indexes by defining a custom XPath conditional expression for the first argument named strings in the General tab. The expression determines which elements of the repeating structure are applied at run time.
For example, to calculate the value of the output element a, you must concatenate the elements in the repeating structure C whose length is greater than 4. You can use the following XPath expression:
$C2[fn:string-length() > 4]
Define when the transform is applied at run time
You can use any of the input elements to the fn:string-join 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.