Transactional Documents

Document types over your own header and line datastores, an enforced status lifecycle, and conversion from quote to order to despatch to invoice.

Document Types

A document type declares that a pair of datastores, a header and its lines, behaves as a transactional document: it has a number, a lifecycle of permitted moves, conversions into other documents and postings to the ledger and stock. Nine document types now ship ready to use, covering buying and selling end to end.

Where to find it

Admin Panel → ERP - Setup:

ERP Documents — the Documents console: Types & health, Documents and Output & letterhead
Record Numbering — how each document type is numbered, per company

Architect Panel → ERP - Setup:

Documents — the same console for architects
Document Types — the types themselves, with the row actions Transitions and Posting
ERP Bindings — which datastores each type's header and lines live in

The shipped types

Buying: Purchase Requisition, Purchase Order, Goods Receipt and Supplier Invoice.
Selling: Sales Quote, Sales Order, Delivery Note, Sales Invoice and Sales Credit Note.

Each comes with its datastores, numbering, status transitions, conversion map and postings, and the Purchasing, Sales and Receivables consoles are built on them. The engine still reaches every table through a binding, so an installation can point a type at its own datastores instead; see Getting Started with ERP for bindings.

What a type holds

Key and Name: the short code (po, sinv) and the name people see.
Binding Key: the binding whose header and line roles name the datastores.
Direction: sale, purchase or internal. It decides the sign of stock movements and postings, and which price lists apply.
Numbering Scheme: the scheme key used to number new documents.
Default Status: where a new document starts, usually Draft.
Lock On Status: lines become read-only at this status. It is also the point from which the document can be e-mailed.
Posts To Ledger and Enabled.

Numbering

Each shipped type has a scheme with the format {PREFIX}-{ENTITY}-{PERIOD}-{SEQ}: the prefix (REQ, PO, GRN, PI, QT, SO, DN, INV, CRN), the company's code, the financial year and a five-digit sequence that starts again each financial year. Change it on Record Numbering, which shows a live example of the next number. A scheme for every company gives the group one sequence (each company still prints its own code); a company with its own scheme gets its own sequence. A type with no scheme creates documents with a blank number. See Record Numbering.

The Types & health tab

Every layer between a type and a posted journal is resolved by name at run time, so a mistake shows only when somebody posts a real invoice. The Types & health tab runs that check now, for each type:

Lifecycle: each transition with From, To, Label, Needs permission, Fires posting and Terminal.
Posting: each posting action with On, Engine, Verb, Resolves to and Available. An engine marked unavailable will fail the first posting.
Converts into: the types it can become, from the conversion map.

Documents keyed outside the consoles

