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 eleven 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. On the main job queue, which carries the journal and the stock jobs, a worker claims a row by deleting it as it reads it. If the handler then 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 replays that row. Two watchdogs can queue the work afresh instead. The cashbook posting has its own queue and failure table, and its watchdog is a default job, run every fifteen minutes: once a finalised document has sat twenty minutes with a payment line but no cashbook line, it queues the posting again, until four failures pile up within a day. A stock watchdog re-queues unposted stock twenty minutes after the document’s date, with no limit on failures, but only where your tenant has it scheduled.
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 rows still waiting in the queue, in priority order across the kinds of job it sweeps, and calls the job endpoint once for each row; each call takes one job of that row’s kind. So a job still waiting in the queue survives a restart. What the sweeper cannot do is retry something that already ran and failed, or pick up a job a worker had already claimed when it stopped, because that row is not there any more. Nor can it find a job whose row was never written.
Step 3 — Know that a backlog is a real, measurable state
After this step you will recognise a third possibility. Finalising a document queues its first job and asks for that kind of job to run at once, without waiting for the tick; an older job of that kind can go first. But whatever is left waiting for the tick is picked up about ten jobs at a time on the main queue, shared across every kind of job the tick sweeps, and one busy kind can take all ten while a quiet one waits behind it. A tenant that leaves work waiting faster than that accumulates a queue, so a busy stretch can leave inventory work sitting in the queue table. Usually nothing has failed and the work is simply behind, though where a stock watchdog runs, a waiting stock job may be a retry. When the work is only behind, stock balances and costs on those lines are correct-but-not-yet, the hardest state to explain.
Step 4 — Know which failures to expect, and why
After this step you will stop treating a failed posting as exotic. A job that fails after Finalise is an ordinary event with an ordinary cause. The causes to check first 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 on a document whose customer has no AR/AP type. Each is thrown by the job, after Finalise has already succeeded. Where the customer has one, that last fault throws nothing: the line is dropped and trade debtors absorbs it.
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 under Error Checking. Missing Journal never shows the job; it asks only whether a journal exists, so a job still waiting, one that failed and one never queued look the same. Press Resolve: if the cause is still there, it posts nothing and its message names the reason, often a missing default GL code; fix that and press it again. If it reads Unsupported document type, post a consignment receipt, return or billing from the Stock Flow Report’s difference listing; for other types, ask BigLedger support. Once the mapping is fixed, Repost beside Posting Journal rebuilds a short journal. It shows only on a listed type, already posted, in ringgit and not a copy; it deletes the old journal first and is silent on failure: check the journals. A foreign-currency document posts through its ringgit copy where your tenant makes one: look there.
Reference: Financial Report — Error Checking
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: I voided the document and the report still shows it: 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.
Answer key
- It was already deleted when the job was claimed; only an error row remains — What actually happens when I press Finalise? How work actually runs — Synchronous or asynchronous — who pays the wait
- A job that was queued and never attempted, for instance after a restart — What actually happens when I press Finalise? How work actually runs — Trace it once: what one Finalise actually starts
- Map the account, then press Resolve again — Sales Invoice (Internal) — Troubleshooting
- An editable document to correct and finalise again — I voided the document and the report still shows it: what a void undoes