Transactional Documents

Document Types

A document type declares that a pair of your datastores — a header and its lines — behaves as a transactional document. Sales invoice, purchase order, quotation, despatch note, credit note, timesheet: all the same shape.

The engine owns no data

A document type stores no records of its own. It points at a binding whose header and line roles name your datastores. Your invoice table stays your invoice table, with your columns; the document type adds lifecycle, conversion and traceability on top.

The practical consequence is that adopting documents does not require migrating anything. An existing orders datastore can be declared a document type and carry on holding the same rows.

Defining one

Each type carries a name, its binding, and its direction — whether it is a sales-side or purchase-side document. Direction matters because it determines the sign of any stock movement or ledger posting the document produces: a despatch takes stock out, a goods receipt puts it in.

Numbering

Pair each document type with a number scheme so references are allocated rather than typed. A gapless, predictable sequence per document type per entity is what auditors expect, and it removes an entire category of duplicate-reference problems.

Choosing your types

Declare a type for each document that has a genuinely different lifecycle, not for each variation in layout. A pro-forma invoice that follows exactly the same path as a normal invoice is a flag on the invoice, not a separate type. Two types that share a status list and a conversion map are usually one type wearing two hats.

What comes next

A document type on its own gives you a labelled pair of datastores. The value arrives with the two things built on it: an enforced status lifecycle, and conversion between types.

Status Transitions

Most systems store a status as a value in a dropdown and hope nothing sets it to something silly. Documents here define the lifecycle as a set of permitted transitions instead — from this status, to that status — and anything not declared cannot happen.

Why transitions rather than statuses

The difference matters the first time somebody tries to reopen a posted invoice. With a list of statuses, nothing prevents it; the field simply accepts a new value, and a document that has already hit the ledger quietly returns to draft. With transitions, "a posted invoice cannot return to draft" is an enforced property of the system rather than a rule people are asked to remember.

It also documents itself. Reading the transition list tells you exactly what can happen to a document and in what order, which is the question a new administrator, an auditor or your future self will ask.

Defining a lifecycle

Add one row per permitted move, naming the document type, the status it moves from and the status it moves to. A typical sales invoice might allow draft to approved, approved to posted, approved back to draft, and posted to cancelled — and nothing else. Note what is absent: there is no route from posted back to draft, and that absence is the whole point.

Terminal statuses

A status with no outbound transitions is terminal. Cancelled and posted are usually terminal or nearly so. Be deliberate about this — a terminal status is a promise that the document will not change again, which is what makes it safe for the ledger and for reporting to rely on.

Who may make a move

Transitions are about what is structurally possible, not about who is allowed. Combine them with security groups and field-level permissions so that approving a document is both a legal move and a move only certain people can make.

Designing the lifecycle

Start with the smallest set that reflects reality, and resist adding a status for every internal nuance. Every status multiplies the transitions you must think about, and a lifecycle nobody can hold in their head will be worked around. If a status exists only so somebody can filter a list, a flag or a date column is usually the better answer.

Converting Documents

Conversion is how one document becomes the next: quote to order, order to despatch, despatch to invoice. The engine copies the document forward according to a field map you define, and records where every line came from.

The field map

A conversion map says which slot on the source document populates which slot on the target. Most of it is obvious — customer, dates, currency, line item, quantity — but you decide, so a field that should not carry forward simply is not mapped. Internal notes on a quote need not appear on the customer's invoice.

Line-level provenance

This is the part that distinguishes a real document flow from copying records. The platform already links records to one another at row level, but fulfilment is rarely a whole-document affair. Order line 10 of 100 is despatched today, 40 next week, and the whole thing is invoiced across three invoices.

Conversion therefore records provenance per line: this invoice line came from that despatch line, which came from that order line, for this quantity. That is what makes the following answerable without a spreadsheet:

• How much of this order is still outstanding?
• Which invoices covered this despatch?
• Has this line been invoiced twice?

Partial conversion

Because provenance is per line and per quantity, converting part of a document is normal rather than a special case. Despatch what you have, and the order retains an outstanding balance that the next despatch draws down. The remaining quantity is derived from the links, not stored in a column that could drift.

Converting is not copying

The new document is a document in its own right, with its own lifecycle. Editing an order after despatch does not retrospectively change what was despatched — and it should not. If a customer queries a figure, the despatch note says what left the building on the day it left, regardless of what happened to the order afterwards.

Auditing

Turn auditing on for both header and line datastores. Between the audit trail and the provenance links you can reconstruct not only what a document says now, but what it said at every stage and what it was derived from.