Using XPath Tokens

This article explains how to use XPath tokens to access data in pipeline workflows—especially when working with complex, nested, or irregular key structures. XPath tokens offer greater flexibility compared to native tokens, particularly when field names include special characters such as spaces or slashes.

Prerequisites

• Pipeline Basics
• Using the Token Picker
• Using Tokens Like a Pro

How to write XPath Tokens

XPath tokens use slash delimiters (/) instead of dot notation (.).

For example:

Native token:

{{<synapse-name>.<api-source-entity>.<api-field-name>}}

Equivalent XPath token:

{{/<synapse-name>/<api-source-entity>/<api-field-name>}}

Accessing keys with special characters

When field names contain spaces, slashes, or other special characters, you must use the XPath [@name="..."] selector.

In the case of custom action, where in native tokens we would use:

{{Action Result From <node-name>.results}}

with XPath we would use:

{{/.[@name="Action Result From <node-name>"]/results}}

Please note that if you are targeting a node or a custom synapse property with a special character name / api name, you need to place a dot character (.) before the [@name="..."] notation.

The [@name="..."] notation can also be used in subsequent keys to access the values with keys that have special characters. For example if we have a custom action response where after result the key for the first name includes a space we would use:

{{/.[@name="Action Result From <node-name>"]/results[@name="First Name"]}}

Filtering capabilities

With XPath notation you can filter a list of objects to extract only objects with a specific value. For example if we have a list of records with a key of type and we want to filter for records with only type 2 value.

Example custom action output:

{
"results": [
    {
        "id": 4831452147,
        "type": "type 1"
    },
    {
        "id": 4831468225,
        "type": "type 2"
    },
    {
        "id": 4425365225,
        "type": "type 2"
    }
  ]
}

We can access this by using:

{{/.[@name="Action Result From <node-name>"]/results[@type='type 2']}}

This would give us only second and third object in our example.

If the type property would be nested under a property, let's say a record key, we could also implement nested filtering by using [@record/type='type 2']. With XPath we can also construct lists of values from lists of objects. Let's say that in our example we are only interested in getting the id values from the list of object and don't need the full objects themselves. One option would be to use loop nodes and add the id values into a temporary variable. 

Alternatively with XPath it is possible to add the key we want to target and the output of the token will be a multivalued list:

{{/.[@name="Action Result From <node-name>"]/results[@type='type 2']/id}}

This token would output:

[4831468225, 4425365225]