- 4 minutes to read

XPath Search Field Expression Plugin

The XPath plugin extracts one or more unique Search Field values from XML in the message body with an XPath 1.0 expression. It reads the message with a forward-only stream reader, so it handles large XML payloads, but it accepts only the forward-only XPath subset listed in Allowed XPath expressions.

  • ✅ One expression returns every matching element or attribute value
  • ✅ Element names match without namespace prefixes, so Orders/Order/Id works on <ns0:Orders>
  • ✅ node() as the first step covers several Message Types with different root elements

When to use it

Your data Use
Plain XML in the message body; you want element or attribute values as they are XPath (this page)
Only part of an XML value (a file name in a path, an ID in a formatted string), or tag names inside an XML sub-tree XPath with RegEx
XML stored as escaped text inside an element of another XML message XPath on Wrapped XPath
XML stored in a context property instead of the body XPath on Message Context
XPath 2.0, or XPath combined with other functions (decode Base64 first, concatenate, compare) Formula with xPath2

For the other plugins, see Choose a plugin.

Expression syntax

The XPath plugin has one field, Expression: the XPath 1.0 expression to evaluate against the message body.

  • Write the path from the root element without a leading / (Orders/Order/Id), as in the examples below.
  • Element names match without namespace prefixes or declarations: Orders/Order/Id matches <ns0:Orders xmlns:ns0="…">. Don't add prefixes to the expression.
  • Use @name or attribute::name for attribute values.
  • Use node() for a step whose element name varies, such as the root element of different Message Types.
  • Only forward navigation works. Axes such as parent:: or preceding-sibling:: can't be evaluated; see Allowed XPath expressions for the supported syntax.

Duplicates are collapsed into unique values; How expressions run explains how several values are stored. Pick the plugin in the Expression Type list when you add or manage a Search Field, and check the result in the Test Expression tab (Test Your Expression).

Expression Type list filtered on xpath, with the XPath plugin selected
The four XPath plugins in the Expression Type list; this page covers XPath.

Examples

Example 1: Get the order IDs from an order message

Input 

<ns0:Orders xmlns:ns0="Common.Schemas/Nodinite/1.0">
    <Order>
        <Id>101</Id>
        <Amount>1000</Amount>
        <City>Karlstad</City>
    </Order>
    <Order>
        <Id>102</Id>
        <Amount>10</Amount>
        <City>Stockholm</City>
    </Order>
</ns0:Orders>

Expression 

Orders/Order/Id

Result 

101
102

Test Expression tab with the XPath plugin returning 101 and 102 from an Orders message
The expression has no ns0: prefix and still matches the namespaced Orders root; the test reports 2 unique matches.

Example 2: One expression for two Message Types

Orders and order responses have different root elements. node() matches either root, so the same expression works on both Message Types.

Input 

<ns0:Orders xmlns:ns0="Common.Schemas/Nodinite/1.0">
    <Order>
        <Id>101</Id>
        <Amount>1000</Amount>
    </Order>
</ns0:Orders>

<ns0:OrderResponse xmlns:ns0="Common.Schemas/Nodinite/1.0">
    <Order>
        <Id>101</Id>
        <Status>OK</Status>
    </Order>
    <Order>
        <Id>102</Id>
        <Status>Failed</Status>
    </Order>
</ns0:OrderResponse>

Expression 

node()/Order/Id

Result

Orders Message Type OrderResponse Message Type
101 101, 102
XPath test: node()/Order/Id on an ns0:Orders message returns 101 XPath test: node()/Order/Id on an ns0:OrderResponse message returns 101 and 102
The root is ns0:Orders; node() matches it. The root is ns0:OrderResponse; the same expression matches it.

Example 3: Read an attribute

Input 

<Shipment>
    <Package trackingNo="1Z999AA10123456784" weight="2.4"/>
    <Package trackingNo="1Z999AA10123456791" weight="0.8"/>
</Shipment>

Expression 

Shipment/Package/@trackingNo

Result 

1Z999AA10123456784
1Z999AA10123456791

XPath test: Shipment/Package/@trackingNo returns two tracking numbers
@trackingNo selects the attribute on each Package element.

Limitations

  • The plugin uses a forward-only stream reader based on Microsoft's XPathReader, so only XPath 1.0 expressions that read forward are supported. Check Allowed XPath expressions before you build an expression.
  • For XPath 2.0, use the Formula function xPath2; the Formula function xPath gives XPath 1.0 inside a formula.

An unsupported expression, or one that matches nothing, gives this result in the test:

Test result: Processed with warning, the provided expression yielded no result
No match: the test reports a warning instead of values.

Next Steps