- 5 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

XPath expression tested on a logged Orders message, animated walkthrough (7.12)
Animated walkthrough: in Edit Search Field Expressions, pick the XPath type, enter the order id path, apply it to the Orders Message Type, and test it on the logged message; the Result shows two unique matches, 101 and 102.

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 Type list when you add or manage a Search Field, and check the result in the Test Expression tab (Test Your Expression).

Type list filtered on xpath, five plugins listed with XPath selected (7.12)
Filtering the Type list on "xpath" shows the five plugins with XPath in their name, JSON Path Base64 Decode with XPath included; 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>Gothenburg</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 (7.12)
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 with a node step as the root on an Orders message, returning 101 (7.12) XPath test with a node step as the root on an OrderResponse message, returning 101 and 102 (7.12)
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 reading the trackingNo attribute of each Package, returning two tracking numbers (7.12)
@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 Expression yields no result (7.12)
No match: the test reports Processed with warning: The Expression yields no result instead of values.

Next Steps