Loading

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

  1. Open Document Types and use the Transitions row action on the type.
  2. Add or edit a row: From, To, Button Label, and the flags you need.
  3. Open the Documents console's Types & health tab and check the lifecycle reads as you intended.
  4. 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.