Built-in XPath transforms

Overview

The Graphical Data Mapping editor supports XPath functions that allow you to manipulate graphically string values, numeric values, date and time comparison, and more.

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

All XPath 2.0 functions are supported in the form fn:<function_name>.

When you need to define complex XPath expressions, use the Custom XPath transform. For more information, see Custom XPath.

Inputs versus arguments

When you use an XPath transform, you must differentiate between inputs to the transform and arguments required to run the XPath function represented by the XPath transform.

Arguments are the data elements required in the calculation of an XPath function.

An argument can be a literal expression, a constant, an input element, a custom XPath expression, or a combination of multiple input elements.

You can have any number of inputs to an XPath transform. You use these inputs to define the arguments of the XPath function.

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

Modify the value of an input element before you apply the XPath function in a map

You can modify the value of an input element to an XPath function in the Properties page of the XPath transform.

You can define an XPath expression or a call to a static method on an imported Java™ class to modify its value. You can also create a complex expression comprising XPath, and Java.

In the General tab, you get the list of input elements to the XPath transform. For each element, the name, type and value are displayed.

To change the input value, you must select the element, and click Edit. Then you can enter the expression to modify the value.

Define when the transform is applied at run time

You can define multiple connections between input elements and an XPath transform. You can then use 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.

Alternatively, to define the conditional expression, you can call 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.

You can use the inputs connected with a primary connection to the transform. To add more inputs, you can define supplement connections between input elements and the 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 defined by an XPath function that requires data from two inputs. One of the arguments is set with data from an input. The prefix and the suffix are literals.

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

<NewElement1>
    <a>MyPrefixFieldAFIELD_EMySuffix</a>
</NewElement1>

Troubleshooting

BIP3946E:

BIP3946E: The map script generation for QName {1} has failed, with the following details: {2}

You get BIP3946E when you try to deploy a map that contains an invalid XPath expression. Check the description provided by {2} to find out which expression is not a valid.