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; use event.preview to detect preview mode, in which the task is responsible for rendering illustrative example actions (see Preview actions)
• options – Contains merchant-configured values for the task (see Task options)
• cache – Allows you to access values that you've stored in your keyval cache (see The "cache" action)
• shop – Describes the current Shopify store (see The shop object)
• ... and, for all events in the "shopify/" domain, a variable named after the event subject; for example, "shopify/orders/create" events will automatically be given an automatic order variable, containing order data from the current event

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 REST 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, but occasionally there will be a surprise: in the REST API, for example, tags are delivered as a comma-delimited string, not as an array.

For an example, compare the storefront customer object with the customer REST API response. For more general comparisons, compare Shopify's webhook reference and admin REST API reference.

Examples

The best source of example scripts is our task library: see usemechanic.com/tasks, and github.com/lightward/mechanic-tasks.

We include the following examples to help get you started. :)

A static email task

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 %}

Logging customer activity via email

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 %}

Sending emails for each order line item

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 %}