Custom XPath

You can use the Custom XPath transform to provide a data value for a simple target element, or values for a repeating simple target element by using an XPath expression.

Overview

You define the XPath expression in the General tab of the Properties view.

You can use context assist by pressing Ctrl+Space while constructing the XPath expression. For more information, see Using content assist (Mapping syntax).

When to use the Custom XPath transform

You can use the Custom Xpath transform to perform any of the following mappings:

Implement an arithmetic operation, such as add, subtract, or multiply. For more information, see Choosing a transform to perform an arithmetic operation.
Implement complex XPath expressions. You can extend built-in transformation functions by using custom XPath expressions. For more information about XPath, see XPath tutorial or W3C XML Path Language (XPath) 2.0.
To access user-defined properties. For more information, see Accessing user-defined properties from a Mapping node.
To set an output to null or nill, use iib:nullValue(). For more information, see Creating a nil output element.
To set an output hex binary BLOB value, use iib:hexBinaryValue($<var>
To set an output base64 binary value, use iib:base64BinaryValue( $<var>
To set a new UUID value, use iib:uuidValue()

Inputs

Inputs are optional to Custom XPath transforms. If required, you can connect any input elements to a Custom XPath transform and access them as part of the XPath expression.

Outputs

You can use a Custom XPath transform to set the data value of a simple target element, or to set the values for a repeating simple target element.

By default, if the XPath expression does not provide a value, the transform creates the target element with an empty value. If you do not want the target element to be created, you can add a conditional expression in the Condition tab.

Note: The Custom XPath transform returns values, not elements. You cannot use a Custom XPath transform to create elements other than the simple target element. For this reason, you cannot populate a complex structure from a Custom XPath transform.

Define when the transform is applied at run time

You can define multiple connections between input elements and the Custom 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.

You can use any inputs that are connected with primary connections to the transform. To add more inputs, you can define supplement connections between input elements and the transform.

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 that comprises 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.

Example

The following figure shows a Custom XPath transform that performs the following calculation:

Uses the fn:substring XPath function to obtain part of the information provided in element E.
Uses the fn:concat XPath function to concatenate the result of the fn:substring function, with the delimiter _, and the element D.
Uses the fn:lower-case XPath function to put in lower case the result of the fn:concat function.

The XPath expression is a complex expression where you nest multiple XPath functions to perform the calculation. The XPath expression is the following:

fn:lower-case(fn:concat(fn:substring($E,10,5),'_',$D))

Custom XPath transform properties pane

If you input the following message:


<?xml version="1.0" encoding="UTF-8"?>
<NewElement>
  <A>A1</A>
  <B>B1</B>
  <C>Field_1</C>
  <D>1000</D>
  <E>CUSTOMER_AREA1</E>
  <F>Optional1</F>
  <G>Optional1</G>
</NewElement>

you get the following output value:


<NewElement1>
 <a>area1_1000</a>
</NewElement1>

Example: How to perform an arithmetic operation

This example shows how to perform an arithmetic operation by using a Custom XPath transform.

The transform has 3 inputs, that are used as part of the calculation that determines the value of the output element b.

Note: You can only use as arguments of an arithmetic operation non-repeating simple type input elements.

The operations consists on adding the value of the input element A to the value of calculating D times E. The value of E is of type string. The value of E is cast to an integer.

($A3 + ($D2 * (xs:integer($E1))))

This figure shows the custom XPath transform used to perform an arithmetic operation.

When you transform the following message, the value of b is 120010.


<?xml version="1.0" encoding="UTF-8"?>
<NewElement>
  <A>10</A>
  <C>2</C> 
  <C>10</C> 
  <D>1000</D>
  <E>120</E>
  <F>Optional1</F>
  <G>Optional1</G>
</NewElement>