Async work
Anything that happens because of a request but not during it goes through a queue. When an order has not reached the ERP, or a new user never got their invitation, this is where to look.
What goes through the queue
Six kinds of work. If a symptom involves something happening late or not at all, it is almost certainly one of these.
| Work | Triggered by |
|---|---|
| Post an order to the ERP | Placing an order |
| Send the order acknowledgement | Placing an order |
| Provision a new user | A user being created or linked |
| Provision a customer administrator | An integration push carrying an admin |
| Re-send an invitation | An invite being reissued |
| Notify a user added to a customer | A user gaining access to a customer |
Placing an order raises two separate items, not one. The ERP post and the acknowledgement email fail and retry independently, so one succeeding tells you nothing about the other. Always check for both.
How to read a queue item
The queue screen lists items with a status, filters by date, status and type, and searches by id, type, group key or payload content — so a customer number or order number in the payload is findable.
| What you see | What it means |
|---|---|
| Queued time | When the work was created. This is when the business event happened |
| Min dequeue time | The earliest it may next be attempted. If this is in the future, it is waiting, not stuck |
| Dequeued time | When it was last picked up |
| Retry count | How many attempts have failed. A climbing count means a persistent failure, not a blip |
| Type | Which handler will process it |
| Group key | Groups related items |
| Payload | The event as JSON. Contains the identifiers you need |
The distinction that matters most
Waiting is not failing. A failed attempt pushes min dequeue time further out each retry, so an
item with three retries and a dequeue time twenty minutes away is behaving exactly as designed. It will
try again.
Escalate when the retry count keeps climbing — that is a failure that will not resolve itself, because the same input will fail the same way.
Retrying an item
The queue screen can release an item, which sets its next attempt to now so the drain picks it up immediately.
Important
Release does not work on a completed item. It is refused. Release is "try again sooner", not "run it again" — there is no way to re-run finished work from the screen.
If completed work needs to happen again, the business event has to be raised again, which is a developer task rather than a support one.
Releasing is safe to do more than once. Handlers are written to be re-runnable, because the queue may redeliver on its own — provisioning creates-or-links rather than creating blindly, the email sender checks its log, and the ERP post is keyed by order number.
When nothing is draining at all
If every item is sitting unattempted rather than one item failing, the problem is the drain, not the work.
The background task screen lists the engines and lets you run one on demand. That distinguishes the two cases quickly:
- Runs on demand and succeeds → the engine is fine, its schedule or the host is not
- Runs on demand and fails → the failure is in the work, and the error will tell you which
Why an order cannot be lost between Commerce and the ERP
Worth knowing when someone asks whether an order might have vanished.
The queue row is written in the same database transaction as the order itself. Either both were saved or neither was. There is no window in which an order exists and the instruction to send it does not.
So if a customer has an order number, the instruction to post it exists. It is queued, retrying, or complete — never missing. That narrows the question to why it has not succeeded yet, which the retry count and the handler's error will answer.