# 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](https://eonesolutions.github.io/eone-bc-integration/endpoint-setup.md), 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

```mermaid
flowchart LR
    A[API POST accepted] --> B[Staged document, status Open]
    B --> G{Approval required?}
    G -->|Yes| P[A person approves it in the client]
    G -->|No| C{Processing mode}
    P --> C
    C -->|Manual| D[A clerk runs Process]
    C -->|Auto Draft| E[Job writes unposted lines, then a clerk posts the batch]
    C -->|Auto Post| F[Job writes the lines and posts them]
    D --> J[Posted to the ledger, status written back, event fires]
    E --> J
    F --> J
```

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](https://eonesolutions.github.io/eone-bc-integration/operating-staged-documents.md).

## 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](https://eonesolutions.github.io/eone-bc-integration/operating-staged-documents.md).
- **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](https://eonesolutions.github.io/eone-bc-integration/operating-staged-documents.md).
- **To the ledger.** Processing writes the document through the standard posting engine using the endpoint's [journal template and batch](https://eonesolutions.github.io/eone-bc-integration/endpoint-setup.md), 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](https://eonesolutions.github.io/eone-bc-integration/realtime.md) 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](https://eonesolutions.github.io/eone-bc-integration/availability-snapshot.md) 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 |

> **Tip:** Rule of thumb: if you can open it on a page and act on it, it is a staging table. If it is invisible plumbing that drains itself, it is the buffer.

**Next:** [Operating staged documents](https://eonesolutions.github.io/eone-bc-integration/operating-staged-documents.md). The clerk's side of this pipeline in the Business Central client.