How document workflow works
The engine behind the journal-wrapper and inventory-adjustment endpoints. It stages what the API accepts, then routes it to the ledger according to each endpoint's configured mode, so posting stays fast and reviewable.
When the API accepts a payment, refund, credit memo, invoice, expense, or inventory adjustment, it does not post immediately. It writes a staged document and returns. What happens next is decided by that endpoint's processing mode, not by the API call. This keeps the API response fast, keeps posting out of the request path, and lets a person review anything you do not trust to flow through automatically.
The pipeline
A document can also park on the way through: waiting for lines the header declared but has not received, waiting for an invoice it references to post, or stopped in error. Those statuses and the way out of each are listed under Operating staged documents.
Stages explained
- Staged document. The transaction lands in a staging table with a status. It is fully visible and (depending on the endpoint) editable in the Business Central client before it posts. See Operating staged documents.
- Manual endpoints stop here until a clerk runs Process. Auto Draft and Auto Post endpoints are picked up by a background job.
- Approval gate. If the endpoint requires approval, only approved documents advance; the job skips the rest and the manual Process action is rejected until approval. Approval runs through Business Central's standard approval workflow. A licensed user sends the document for approval and an approver approves it in the client; the API cannot approve. See Operating staged documents.
- To the ledger. Processing writes the document through the standard posting engine using the endpoint's journal template and batch, so it inherits Business Central's normal validation, source codes, and number series. Auto Draft leaves the lines unposted for a person to post; Auto Post posts them.
- Writeback. Once posted, the document's status is updated and, if posted-document events are enabled, a realtime trigger fires so the integration can record the Business Central document number and posting date.
Why staging instead of posting inline
- Speed: the API returns without waiting on posting or its locks.
- Review: a document you are not ready to trust can sit as a draft, or wait for approval, before it affects the ledger.
- Resilience: if an imported document references an invoice that has not posted yet, it can wait (Awaiting Invoice) and apply itself automatically once the invoice posts, rather than failing the import.
Staging tables are not a queue
The staging tables are persisted Business Central data: real records with a status, not a transient queue. That is deliberate: a staged document is an auditable record a person can inspect, edit, approve, or archive.
This is worth stating because the extension has a second kind of intermediate storage that behaves the opposite way. The availability snapshot is fed by a transient buffer: a work queue that drains itself and that nobody edits.
| Document-workflow staging tables | Availability buffer | |
|---|---|---|
| Holds | Imported payments, refunds, credit memos, invoices, expenses, inventory adjustments | (item, location) keys that need their availability recomputed |
| Nature | Persisted, auditable documents | Transient work queue |
| Lifetime | A document lives until it is processed and (optionally) archived | A row lives only until the refresh job drains it |
| Who touches it | A clerk can review, edit, approve, process, or archive it | Nobody: it is internal plumbing |
| If it grows | Normal: documents await review or approval | The refresh job is falling behind |
Next: Operating staged documents. The clerk's side of this pipeline in the Business Central client.