⚙️ Document commands and subtypes

← Business process wiki

How a user posts a document, why "there is a Posted subtype" does not yet mean the document can be posted from the card, and what happens to the postings when the state changes. How the contours run — the process map.

A command is the only transition button#

The subtype is the document's current state (Draft, Confirmed, Posted…). There is no subtype field on the card: a document is born already in the initial subtype (IsInitial). If there is no initial subtype, or several are marked, Create in the journal first asks which subtype to start in. After that only a command changes the subtype: picking "Posted" from a list is not possible.

A document can only be posted from the UI by a command. The command is bound to the source subtype (for example, only to Draft). When pressed it:

1. Runs the checks through the domain services, without copying their formulas into the command: the balance (IStockAvailabilityService, ISalesFulfillmentService), the cell assignment (IStoreCellService), the quantity in the base unit (IItemQuantityConverter), the tax rate and amount (ITaxService), the period and the accounts (IGeneralLedgerService). If a check fails, the client gets a message (ClientAction.Message), execution stops, and the subtype does not change.
2. Sets the target subtype (document.Subtype = SalesOrder.Subtypes.Confirmed) and saves.
3. The engine posts the document in its new state: the OnBeforePost / OnAfterPost events run, and so do the target subtype's transaction scripts — the postings into the registers, the reservation, the ledger.

A transition command does not call the services' mutating methods (CreateCalculationAsync, InvoiceOrderAsync, CompleteTripAsync, CreateAccrualAsync…): OnAfterPost already runs them. From a command — reading and validation only.

Without such a command the document is a draft forever as far as the card is concerned, no matter how many scripts are attached to "Confirmed". How to make the button — the zuloone-new-command skill. How subtypes and postings work — zuloone-new-document.

The programmatic path (document.Subtype = …, SetSubtypeAsync, the /subtype API) is for services, events and tests, when the checks have already been made higher up. It is not a substitute for the user's button.

A command that changes no subtype (filling in prices, expanding a BOM) does not post the document.

Postings do not accumulate: Mix semantics (replacement, not a sum)#

Yes: on a transition the engine removes every movement the document has already written and writes afresh what the scripts of the target subtype only produce. In the ZuloOne code this is called MIQS replace semantics — that is how Mix worked.

In Mix, on every save DocumentManager took the current SubtypeID's scripts (GetTransactionScripts), computed the new set of postings and handed it to TransactionProcessor.SaveDocumentTransactions: registers no longer in the set went to DeleteDocumentTransactions, the rest to MergeDocumentTransactions (old rows absent from the new set are deleted). Changing the subtype did not "add a layer" — it substituted the document's postings with what the new subtype knows how to write. Commands there were bound to a subtype as well (DocumentCommandToSubtype): the button is visible only on its own state and, once the checks pass, sets the new subtype + Save.

The typical Draft → Confirmed path feels like "just post the document": a draft has no scripts, there is nothing to remove, and the confirmation's postings are written.

But if the states form a chain and each has its own set of registers:

Realized  →  the script writes the realization
Done      →  the script writes something else, no realization in it

then moving Realized → Done will remove the realization's postings. Only what the "Done" subtype wrote stays in the registers. A rollback to draft (a subtype with no scripts) removes the postings entirely — the document is "empty" again.

That is why "pay" must not be made a subtype of the same sales realization: an Issued → Paid transition would erase the stock, the revenue and the receivables along with the "paid" flag. A payment is a document of its own, see obligations and the ledger.

If a later state has to keep an earlier one's effect, the later subtype's scripts write both sets (the realization and "done"), or the second effect lives in another document. The current state's movements = what has to be true now, not the sum of the transition history.

The same transaction script can be attached to several subtypes (in Mix — DocumentSubtypeTransactionScript on different SubtypeIDs). The later state then keeps no "layer" of the earlier one but recomputes the same postings. If the target subtype has no binding, the register rows are deleted.

Transition commands#

One command, one edge. The binding is to the source subtype. The programmatic document.Subtype = … in tests and services is still legitimate; from the card a button is needed.

Stores#

Sales and purchasing#

Issued in the UI is Released. Issued → Paid on a realization does not exist: payment is made by CustomerPayment. There is no Mark delivered on a realization.

DeliveryTrip stays an option for consolidated delivery, not the axis: FillTripFromRoute (collects the Confirmed orders of the route's stops), DispatchTrip (Draft → Dispatched, checks the crew and the capacity), CompleteTrip (closes the orders: a refusal → Cancelled, otherwise Delivered). The global PlanDeliveryWave creates the drafts from the day's schedule. The global PlanPickWave (Gather pick wave, warehouse ribbon) folds draft PickTasks for several orders from one storage cell into one task. An order becomes Delivered when the realization is Released, or when a trip completes. The usual path is order → realization, with no trip. The process — sales and purchasing.

Production, accounting, HR, taxes, loyalty#

Commands without a subtype change#

Rolling back (posted → draft) the engine can do by itself. No document has a separate "Back to draft" command.

How not to confuse the three mechanisms#

A map with no command gives no button. Scripts with no command do not run from the card. Events with no command only fire if the subtype was changed programmatically.

What's not there yet#

• There is no subtype selector on a saved card; a visible command is the only user transition.
• There is no generic Back to draft command for posted documents.
• A sales realization has no paid state; payment is a separate customer payment.

Where next#

• screen steps for users
• Overview and the map of modules
• Process map