A task's code is a Liquid template. In the same way that a Shopify storefront might use a Liquid template to receive requests and render HTML, a task uses its Liquid code to receive events, and render a series of JSON objects. These JSON objects define actions, logs, and errors.

Task code always has access to a set of environment variables, which can be used to make decisions about what JSON objects to render.

A task must purposefully consider its preview, so as to accurately communicate its intent to users and to the Mechanic platform.

A task's Liquid code always has access to a set of environment variables, defined by Mechanic.

{% unless event.preview %}
  {% assign customer = customer.reload %}
{% endunless %}

Event subject variables

When a task is actually invoked for an event, it may have access to an additional variable, determined by the specific event it is responding to. When this is the case, the additional variable will be named after the event subject, and its contents will be established by the event's data. The name of this variable is communicated by the Mechanic task editor, based on the task's current subscriptions.

For example, a subscription to shopify/customers/create will make available a variable called customer. A subscription to shopify/products/update will expose a variable called product, etc.

Shopify variables

All Shopify events support an additional variable named after the event topic. For example, when a task responds to a shopify/customers/create event, it will have access to an additional variable named customer, containing the customer data contained in the event.

Shopify events always contain data from Shopify's REST representation of each resource; therefore, automatic Shopify variables always contain data from the REST representation as well. The best resource for the data available for each variable type is Shopify's REST Admin API reference.

An action object defines work to be performed by an action, after the task is fully finished rendering. Action objects are most easily generated using the action tag.

An action object is a plain JSON object, having the following structure:

{
  "action": {
    "type": ACTION_TYPE,
    "options": ACTION_OPTIONS,
    "meta": ACTION_META
  }
}

Defining an action

Type

The action type is always a string, having a value that corresponds to a supported action (e.g. "shopify", or "http").

Options

Action options vary by action type. Depending on the action type, its options may be another complete object, or an array, or a scalar value.

Meta

Actions may optionally include meta information, annotating the action with any JSON value.

This information could be purely for record-keeping, making it easy to determine why an action was rendered, or to add helpful context:

{
  "action": {
    "type": "shopify",
    "options": [
      "post",
      "/admin/customers/1234567890/send_invite.json",
      {}
    ],
    "meta": {
      "invite_reason": "alpha",
      "customer_email": "customer@example.com"
    }
  }
}

Or, this information could be used to facilitate complex task flows, in concert with a subscription to mechanic/actions/perform (see Responding to action results). An action's meta information can supply followup task runs with information about state, allowing the task to cycle between different phases of operation.

{% if event.topic contains "trigger" %}
  {% action %}
    {
      "type": "cache",
      "options": ["set", "foo", "bar"],
      "meta": {
        "mode": "first"
      }
    }
  {% endaction %}
{% elsif action.meta.mode == "first" %}
  {% action %}
    {
      "type": "cache",
      "options": ["set", "foo", "bar"],
      "meta": {
        "mode": "second"
      }
    }
  {% endaction %}
{% elsif action.meta.mode == "second" %}
  {% action "echo", "done" %}
{% endif %}

When a task renders an error object, the task run will be marked as failed, and no rendered action runs will be performed. This is a good way to communicate an intentional failure to the user, when your Liquid code detects a certain condition.

A task that renders an error object during preview will interrupt the preview, and visibly communicate the error to the user. This makes error objects a useful way to validate task options.

An error object is a plain JSON object, having the following structure:

{
  "error": ERROR_DETAILS
}

The error details can be any JSON value. This value will be represented to the user as the reason for the task failing.

Error objects are most easily generated using the error tag.

Log objects are useful for recording information for later reference. They have no side-effects. Carefully chosen log objects can massively simplify post-hoc debugging, especially (as we've found) when investigating merchant bug reports.

A log object is a plain JSON object, having the following structure:

{
  "log": LOG_DETAILS
}

The log details can be any JSON value.

Log objects are most easily generated using the log tag.

Log objects appear wherever task run results are visible, including the task preview and when viewing an event.