A document created in the generic datastore editor or on its record screen is held to the engine's rules: it starts at the type's opening status with the next number from its scheme, a changed status or number is refused (use the document's own actions), totals are recalculated from the lines, the company and counterparty freeze once the lines lock, and a document cannot be deleted once it has moved on or anything was made from it.

What goes wrong

"No document types are enabled" on the console: define a type, or tick Enabled.
A posting engine shows as not available: the engine named is not installed; correct the posting row.
New documents have no number: the type's scheme key has no number scheme. Create it on Record Numbering, which lists missing engine schemes.

Worked example

A wholesaler using the shipped types wants its own invoice numbers to restart each calendar year with the prefix "S". On Record Numbering the ERP administrator opens the SINV scheme, changes the prefix to S and the reset to each year, and checks the live example. On Types & health they confirm every posting row for Sales Invoice resolves before the first invoice of the year is posted.

Recommendations

Use the shipped types unless you have a real reason not to; the consoles depend on them.
Run Types & health after any configuration change.
Decide numbering before go-live; changing format mid-year confuses auditors.
Never type statuses; move documents with their actions.

Status Transitions

A document's lifecycle is a list of permitted moves (from this status, to that status), not a free status field. A move that is not declared cannot happen. Each move can need a permission, ask for a reason, refuse the person who made the previous move, fire postings, or be made only by the engine itself.

Where to find it

Architect Panel → ERP - Setup:

Document Transitions — every move of every document type; filter by document type
Document Types — the Transitions row action opens one type's moves
Documents — the console: Types & health shows each lifecycle, and the Documents tab moves a document

Admin Panel → ERP - Setup:

ERP Documents — the same console for holders of ERP: Administration

What a move holds

Document Type, From and To.
Button Label: what the button says, for example "Issue to supplier". A bare verb such as "Cancel" is shown with its document ("Cancel order").
Requires Permission: the permission the user must hold. The shipped moves use the ERP role permissions (so holders of ERP: Receivables post invoices) and a few specific ones: Approve purchase requisitions, Issue purchase orders, Approve supplier invoices and Approve sales credit.
Locks Lines: the lines become read-only from this move.
Terminal: the document cannot move again.
Posting Trigger: the name the posting actions listen for, such as post, commit or reverse.
Not By The Requester: whoever moved the document into its current status may not make this move; a second person has to.
Needs A Reason: the move asks for a reason, which is kept on the document's history. Rejecting, declining credit, losing a quote and reversing a delivery all use it.
Automatic: a bookkeeping move the engine makes itself, such as a sales order becoming Delivered when its deliveries ship. It is never offered as a button and is refused if asked for.
Re-opens: an automatic move that reopens a finished document, such as a requisition going back to Approved when its only order is cancelled. It stops the finished status counting as open on work lists.

Guards and why a move is not offered

Besides the declared moves, posting actions can carry guards that refuse a move: the customer is on stop, a requisition line has no price, a credit note has no reason, the bill duplicates another, the order's receipts do not cover it. A move a guard would refuse is usually not offered at all, and the consoles list it under Why ... not offered with the reason. Guards are configured on Document Posting Actions; see Posting Actions and Guards in this section.

Approvals on a move

An approval matrix can be attached to a move: the shipped ones sit on a requisition's Submitted, a purchase order's Pending Approval and a sales order's Credit Hold, all switched off. When one is enabled, entering that status opens an approval run, and the approved status can only be reached when the run is approved. Requests appear in the approver's Approvals Inbox and, for purchase documents, in Purchasing → My approvals. When a document reaches a status it cannot leave, any open approval on it is withdrawn automatically. Approval matrices are described under How an Approval Matrix Runs.

Changing a lifecycle

Open Document Types and use the Transitions row action on the type.
Add or edit a row: From, To, Button Label, and the flags you need.
Open the Documents console's Types & health tab and check the lifecycle reads as you intended.
Try the move on a test document from the console's Documents tab (Move this document).

The shipped lifecycles of the nine document types are maintained by platform updates: an update can replace them. Prefer adding a move to editing a shipped one, and record any change you make.

What goes wrong

A button is missing for everyone: the permission it requires is held by nobody, or a guard refuses it. Check Why ... not offered.
"You moved this to ... yourself, so somebody else has to make this decision": the move has Not By The Requester. A second person must make it.
Somebody typed a status in the datastore: the change is refused. Statuses move only through the declared moves.

Worked example

The shipped purchase order lifecycle: Send for approval (Draft to Pending Approval), Issue to supplier (Draft or Pending Approval to Issued, needs Issue purchase orders, locks lines, fires commit), Part received and Fully received (driven by receipts), Close, Close short and Cancel. A company that wants every order over a value approved enables the Purchase order release matrix; nothing in the lifecycle itself has to change.

Recommendations

Leave the dangerous move out rather than restricting it by permission; absence is stronger.
Use Needs A Reason on every rejection, cancellation and reversal.
Use Not By The Requester wherever a second signature is the control.
Check Types & health after every change.

Converting Documents

Conversion is how one document becomes the next: a requisition becomes an order, an order a goods receipt, a receipt a bill; a quote becomes a sales order, an order a delivery, a delivery an invoice, an invoice a credit note. The engine copies fields forward according to a map, records where every line came from, and keeps the source document's status in step with what has been made from it.

Where to find it

Architect Panel → ERP - Setup:

Document Conversion Map — which field on the source fills which field on the target
Documents — the console's Documents tab, with Convert and each document's Fulfilment

Admin Panel → Purchasing:

Purchasing — the Create ... buttons on requisitions, orders and receipts

Admin Panel → Sales:

Sales — the Create ... buttons on quotes and orders

Admin Panel → Receivables:

Receivables — To invoice, and Create sales credit note on invoices

The shipped conversions

Buying: requisition to purchase order; purchase order to goods receipt or supplier invoice; goods receipt to supplier invoice.
Selling: quote to sales order; sales order to delivery note or (for services) sales invoice; delivery note to sales invoice; sales invoice to credit note.

Converting part of a document

Open the source document and press its Create ... button (on the Documents console, Convert).
The panel lists each line with what is still open. Enter how much to take; a line left at 0 stays open for later.
Confirm. The new document opens in its first status, with links from each of its lines back to the source line.

Because every line records where it came from and how much, the open quantity on the source is worked out from those links rather than stored in a column that could drift. The console's Fulfilment section shows it per line: ordered, what went into which document, and what is still open.

Rules the engine applies

The source must be ready: a requisition must be Approved to become an order; an order must be Issued (or later) to be received or billed; a sales order must be Confirmed or Partially Delivered to be delivered; an invoice must be Posted or Paid to be credited; a quote must be Sent or Accepted. Otherwise the button is not offered and the reason is given.
The source moves on by itself: a quote becomes Accepted, a requisition Ordered, a purchase order Receiving then Received, a sales order Partially Delivered, Delivered and Invoiced.
Cancelling hands quantities back: cancelling a draft receipt, bill, delivery or invoice releases its quantities to the source, and the source's status follows. A cancelled order sends its requisition back to Approved.
No double fulfilment: a sales order line can be invoiced once, whether through its delivery or straight from the order. The map's quantity policy Open across every route (no double fulfilment) enforces this.
The counterparty must be usable: a supplier on hold cannot be ordered from and a customer on stop cannot be delivered to.

The conversion map

Each row names From Type, To Type, Level (header or line), From Slot and To Slot, or a Constant instead of a source slot, and a Quantity Policy. Only what is mapped is copied: internal notes on a quote need not reach the customer's invoice, and a supplier's own reference on an order is not copied onto the bill. The shipped maps copy the counterparty, currency, terms, references, items, quantities, prices and coding.

Converting is not copying

The new document has its own lifecycle. Editing an order after a delivery does not change what was delivered, and a converted line keeps the price it was agreed at, so the invoice charges what the quote offered and commits the discounts actually given.

What goes wrong

"Nothing on this document is still open": everything has already been converted. Check Fulfilment.
The Create button is missing: the source is not at a status that allows it, or the counterparty is blocked; the reason is listed under Why ... not offered.
A field arrives empty on the new document: it is not in the conversion map. Add a row.

Worked example

An order for 100 units is delivered as 60 and then 40. The first delivery is invoiced at once; the second goes on a later invoice. Every invoice line links to its delivery line and through it to the order line, so the order shows nothing open and moves to Invoiced. When the customer queries a figure, the links answer which delivery and which order line it came from.

Recommendations

Map deliberately; anything unmapped is a decision.
Convert from the consoles, not by keying new documents, so the links exist.
Cancel rather than delete a draft made in error; cancelling releases its quantities.
Test a partial conversion after changing a map.

Posting Actions and Guards

Posting actions are what happens when a document moves: the ledger journal when an invoice posts, the stock issue when a delivery ships, the budget commitment when an order is issued. Guards are posting actions that run before a move and can refuse it. Together they turn a status change into real bookkeeping, and they are where several features are switched on per document type.

Where to find it

Architect Panel → ERP - Setup:

Document Posting Actions — every posting action and guard; filter by document type
Document Types — the Posting row action opens one type's posting actions
Documents — the console: Types & health checks each one resolves, and Re-post re-fires one

What a row holds

Document Type.
Trigger: when it runs (see below).
Engine: which part of the ERP does the work, such as doc, ledger, stock, budget, match, sales, price, apprmx (approval matrix), edi or punch (PunchOut).
Action: what that engine does, such as post, issue, reserve, check or send_order.
Config: settings for the action, written as a short JSON object.
Order: the order rows with the same trigger run in.

Triggers

A posting trigger name, such as post, commit, confirm or reverse: runs when a transition whose Posting Trigger has that name is made.
pre:status: a guard, run before the document enters that status. If it refuses, the move does not happen.
pre:convert:type and pre:create: guards before converting into a type, or creating a document.
converted:type: after a conversion, usually moving the source on (a requisition to Ordered).
entered:status: after the document enters a status, such as handing quantities back on Cancelled, or withdrawing open approvals at a dead end.

Posting is part of the move. If any action fails, the move is refused and nothing changes: "Not moved to '...' - posting failed, so nothing was changed: ..." followed by the engine's reason.

Shipped guards worth knowing

Credit check on confirming a sales order (customer on stop, credit limit).
Budget check on issuing a purchase order.
Priced lines on submitting a requisition: a line with a quantity and no price is refused. Remove the row to switch this off.
Required slots on posting a credit note: the reason must be filled in.
Duplicate on submitting or approving a supplier invoice; set its Config to {"require_reference":1} to make the supplier's invoice number mandatory as well.
Match on approving a supplier invoice, when a match policy applies.
Link state guards that stop a delivery or receipt being reversed once billed, and stop an order being marked Fully received before its receipts cover it.

Features you switch on here

PunchOut order transmission: add a row on the Purchase Order type with Trigger commit, Engine punch and Action send_order to queue issued orders back to PunchOut suppliers (see PunchOut Procurement).
EDI purchase orders: the shipped row that sends an 850 or ORDERS when an order is issued is switched off in its Config; most installations instead tick Send purchase orders automatically on each EDI partner (see EDI & Trading Partners).

Checking and re-posting

After any change, open the Documents console's Types & health tab. Each posting row shows Resolves to and Available; an unavailable engine would fail every posting.
To re-run a posting action for one document, open it on the Documents tab and use Re-post. Actions that hand quantities back are refused unless the document is actually at the status they belong to, so Re-post cannot release a live document's quantities.

What goes wrong

"Not moved ... posting failed": read the reason; it is usually a missing account, rate or setting in the engine named.
A move is refused by a guard nobody expected: find the pre: row for that status on the type and read its Config.
Engine not available: the engine named is not installed on this system, or the code is misspelt.

Worked example

A company wants PunchOut orders sent automatically. The architect opens Document Types, uses Posting on Purchase Order and adds a row: Trigger commit, Engine punch, Action send_order, Order 50. Types & health shows the row resolves. The next order issued to a PunchOut supplier is queued for the PunchOut Order Transmission task.

Recommendations

Add rows rather than editing shipped ones, and note why.
Prefer guards for controls: a guard refuses before anything changes.
Check Types & health after every change.
Use Re-post sparingly and only after fixing the cause.

ERP Custom Fields

ERP custom fields add your own fields to ERP records (a customer's account number in your old system, a purchase order's project code, a delivery's carrier) without changing the datastore's structure. The values are kept beside the record and appear on its record screen in a Custom fields pane.

Where to find it

Architect Panel → ERP - Setup:

ERP Custom Fields — the definitions: which datastore a field is added to, its name, label, type and rules
ERP Setup — its checklist lists any custom field definition that is not valid

When to use it

Use a custom field when you need to record something the shipped ERP datastores do not hold and you would rather not change those datastores, which platform updates maintain. For a field that every installation would want, or one you need to report on heavily, adding a real column to your own datastore is usually better.

Defining a custom field

Open ERP Custom Fields and add a row.
Choose the datastore the field belongs to (Table Name), for example the purchase orders or customers datastore. It must be a registered datastore that exists.
Give it an internal name: letters, digits and underscores, starting with a letter or underscore, at most 64 characters, such as carrier_ref. It must not be the name of a real column on that datastore, or of another custom field on it.
Give it the label people will see, and help text that says what to enter.
Choose the type from the picker (text, number, date, a link to another datastore, and so on), and its settings if the type has any, such as the choices of a pick-list.
Set whether it is required, a default value, any validation rule, its position on the form, and whether it is encrypted.
Make sure it is enabled, and save.

Encryption applies to text-like fields (text, long text, phone, address): the value is stored encrypted at rest and searching it still works, more slowly. On a date, number or link field the setting is ignored, because those values are compared and joined.

Using it

Open a record of that datastore on its record screen. The Custom fields pane lists the fields defined for it, with their current values. Edit and save; required fields are checked before anything is written, and only fields defined for that datastore are stored.

Who can see and change the values follows the record: you need read access to the datastore to see them and edit access to change them, the record must be visible to you, and record access rules apply. For ERP documents the ERP role grid applies too, so a buyer can read the custom fields on their own purchase order.

The rules are enforced everywhere

A definition saved through the ERP Custom Fields list, a record screen, the API or an import is checked the same way. The refusals you may see:

"Choose the datastore the custom field belongs to - it must be a registered datastore that exists."
"A custom field needs a valid name: letters, digits and underscores, starting with a letter or underscore, at most 64 characters."
"'...' is already a real column on ... - a custom field cannot shadow it. Choose another name."
"There is already a custom field called '...' on ..."

A definition stored before these checks existed that breaks them is ignored at run time and listed on the ERP Setup checklist, so you can correct it.

What goes wrong

The pane does not appear: no enabled field is defined for that datastore, or you lack read access to it.
A value will not save: a required custom field is empty, or you have read but not edit access.
Turning a field off: disable it rather than deleting it; existing values and history stay intact.

Worked example

A distributor wants every delivery note to record the carrier's consignment number. The architect adds an ERP custom field on the delivery notes datastore with the internal name consignment_no, the label "Consignment number", type text, not required. Warehouse staff open a delivery note's record screen, fill in the Custom fields pane, and the number is there for anyone answering a customer's "where is my order" call.

Recommendations

Name fields as identifiers you will recognise in a year; they cannot clash with real columns.
Write help text; it is what tells people what to enter.
Encrypt sensitive text, not dates or numbers.
Disable rather than delete fields you no longer need.