An introduction to runs
Everything has a run
The work that Mechanic does is split into three classes: events, tasks, and actions. When each of these three classes are made ready to be performed, we call this a run. A run has a start time, an end time, a status, and a result.
A normal flow in Mechanic looks like this:
- An event is created – possibly by a Shopify webhook, or by a user webhook, by the Mechanic scheduler, or by an "event" action.
- An event run is created, and performed. During this phase, Mechanic scans the store's tasks to see which ones are relevant for the current event, by checking the subscriptions on file for each task. For each task that Mechanic discovers for the event, a task run is created. (If the task subscription involved a delay, as in "mechanic/scheduler/daily+2.hours", the task run will be set to wait for that amount of time.) The result of the event run is this set of task runs.
- Each task run is performed. During this phase, Mechanic takes each task's Liquid script, and evaluates it using the associated event. The result of the task run is the set of JSON action objects rendered by the task's Liquid script. Each action object is used to create an action run.
- Each action run is performed. During this phase, Mechanic executes each action, given the options that were provided for it by the task run's result.
Understanding this sequence of events is important. Task runs do not come into existence until the event run has been performed, and the effects of an action run do not take effect until they've had an opportunity to be performed.
Importantly, this means that task scripts do not have access to the effects of the actions they generate. Actions are performed later in the sequence, and their effects will only be seen by subsequent task runs.
Runs are asynchronous
Mechanic's backend uses a run scheduler, which monitors each account's run queue, and sends due runs to our worker pool, where each run is performed.
Once created, runs generally do not have a guaranteed order. This means the order that actions appear in a task run result is not indicative of the order in which the actions will be performed, unless the task is configured for action run sequences (see Generating sequences of actions).
Runs are retryable
Runs are automatically retried when a non-permanent error is encountered. For "http" actions, this might be a connection error. For "email" actions, this might be a temporary outage with our email provider. Mechanic will automatically retry these runs up to 4 times, for a total of 5 attempts. Retries are subject to a variable backoff delay, of approximately 0:30, 1:16, 2:32, and 5:08 respectively, for each of the 4 retries.
Some task runs may be manually retried, via the Mechanic user interface. Task runs, for example, may be manually retried if they did not generate any actions. (This means that you may set up a task to generate only "log" objects, and be able to retry each run freely.) All action runs that encountered an error may be manually retried.