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", // "/name", "/description", "/state/{key}", "/state", "/assigneeId", "/assigneeType", "/activityContext/status"
        "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.

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. {% raw  %}{{ updateContext.myProperty }}{% endraw  %}"
    },
]