Message Image  

XPath in IBM Integration Bus

 View Only
Tue July 14, 2020 01:26 PM

santascookies

XPath in Integration Bus provides you a lot more than it’s W3C standards based syntax for defining parts of an XML document.

It enables you to express conditions, perform operations on strings and numeric data and call on a rich set of processing functions. Significantly although XPath is generally associated with XML data, in Integration Bus, the power of XPath can applied with other data formats, such as text or binary data that has been parsed using DFDL, or JSON data parsed using the JSON domain parser.

Examples of the use of XPath in IBM Integration Bus include:

  1. Node logic conditions, e.g. Route node
  2. Data Selection on various node properties, e.g. Monitoring Event data
  3. The Graphical Data mapper has XPath at it’s core, XPath expressions are used for
    • Conditions on “If – Else”, “Join”, filters on “For each” transform
    • Numeric operations, String manipulation, and data processing on “Custom XPath transforms”
  4. Extracting information from messages in a JavaCompute node
  5. Dynamic processing properties in a DFDL model

Since XPath is such a powerful tool in Integration Bus Development we thought we’d bring you some key points for it’s effective use.

Firstly in XPath everything is a sequence, so it’s key to understand what a sequence is.

XPath naturally handles repeating elements and values. An XPath can match multiple elements, for example song/verse, selects all ‘verse’ data nodes that are children of ‘song’ and will return them in a ‘sequence’ of nodes. You can use an XPath predicate to only match one node, for example $song/verse[newItemName='Drumming'], selects only the ‘verse’ data node that is a child of ‘song’ and has a data node ‘newItemName’ with value ‘Drumming’. Applying this to a model of a popular festive song would match just one verse. It will however still be returned as sequence, containing just one node. A sequence is expressed as a comma separated list enclosed in parenthesis ( $node1, $node2 ).

Some XPath expressions expect to work with data values, not data nodes, for example sum(song/verse/newItemCount). This is not a problem, XPath will automatically extract the values from the sequence of nodes.

Note however that while XPath will automatically perform this “atomization” to obtain the data value from a node sequence, some expressions, in particular numeric operators require a single data value, not a sequence. For example song/verse/newItemCount + 1 would likely fail. You must alter this expression to ensure just one ‘newItemCount’ data value is selected by the XPath, perhaps using an array index predicate like song/verse/newItemCount[previousIndex] + 1.

You can apply an array index predicate to an XPath sequence. This can be used to implement a coalesce function. Coalesce functions evaluate the arguments in order and return the first one that yields a value. Hence for our festive song we could use:
( $song/verse[newItemName=$item]/newItemName, fn:concat($item, ' not in any verse' )[1]
to return either the value of ‘newItemName’ from the first verse that has a ‘newItemName’ matching ‘item’ or if none the text ‘ not in any verse’.

Using XPath for Conditions.
When using XPath for conditions you provide an XPath expression that yields a true or false Boolean value. In XPath, all data values have an ‘Effective Boolean Value’ (EBV). The following values have the EBV false:

  • The xs:boolean value false
  • The numbers 0 and NaN
  • The empty string ”
  • The empty sequence ()

Everything else has the EBV true.

Hence you can provide conditional expressions that are simply a path.

A boolean value can also be produced by XPath’s comparison and logical operators:
=, !=, <, >, <=, >=, eq, ne, lt, gt, le, ge, and, or, not.

There are also a range of XPath functions that return a Boolean value. Please note that the XPath function fn:empty($path) returns Boolean true only if the passed path yields a sequence that is empty, it is not a string operator. To test for an empty string you must instead use $path == ''. To test for the existence of a node, or at least one node in a sequence use fn:exits($path).

Using XPath for Numeric calculations.
All the usual mathematical operators are built into the XPath syntax and there is a rich numeric function library – e.g. sum, count, round, max, min, etc.

As already noted above numeric operators can only be applied to single data values, you must ensure when providing a path that it will only select one single data value node.

Another point to note when using numerical operators and functions is that values will be automatically promoted to the higher precision. For example currency values may sometimes be defined in the message model as double, however you may require a calculation to be performed using two digit decimal precision. This can be achieved using the “xs” type casting and XPath, “fn” rounding functions. For example the total ‘Item’ cost in the “Transformation using a Map” tutorial is calculated with the following XPath expression in a Graphical Data Map Custom XPath transform:
fn:round-half-to-even( (xs:decimal($Price) * xs:decimal(1.6)), 2 )

Using XPath for strings manipulation.
You can use XPath expressions to manipulate strings by exploiting the extensive function library for string comparing, concatenation, splitting, joining, etc.
For example you can use the fn:string-join to produce a single string from a sequence, repeating set of inputs. Conversely the fn:tokenize function can be used to split a single string value into a sequence of values that could then be assigned to a repeating output target.

In this post we have looked at just a few ways you can exploit XPath, we hope this has been helpful and please let us know what aspects you’d like to know more about.

2 comments on"XPath in IBM Integration Bus"

  1. Daniel Steinmann April 09, 2019

    I tried to add your coalesce XPath like ( $Root/XMLNSC/foo/bar, $Root/XMLNSC/test/ing )[1] to extract a global correlation id when configuring the transaction start monitoring event, but I can not save it. It says:

    The ( $Root/XMLNSC/foo/bar, $Root/XMLNSC/test/ing )[1] XPath must start with a XPath variable.

    Any idea how I can convince the XPath editor of IIB 10.0.0.14 to accept this?

    Reply (Edit)
    • BenThompsonIBM August 20, 2019

      Hi Daniel,
      Apologies for the delay in approving this comment … for the benefit of others who may hit this … The syntax which the XPath expression builder page allows is not the full range of the XPath standard … in this circumstance, the expression builder is designed to help navigate to a variable in your tree rather than be used as a means of computation based on multiple values in the tree (such as coalesce). The allowable syntax can be investigated using the drag and drop functions of the two available windows on the dialog page (“Data Types Viewer” and “Operators”) or by using ctrl-space keys in the Expression editor. The intention of the use of an xpath expression in this particular circumstance is to allow you to reuse a value from the tree as your global transaction id. If you’d like to only emit a monitoring event in certain circumstances (dependent on the presence of a particular value in your tree) then you can do this with the Event Filter option of the monitoring page dialog.
      Cheers, Ben

      Reply (Edit)