Task scripts

Mechanic turns Liquid from a templating language, into a programming language.

Each task script is expected to render a stream of JSON objects that can be used to generate actions. Put another way, your script should render a series of JSON objects, one right after the other, separated by nothing other than whitespace.

For more information about actions, see An introduction to actions.

Your Liquid code always has access to these standard variables:

• event  – Represents the incoming event. Use event.topic  to get the current event topic, and event.data  to get the event's payload. (Find samples of these payloads in the Shopify docs.) And, super importantly, use event.preview  to determine if Mechanic is running your script for the purpose of showing the merchant what the script can do.
• options  – Contains merchant-configured values for the task. For more information on generating the task configuration form, and thereby populating this variable, see Task options.
• cache  – Allows you to access values that you've stored in your keyval cache – see The "cache" action.

There are also additional variables for things like the current shop, and objects that related to the event that your task is processing.

For more information about Liquid, see An introduction to Liquid at Mechanic.

Take note! If you're used to writing Shopify templates in Liquid, remember that Mechanic uses Shopify's Admin API representation for these objects, not the storefront Liquid representation! This usually means that you'll have access to more data than you would in a storefront template.

For an example, compare the storefront customer object with the customer API response.

For more general comparisons, compare Shopify's webhook reference and admin API reference.

Examples

The best source of example scripts is our task library: usemechanic.com/tasks. We include the following examples to help get you started. :)

Simple

This script doesn't change its results based on the event – it sends the same email every time. It uses the "action" tag to render a JSON object that defines an "email" action.

{% action "email" %}
  {
    "to": "hello@example.com",
    "subject": "Hello world",
    "body": "It's a mighty fine day!"
  }
{% endaction %}

Moderate

Subscriptions:

shopify/customers/create
shopify/customers/update
shopify/customers/delete

This script sends an email offering a heads-up that a customer has been created, or updated, or deleted.

{% capture email_body %}
Customer attributes:

{{ customer | json }}
{% endcapture %}

{% action "email" %}
  {
    "to": "customers@example.com",
    "subject": "Customer {{ customer.email }} was {{ event.topic }}d",
    "body": {{ email_body | json }}
  }
{% endaction %}

Advanced

Subscriptions:

shopify/orders/create

This script loops through every line item in the order, and – for every line item having a SKU – emails the appropriate team about that line item. This script could generate zero, one, or a hundred emails!

{% assign teams_to_email = "" %}

{% for line_item in order.line_items %}
  {% if line_item.sku == blank %}{% continue %}{% endif %}

  {% assign team = line_item.sku | split: "-" | last %}

  {% capture subject %}New order for a {{ team }} product{% endcapture %}

  {% action "email" %}
    {
      "to": "{{ team }}@example.com",
      "subject": {{ subject | json }},
      "body": {{ line_item | json | json }}
    }
  {% endaction %}
{% endfor %}