Options
Last updated
Was this helpful?
Last updated
Was this helpful?
accept user configuration via options. Options are created dynamically, by reference: each option referenced in a task's 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 , by rendering error objects according to the task's its own validation logic.
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
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.
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.
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.
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.).
(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
Use ordinal tokens to define values:
Ordinals (o1, o2, …) determine display order. Underscores inside values are preserved.
min<number> – required
max<number> – required
step<number> – optional (defaults to 1).
Append _array for multi‑select.
Unsupported resources are rejected during validation.
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).
futureonly
date, datetime
Picker disallows past dates.
Required fields must not be empty.
Range sliders need both min and max.
Pickers only allow product, variant, or collection.
Email inputs are matched against a basic regex.
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.
Text input
options.subject__required
"Welcome!"
Email input
options.reply_to__email_required
"person@example.com"
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"
Getting a plain string (strip the offset)
Custom rules? Learn more about .
Liquid code in task options have access to the same set of that are made available to the task code, including event, shop, cache, and any event subject variables.