At a Glance
Module: purchase-order · Personas: Purchaser · Procurement Manager · Vendor · Receiver · Finance · Audit / Config
Workflow lifecycle: Draft → In Progress → Sent → Partial → Completed / Closed (with Voided branch)
Drill into per-persona views below for action-level detail
This page is the overview entry point for the user-flow set of the purchase-order module. A Purchase Order (PO) is the procurement-commitment document — a PO header (tb_purchase_order) together with one or more detail lines (tb_purchase_order_detail) — that takes the agreed line items from one or more approved Purchase Requests and binds the buyer to the vendor at a fixed price, quantity, and delivery date. The lifecycle in Section 2 spans from initial draft creation through internal approval, transmission to the vendor, partial or full receipt against the PO, and finally closure (normal completion or early closure). The personas involved are the Purchaser (creates and transmits POs, manages amendments), the Procurement Manager (oversight, high-value approval, vendor ranking, override authority), the Vendor (external party with no system login — receives, acknowledges, fulfils, invoices), the Receiver (physically accepts goods and raises GRN against the PO), the Finance team (three-way match and AP posting), and the Audit / Config roles (Auditor for read-only review, System Administrator for workflow and integration configuration). The role catalogue itself is defined in the module landing Section 4.
Section 2 below is the global state machine — the canonical list of transitions across enum_purchase_order_doc_status values, independent of who acts. Each per-persona file (linked from Section 3) describes that persona's path through the state machine — their entry point, the actions available to them, the decision branches they face, and the handoff that ends their involvement. Section 4 then summarises the cross-persona handoffs that stitch the individual paths together. Read this overview first to anchor the lifecycle, then drill into the persona file that matches your role.
The PO document status is stored on tb_purchase_order.po_status and constrained to the values declared in enum_purchase_order_doc_status: draft, in_progress, voided, sent, partial, closed, completed. The transitions below cover the legal moves between them; everything else is rejected by the workflow engine. Note that receipt-driven transitions (sent → partial → completed) are triggered by GRN postings in the downstream good-receive-note module, not by direct user action on the PO.
| From state | Action | To state | Allowed for | Pre-conditions |
|---|---|---|---|---|
(none) |
create | draft |
Purchaser | Header fields validated (vendor_id, currency_id, order_date, delivery_date, workflow_id); at least one line required before submission. PR linkage written to the bridge table when sourced from PR. |
draft |
save (edit) | draft |
Purchaser (owner) | PO still editable; no workflow stage advanced. Header totals (total_qty, total_price, total_tax, total_amount) recalculated on save. |
draft |
submit for approval | in_progress |
Purchaser (owner) | At least one non-deleted line; header complete; selected workflow_id is active for scope purchase-order. last_action set to submitted; stage cursor advances to first approval stage. |
draft |
delete | (none) |
Purchaser, Procurement Manager | Soft-delete only (deleted_at set); allowed solely while the PO is in draft and has never been submitted. |
in_progress |
approve (this stage, not final) | in_progress |
Current-stage approver | Approver is assigned to workflow_current_stage with stage_role = approve; last_action becomes approved; stage cursor advances. |
in_progress |
approve (final stage) | sent |
Final-stage approver (typically Procurement Manager for high-value) | All prior stages signed off; high-value threshold check passed where applicable. PO is transmitted to the vendor on this transition (email / EDI / portal as configured). |
in_progress |
send-back | draft |
Any approver on the chain | Reason text required; returns the PO to the Purchaser for revision. Audit comment written. |
in_progress |
reject / void | voided |
Any approver on the chain, System Administrator | Reason text required; workflow terminates with no further actions allowed. |
sent |
receive (partial) | partial |
Receiver via GRN posting | At least one PO line has received_qty > 0 but received_qty < order_qty − cancelled_qty across the PO. State change is computed from line-level GRN postings. |
sent |
receive (full) | completed |
Receiver via GRN posting | Every line satisfies received_qty + cancelled_qty ≥ order_qty; all lines closed via GRN in a single transaction. |
sent |
void | voided |
Procurement Manager, System Administrator | Reason text required; allowed only when no GRN has yet posted against any line. |
partial |
receive (additional) | partial |
Receiver via GRN posting | Subsequent GRN posts more quantity but the PO still has at least one open line; state remains partial. |
partial |
receive (final balance) | completed |
Receiver via GRN posting | Final GRN clears the outstanding balance on every line; PO transitions to normal completion. |
partial |
close (cannot supply) | closed |
Procurement Manager, Inventory Manager | Vendor cannot supply the outstanding quantity; remaining open qty is treated as cancelled (line cancelled_qty written). Reason text required. |
completed |
(no further action) | completed |
— | Terminal state for the receipt path; three-way match in Finance is tracked on the linked invoice, not on the PO status. |
Each persona below has a dedicated drill-down file describing their entry point, primary flow, decision branches, and exit point. Slugs match the persona role; clicking the link opens the per-persona view.
sent → partial → completed receipt-state transitions.The table below captures the moments where the PO moves from one persona's responsibility to another's. Each handoff is anchored to the document state at the point of transfer.
| From persona | Trigger | To persona | Document state at handoff |
|---|---|---|---|
| Purchaser | Submit for approval | First-stage approver (typically Procurement Manager for high-value) | in_progress (stage cursor on first approval stage) |
| Approver (stage N, not final) | Approve at this stage | Approver (stage N+1) | in_progress (stage cursor advances) |
| Procurement Manager (final stage) | Approve at final stage and transmit | Vendor | sent (PO transmitted; awaiting first GRN) |
| Approver (any stage) | Send-back with reason | Purchaser | draft (with revision history and approver comment retained) |
| Vendor | Physical delivery of goods | Receiver | sent (system state unchanged until GRN is posted) |
| Receiver | Post GRN — partial fulfilment | Purchaser, Inventory Manager | partial (one or more lines still open) |
| Receiver | Post GRN — final balance | Finance (for invoice match) | completed (every line fully received) |
| Procurement Manager / Inventory Manager | Close PO with remaining qty as cancelled | Finance (close-out review) | closed (remaining qty written as cancelled_qty) |
| Procurement Manager / System Administrator | Void with reason | Auditor (post-hoc review only) | voided |
| Finance | Three-way match completes and AP posted | (terminal) | completed (PO unchanged; AP liability posted against the matched invoice) |
../carmen/docs/purchase-order-management/purchase-order-module.md — primary carmen/docs source for the business analysis, state diagram, and PO creation flows.enum_purchase_order_doc_status values used in Section 2 above and the bridge table that carries PR→PO traceability.partial / completed transitions), vendor-pricelist (price snapshot at PR-to-PO conversion time).