Mapping with XPath and Liquid

Most text fields in the management UI can contain either XPath expressions, or a combination of literal text with liquid expressions.

XPath

For a text field to contain an XPath expression, it must be in expression mode, this can be done by setting the toggle to On, as shown here. The toggle will display a preview of your XPath expression by evaluating it against the example input provided at the top of the workflow definition.

Liquid

Liquid is a templating language for mapping more complex data. A full guide on Liquid can be found on Shopify's documentation.

When a text field is in literal mode, it can contain liquid expressions. To access the context, expressions should be in the form {{ context.your-value }} where context replaces the base element of your input xml, and your-value is a dot sepearated path to your desired value.

Liquid expressions in emitted contexts can also access the task instance itself, so you could for instance access the task ID using something like {{ task.Id }}.

Liquid Data Shape

The most important thing to know with Liquid is the shape of the data you're working with. The root properties are subjectId, context and task, for accessing the subject Id, xml context and task properties. The task properties are only available when mapping an emitted context.

If you had a task instance with this context:

<xml>
    <name>Roberto</name>
    <age>32</age>
</xml>

Then the shape of the data accessible via liquid would look like this:

{
    // Always available
    "subjectId": "string",
    "correlationId": "string",
    "owner": "string",
    "ownerType": "string",
    "context": {
        "name": "Roberto",
        "age": "32"
    },
    // Only availble in mutations
    "updateContext": {
        "name": "Roberto Roberts",
        "age": "33"
    },
    // Only available in the emitted context
    "task": {       
        "Id": "string",
        "TaskKey": "string",
        "Name": "string",
        "Created": "string",
        "Updated": "string",
        "LastRun": "string",
        "SubjectId": "string",
        "WorkflowDefinitionId": "string",
        "Filters": "string",
        "Context": "string",
        "ActivityContext": {
            "Status": "string",
            "Due": "string"
        },
        "Description": "string",
        "AssigneeId": "string",
        "AssigneeType": "string",
        "Notification": "string",        
        "TaskDefinitionId": "string",
        "TaskType": "string",
        "Creator": "string",
        "State": {
            "comments": "string",
            "reviewer": "string"
        },
    }
}

Liquid Example

If we wanted to emit some of the task data alongside an event, we could define an emitted context like this:

<xml>
    {{ context }}
    <comments>{{ task.State.comments }}</comments>
    <subject>{{ subjectId }}</subject>
</xml>

When the event is fired, this would be mapped into this:

<xml>
    <name>Roberto</name>
    <age>32</age>
    <comments>My comments</comments>
    <subject>subject-id</subject>
</xml>