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: the same shape each time.

Where to find it

Architect Panel → ERP - Setup:

• Documents — the console — work with actual documents
• Document Types — declare a type and point it at a binding
• Document Conversion Map — which field becomes which when one type becomes another

Architect Panel → Data:

• Record Numbering — the number scheme that allocates references

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.

So adopting documents requires migrating nothing — an existing orders datastore can be declared a document type and carry on holding exactly the same rows.

Defining one

Each type carries a name, its binding, and its direction — sales-side or purchase-side. 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 type with a number scheme so references are allocated rather than typed. A predictable sequence per type per entity is what auditors expect, and it removes an entire category of duplicate-reference problems.

Choosing your types

Declare a type per genuinely different lifecycle, not per layout variation.

A pro-forma following exactly the same path as a normal invoice is a flag on the invoice, not a separate type. Two types sharing a status list and a conversion map are usually one type wearing two hats — and every extra type multiplies the transitions and maps you have to maintain.

Worked example

A distributor declares four types: Quotation, Sales Order, Despatch Note and Sales Invoice, all sales-side, each over its own header and lines datastores which already existed. Each gets a number scheme. Credit Note is a fifth type because its lifecycle genuinely differs — it can only be raised against an invoice.

Recommendations

• One type per lifecycle, not per layout.
• Always pair with a number scheme.
• Set direction deliberately — it drives the sign of everything downstream.
• Declare existing datastores as types rather than building new ones.

Status Transitions

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

Where to find it

The transition list belongs to a document type, so start at Architect Panel → ERP - Setup → Document Types. The transitions themselves are held in a datastore of their own; where your panel does not surface it directly, open the document status list from All Datastores.

Why transitions rather than statuses

The difference shows the first time somebody tries to reopen a posted invoice. With a list of statuses nothing prevents it — the field accepts a new value and a document that has already hit the ledger 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 type, the from status and the to status. A 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. That absence is the whole point.

Terminal statuses

A status with no outbound transitions is terminal. Posted and cancelled usually are, or nearly so.

Be deliberate: a terminal status is a promise the document will not change again, which is what makes it safe for the ledger and for reporting to depend on.

Who may make a move

Transitions govern what is structurally possible, not who is allowed. Combine them with security groups and field-level permissions so approving a document is both a legal move and a restricted one.

Worked example

A purchase order allows: draft → submitted, submitted → approved, submitted → draft (rejected back for amendment), approved → sent, sent → received, sent → cancelled. There is no route from received to anything, because a received order is history. Approval is additionally restricted to the buying manager group.

Designing it

Start with the smallest set that reflects reality. 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 the better answer.

Recommendations

• Draw it on paper first. Five statuses is usually plenty.
• Leave the dangerous move out rather than restricting it by permission — absence is stronger.
• Make posted terminal wherever the ledger depends on it.
• Review the list when somebody asks for a new status; often they want a flag.

Converting Documents

Conversion is how one document becomes the next. The engine copies it forward according to a map you define, and records where every line came from.

Where to find it

Architect Panel → ERP - Setup:

• Document Conversion Map — which slot on the source populates which on the target
• Documents — the console where conversion is performed

The field map

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

Line-level provenance

This is what distinguishes a real document flow from copying records.

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 and per quantity, which makes these 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 is normal

Because provenance is per line and quantity, converting part of a document is ordinary 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 rather than stored in a column that could drift — so it cannot disagree with the despatches.

Converting is not copying

The new document has its own lifecycle. Editing an order after despatch does not retrospectively change what was despatched, and should not: if a customer queries a figure, the despatch note says what left the building on the day it left.

Worked example

An order for 100 units is despatched 60 then 40. The first despatch is invoiced immediately; the second is invoiced with another order on one consolidated invoice. Every line on both invoices links back to the despatch line and through it to the order line, so the order shows nothing outstanding and the customer's query about the consolidated invoice is answered by following the links.

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.

Recommendations

• Map deliberately. Anything unmapped is a decision, so make it consciously.
• Never recalculate outstanding quantities into a column — derive them from the links.
• Enable auditing on both datastores before the first conversion.
• Test a partial conversion before go-live; it is where mapping errors surface.