Mutations

Mutations allow you to update an existing task. They run under the same conditions a trigger can be run, and additionally include a JSON Patch document which describes how a task should be updated. Mutations must match the trigger conditions and have the same correlation id. If an event is raised without a matching correlation id, it will be ignored.

Syntax

The JSON Patch document is the same format as a HTTP Patch. Each item in the array describes a single operation applied to the original task. An example document to change a task name to "new name!" would look like this:

[
    {
        "op": "add", // "add", "remove", "replace"
        "path": "/name",
        "value": "new name!" // The new value of the property. Can be any valid JSON, as long as it matches the type of the property being patched
    },
]

The entire JSON document can be templated using liquid syntax, so e.g. the value of the property being updated can be dynamic depending on the event context.

Supported Fields

The path property of a mutation can be set to any of the following:

• /name
• /description
• /activityContext/status - the status of the task, e.g Completed, Cancelled etc
• /state/{key} - to set a single state value
• /state - to set the entire state at once
• /assigneeId
• /assigneeType
• /activityContext/due - the due date
• /activityContext/expiry - the expiry date

Accessing Context in a Mutation

Mapping data from the mutation context is slightly different to the normal context, because the liquid base element is {{ updateContext. }} rather than the usual {{ context. }}, because the latter will access the original task context instead of the context of the event that has triggered the mutation.

Updating Task Status

To update the status of a task using a mutation, the value must be a valid task status: New, InProgress, Completed, Cancelled, Failed or Blocked. The usual task status validation rules apply, so your mutation cannot change tasks into an invalid status.

For example, if you wanted to mark a task as completed using a mutation, you could use something like this:

[{
    "op": "replace",
    "path": "/activityContext/status",
    "value": "Completed"
}]

Conditionally Applying Mutations

Mutations can be applied conditionally using Liquid if statements, for example the following mutation would only be applied if the age is greater than 30.

[
    {% if updateContext.age > 30 %} 
    {
        "op": "add",
        "path": "/state/ageCategory",
        "value": "Over 30"
    },
    {% endif %}
]

Completing a task on form submission

A common scenario is to complete a task based on event that represents the submission of an AireForm form. To do that you would typically have a mutation along the lines of:

[
  {% assign action = updateContext.Action | append: "" %}
  {% if action == "ClinicianFormSubmitted" %}
    {
        "op": "replace",
        "path": "/ActivityContext/Status",
        "value": "Completed"
    }
  {% endif %}
]

Note: we have added a guard condition to filter for ClinicianFormSubmitted events only.

Debugging Mutations

If your mutation is not working as you expect there are several things to double check first:

• Does the routing key of the event match the trigger you've defined for your mutation?
• Does the correlation ID of the event match the correlation ID of the task you're trying to mutate?
• Are there any JSON syntax errors in your mutation?
• Are there any recent workflow logs giving more details about why a mutation isn't working?

If you're trying to conditionally apply a mutation using liquid if statements, you could try adding something outside of the if statement to check, for example:

[
    ...
    {
        "op": "add",
        "path": "/state/debug",
        "value": "Something useful e.g. {{ updateContext.myProperty }}"
    },
]