When the chain does not run, and how you find out — transcript

Play this as a presentation — one slide per step, with the same narration. Every word of every step is on this page.

This lesson is for whoever at GadgetSphere is asked “the invoice is final, so where is the journal?” In about thirteen minutes you will know the three different things that sentence can mean, which table answers each, and the thirty-second check that tells them apart.

Step 1 — Know that a claimed job is gone from the queue

After this step you will know why “it will retry” is usually wrong. A worker claims a queue row by deleting it and taking the deleted row back in the same statement. The handler then runs on that data. If the handler throws, there is no row left to retry: the failure is written to a separate standard-error table, carrying the event code, the properties that name your document, and the message. Nothing re-drives it. The word to avoid here is “queued” — once a job has been attempted, it is no longer queued, whether it succeeded or not.

Reference: How Work Actually Runs — Trace it once: what one Finalise actually starts

Step 2 — Know what the sweeper does cover

After this step you will know why the design is still safe. The failure the queue does protect against is a job that was never attempted — a restart, a lost thread, a worker that went away. A background tick reads up to ten distinct event codes still sitting in the queue and calls the job endpoint once for each, and that endpoint takes one event per call. So nothing is lost simply because a process died. What the sweeper cannot do is retry something that already ran and failed, because that row is not there any more.

Reference: How Work Actually Runs — Trace it once: what one Finalise actually starts

Step 3 — Know that a backlog is a real, measurable state

After this step you will recognise a third possibility. Because the tick moves one job per event code, a tenant that produces work faster than that accumulates a queue. Measured across every tenant database, an unprocessed inventory backlog is sitting in the queue table on a handful of tenants, and one of them holds a very large one. For those documents nothing has failed and nothing is wrong with the configuration: the work is simply behind. Stock balances and costs on those lines are correct-but-not-yet, which is the hardest of the three states to explain to somebody looking at a report.

Reference: How Work Actually Runs — Trace it once: what one Finalise actually starts

Step 4 — Know which failures are common, and why

After this step you will stop treating a failed posting as exotic. Standard-error rows for the journal processor exist on more than half of all tenants, and for the inventory and cashbook processors on roughly a third. The commonest causes are mapping, not machinery: a receivable account that is not mapped in the company defaults, a settlement method with no cashbook or GL code, a sales or tax line that resolved no account and was dropped so the journal no longer balances. Every one of those is thrown by the job, after Finalise has already succeeded.

Reference: Sales Invoice (Internal) — Lifecycle and effects

Step 5 — Run the check, in this order

After this step you will have a routine that takes half a minute. Open Trace Document from the Error Checking screen for the document in question. If it shows a failed job with a message, that is your answer and Resolve will re-run it once you have fixed the mapping. If it shows nothing at all and the document is FINAL, the job was never queued — look at the fan-out: your tenant may not subscribe to that processor, your company may exclude it, or the fan-out itself may have thrown. If the document is in a foreign currency, no inventory line was ever going to exist.

Reference: Sales Invoice (Internal) — Troubleshooting

Step 6 — Know what VOID does, and what it cannot undo

After this step you will know the way back. Voiding a finalised document queues its own primary processor, which fans out to the void processors your tenant subscribes to: they reverse the journal, negate the stock ledger line and replay costing forward over every later movement, remove the cashbook line, unpick the contra and the knock-off, take the membership points back and reverse the tax. It is the same mechanism read backwards, with the same filters and the same silence when a subscriber is not enabled — and subscribing to a posting processor does not subscribe you to its void counterpart. What a void will not give you is an editable document. That is a different button, and it undoes far less than its name suggests.

Reference: What a Void Undoes

Check yourself

Three to five questions on what you just heard. Every correct answer links to the page that makes it correct, so you can check the source, not just the mark.

Back to the series · Play this as a presentation