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. For each task that Mechanic discovers for the event, a task run is created. 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. The scheduler will send a maximum of 20 runs at a time to our worker pool, where each run has an opportunity to be performed.
Once created, runs 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.
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 continue to retry runs that encounter these errors, using a backoff algorithm to establish retry timing.
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.