A workflow is one rule: when a trigger fires, check these conditions, and if they’re true, run these actions. Create workflows on the Order Workflows tab.
Workflow settings#
| Setting | Details |
|---|---|
| Name | Required, 254 characters or fewer, and unique. Workflows have no separate code; the name identifies the workflow in provisioning and the admin. |
| Enabled | Only enabled workflows run when their triggers fire. New workflows are enabled by default. |
| Wait Until True | Keep re-checking the conditions after the trigger, instead of giving up when they’re false. See Wait Until True. |
| Interval and Maximum | Used with Wait Until True. Both are in minutes. |
| Triggers | One or more events that start the workflow. See Triggers. |
| Conditions | Optional. With no conditions the actions always run. See Conditions. |
| Actions | One or more actions, run in the order listed. See Actions. |
How workflows run#
When an event happens to an order:
- Miva loads every enabled workflow that has that trigger, in the order the workflows were created.
- For each one, it checks the conditions against the order.
- If they’re true, it runs the actions in order. After any action that changes the order (a queue change, note, custom field or payment), the order data is reloaded, so the next action and the next workflow see the change. A webhook sent after a queue action carries the updated queue flags.
- If an action fails, the rest of that workflow’s actions are skipped. Other workflows for the same event still run. The failure isn’t shown anywhere in the admin, so test new workflows on a sample order.
Workflows run every time a trigger fires. Nothing limits a workflow to once per order: an order whose total changes three times runs an Order Total Change workflow three times. Write conditions and actions so repeats are harmless. For example, Add to Queue does nothing if the order is already in the queue, while Add Note adds a note each time. To run a workflow once, have it set a custom field and add a condition that the field is empty.
Wait Until True#
Many events happen before an order is ready. When an admin user clicks New Order, the Order Created trigger fires right away, before the order has items, a shipping method or a payment. Wait Until True handles this.
With Wait Until True on:
- When the trigger fires, the conditions are checked right away. If they’re true, the actions run immediately.
- If they’re false, the order goes into the workflow’s wait queue. Every Interval minutes, Miva checks the conditions again.
- As soon as they’re true, the actions run and the order leaves the wait queue.
- If the conditions are still false after Maximum minutes from the first check, the order leaves the wait queue and the actions never run. Nothing is logged when this happens.
The admin suggests an interval of 5 minutes and a maximum of 60 for new workflows. There’s no upper limit, but a long maximum on a busy store keeps a lot of orders in the wait queue.
Things to know:
- Scheduled task. The re-checks are done by the scheduled task Process Order Workflow Wait Queue, which the module installs enabled, running every minute. If that task is disabled, orders stay in the wait queue and Wait Until True workflows never finish. An interval shorter than a minute effectively becomes a minute.
- One wait per order and workflow. If the same trigger fires again while the order is already waiting for that workflow, it doesn’t start a second wait or reset the clock.
- Trigger data isn’t available on re-checks. Some triggers add extra values, such as
original_status(see the table below). Those exist only when the trigger first fires. A condition that uses them can match immediately but never on a re-check. - Disabling doesn’t stop waiting orders. Orders already in the wait queue keep being checked, and can still run the actions, after the workflow is disabled. Deleting the workflow clears its wait queue.
- Failed actions on a re-check are written to the scheduled task log as warnings, and the order leaves the wait queue without a retry.
Triggers#
A workflow needs at least one trigger. Some triggers add extra values to the data that conditions can test, alongside order.
| Trigger | Code | Fires when | Extra values |
|---|---|---|---|
| Order Retrieved | order_retrieved |
An order is returned by QueueOrderList_Load_Query. It fires for each order in the response, after the response is sent. |
|
| Order Acknowledged | order_acknowledged |
An order ID is sent to OrderList_Acknowledge. |
|
| Order Created | order_created |
An order is created, whether by a shopper at checkout, in the admin or by a subscription. | |
| Order Status Change | order_status_change |
The order status changes. | original_status |
| Order Total Change | order_total_change |
The order total changes. | original_total |
| Order Shipment Created | ordershipment_created |
A shipment is created. | created_ordershipment |
| Order Shipment Deleted | ordershipment_deleted |
A shipment is deleted. | deleted_ordershipment |
| Order Shipment Status Change | ordershipment_status_change |
One or more shipments change status, for example from picking to shipped. | updated_ordershipments (each with its new values, original_ values, and orderitems), updated_ordershipment_count |
| Order Item Created | orderitem_created |
An item is added to the order. | created_orderitem |
| Order Item Updated | orderitem_updated |
An item’s price, attributes, quantity or other details change. | |
| Order Item Status Change | orderitem_status_change |
One or more items change status. | updated_orderitems (each with its new values, original_ values and options), updated_orderitem_count |
| Order Item Deleted | orderitem_deleted |
One or more items are deleted. | deleted_orderitems, deleted_orderitem_count |
| Order Return Created | orderreturn_created |
A return (RMA) is created. | created_orderreturn |
| Order Return Deleted | orderreturn_deleted |
A return is deleted. | deleted_orderreturn |
| Order Return Status Change | orderreturn_status_change |
One or more returns change status. | updated_orderreturns (each with its new values, original_ values and orderitems), updated_orderreturn_count |
There are no triggers for an order being deleted or moved to a different batch.
The admin’s field picker only offers order: paths. To use an extra value, type its path into the condition, for example original_status or updated_orderitems[1]:status.