Options

Tasks accept user configuration via options. Options are created dynamically, by reference: each option referenced in a task's code results in that option being added to the task's configuration form. In the option reference {{ options.foo_bar__required }}, the option key is foo_bar__required. The appearance and behavior of the option's form element is based on flags in in the option key – in this example, only the "required" flag is in use.

Mechanic flags provide only limited option validation. A task may define custom validation, by rendering error objects according to the task's its own validation logic.

1. Keys

Options are made available in the options variable, which is a hash having key-value pairs for each option key and option value. The option key must only contain ASCII numbers, lowercase letters, and underscores. The option key is reformatted for use as the option name presented to the user – underscores are replaced by spaces, and the entire line is sentence-cased.

<name>[__<flag>[ _<flag> ... ]]
Part
Rules
Example

name

Lowercase letters, numbers, and underscores only.

send_after

flag

One or more tokens that customise the field (see below).

required, date, picker_product

Because option keys are registered via static analysis, options must each be referenced using a standard lookup (e.g. options.foobar) at least once.


2. Display Order

Options are displayed to the user in the order in which they are first referenced in the task code.

Because this may not result in a natural sequence, it can be useful to prefix task code with a comment block, explicitly referencing each option so as to force the overall order.

{% comment %}
  Option order:

  {{ options.api_key__required }}
  {{ options.mode__select_o1_test_o2_live }}
  {{ options.webhooks__array }}
{% endcomment %}

3. Flags

Option flags control how an option appears and behaves in a task's configuration form, and also control the type and format of the option value.

Many flags may be combined with other flags, for more nuanced control.

If no flags are used for an option, an option will be made available as a plain text field, and the option value will be a string.

The special userform flag does not change the input type or validation; it simply marks an option as one that should appear on the Run-task form (topic mechanic/user/form) in additions to the general task options screen.

Flags fall into three categories:

Category
Purpose

Input types

Choose a specific control and value type (date picker, slider, select list, …). Exactly one input‑type flag should be used.

Form modifiers

Fine‑tune how the control looks or validates (required, multiline, etc.).

Auxiliary flags

Extra behaviour for certain input types (future‑only dates, multi‑select choices, etc.).

3.1 Input‑type flags

Flag
UI control
Value returned
Key examples

(none - default)

Single‑line text

string

options.subject

multiline

Multiline text box

string

options.body__multiline

boolean

Checkbox

true/false

options.enabled__boolean

number

Numeric input (step=1)

number

options.count__number

code

Code‑formatted text area

string

options.script_snippet__code_multiline

keyval

Key → value repeater

hash

options.headers__keyval

array

Value repeater

array

options.tags__array

date

Calendar picker

"YYYY‑MM‑DD"

options.launch_date__date

datetime

Date+time picker

"YYYY‑MM‑DDTHH:MM"

options.send_at__datetime

time

Time‑only picker

"HH:MM"

options.quiet_time__time

color

Hex colour picker

"#RRGGBB"

options.theme_color__color

range_minX_maxY_stepZ

Slider + number box

number

options.qty__range_min0_max100_step5

select

Single‑choice dropdown

string

options.plan__select_o1_basic_o2_pro

choice

Radio buttons

string

options.tier__choice_o1_gold_o2_silver

multiselect

Checkbox list

array[string]

options.channels__multiselect_o1_email_o2_sms

picker_<resource>

Shopify resource picker

gid string

options.product__picker_product

picker_<resource>_array

Multi‑select resource picker

array[gid]

options.products__picker_product_array

Array options have a hidden feature: once the user-configured array reaches 5 elements in size, a new "Manage in bulk" button will appear for that option. Clicking it will open a modal which allows the user to manage the array's input using a single multiline text field, in which each line represents an array element. This is a convenient way to configure larger arrays.

Choice/Select grammar

Use ordinal tokens to define values:

<name>__select_o1_basic_o2_pro_o3_enterprise
               │  │     │  │
               │  │     │  └───── value #2
               │  │     └──────── ordinal marker
               │  └──────────── value #1
               └─────────────── ordinal marker

Ordinals (o1, o2, …) determine display order. Underscores inside values are preserved.

Range grammar

  • min<number>required

  • max<number>required

  • step<number> – optional (defaults to 1).

Picker grammar

<name>__picker_<product|variant|collection>[_array]
  • Append _array for multi‑select.

  • Unsupported resources are rejected during validation.

3.2 Form‑modifier flags

Flag
Applies to
Effect

required

Any

Field must be filled before Save.

email

text

Adds email placeholder and basic email format check.

userform

Any

Shows this option on Run task form (mechanic/user/form).

3.3 Auxiliary flags

Flag
Works with
Effect

futureonly

date, datetime

Picker disallows past dates.


4. Built‑in validation

  1. Required fields must not be empty.

  2. Range sliders need both min and max.

  3. Pickers only allow product, variant, or collection.

  4. Email inputs are matched against a basic regex.

Custom rules? Learn more about custom validation.


5. Liquid

Options that allow text input are evaluated for Liquid when a task processes an event. Liquid evaluation for options occurs before it occurs for task code, which means that any Liquid variables created by task code are not available to task options.

Liquid code in task options have access to the same set of environment variables that are made available to the task code, including event, shop, cache, and any event subject variables.


6. Quick reference

Goal
Key snippet
Value example

Text input

options.subject__required

"Welcome!"

Email input

options.reply_to__email_required

Checkbox

options.newsletter__boolean

false

Key–value map

options.headers__keyval

{ "X-Env": "staging" }

String list

options.tags__array

["vip","wholesale"]

0–100 slider

options.score__range_min0_max100

42

Colour picker

options.bg__color

"#336699"

Dropdown

options.plan__select_o1_basic_o2_pro

"basic"

Multi‑select

options.channels__multiselect_o1_email_o2_sms

["email","sms"]

Product picker

options.promo__picker_product

"gid://shopify/Product/123"

Product list

options.products__picker_product_array

[ "gid://…/1", "gid://…/2" ]

Date

options.go_live__date_required

"2025-05-06"

Time

options.quiet_at__time

"00:25"

Datetime

options.party__datetime

"2031-04-22T15:13:00"

Working with date options

Getting a plain string (strip the offset)

{{ options.launch_date__date | date: "%Y-%m-%d" }}
   ⇒ 2025-05-06

{{ options.quiet_at__time  | date: "%H:%M" }}
   ⇒ 00:25

{{ options.party__datetime     | date: "%Y-%m-%d %H:%M" }}
   ⇒ 2031-04-22 15:13

Converting to another timezone

{{ options.party__datetime | date: tz: "UTC" }}
   ⇒ 2031-04-22T19:13:00Z       {offset shifted +4 h}

{{ options.quiet_at__time | date: "%H:%M %Z", tz: "America/Vancouver" }}
   ⇒ 21:25 PDT

Last updated

Was this helpful?