User Form

Create custom input forms for manually-triggered Mechanic tasks — collect user input and pass it to your task code.

When a task subscribes to the mechanic/user/form event topic a "Run task" button is added to the task.

When the Run Task button is clicked the user is presented with a form that contains any task options that have the _userform flag.

Form fields intentionally start blank: the form collects ad-hoc input for a single run, while the values saved on the task's options remain the task's configuration for its other subscriptions. Your task code decides what blank input means — a common pattern is falling back to the saved option value:

{% assign recipients = input.email_recipients | default: options.email_recipients__array__userform %}

Submitting the form never changes the task's saved options.

When submitted, an event is generated, to which only this task will respond. The user's input is available in Liquid as input.<name>.

User form on Run Task page

Click the link button beside the title of the form to copy a link to the form that you can share with your users

Where User Form fields appear

User Form fields show up in:

• The task-level Run Task button for mechanic/user/form.

• The Run tasks page for Shopify admin action links (and equivalent run links) when exactly one task is selected.

See Shopify admin action links and Run links for details.

Getting the user’s input in code

During a mechanic/user/form event, ad-hoc values are available as input.<name>. event.data also contains these values for backward compatibility.

{% # These will appear on the run task user form %}
{% assign big_event = options.the_big_event__date_userform %}
{% assign color_for_big_event = options.color_for_big_event__color_required_userform %}

{% # This will NOT appear on the run task user form %}
{% assign level = options.level__select_o1_low_o2_high %}

{% if event.topic == "mechanic/user/form" %}
  {% # we need to get the value from user input, we don't want the value from the task option %}
  {% assign big_event = input.the_big_event %}
  {% assign color_for_big_event = input.color_for_big_event %}

{% endif %}

{% action "echo" big_event, level, color_for_big_event %}

Note: event.data contains submitted values for backward compatibility. Prefer input.<name> going forward, and use options.* for stored task options.

User form options also appear on the Run tasks page for Shopify admin action links (mechanic/user/{resource} topics). In that context, input.<name> is still the recommended way to access user input.