Order Lifecycle

This page covers the operational behaviors that act on existing purchase orders: updating the order header, viewing order details, listing orders, processing an order through its states, and submitting an order to a vendor.

Use case references:

• PRO::PO::0003::0003 — Update Header
• PRO::PO::0002 — View and List Orders
• PRO::PO::0004 — Submit Order

---

Update Order Header

Use case: PRO::PO::0003::0002 and PRO::PO::0003::0003 — Priority: MVP2-B

Orders are only editable when they are in the NEW state. The Edit action is therefore only available from the Draft order list.

Steps

1. User requests the list of Draft Orders.
2. User selects an Order from the list and clicks the Edit button.
3. The system displays the Order Header in Edit Mode, loading the current header information from the list cache.
4. The user updates the Order Header properties. Changes are stored in a local copy without immediately persisting.
5. The user clicks Save.
6. The system calls PUT /v1/order/order/{eId} with the updated OrderHeaderInput.
7. On success, the system displays the updated Order Header. On error, validation messages are shown without losing the user’s changes.
8. The user dismisses the displayed Order Header and returns to the Draft Order List.

The actor modifies fields including: vendor name, contact information, shipping terms, delivery address, payment terms, line quantities, line descriptions, and notes.

The following fields are system-managed and cannot be overwritten by the actor: orderNumber, status, and goodsValue.

Precondition: The PO exists in NEW state.

Postcondition: Card states are unchanged when header or line fields are edited; associated cards remain in REQUESTED.

Sequence Diagram

API Routes

Step	Route	Notes
Get Order Headers with Status NEW	POST /v1/order/order/query	Filter for status: NEW; returns a page of Order Header Records
Update Header	PUT /v1/order/order/{eId}	Body is updated OrderHeaderInput; returns the Updated OrderHeader Record

---

View Order Details

Use case: PRO::PO::0002::0002 and PRO::PO::0002::0003 — Priority: MVP3

From any list of Purchase Orders, a Purchase Order can be selected to view its details.

Three API paths are available depending on what information is needed:

Path	Description
GET /v1/order/order/{eId}	Returns the PO header only
GET /v1/order/order/full/{eId}	Returns the PO header and all lines
GET /v1/order/order/lines/{eId}	Returns the PO lines only

The full view includes header fields, line items with quantities and costs, and the list of serviced Kanban Cards associated with each line.

Postcondition: The actor can review PO history and current state, including which cards were fulfilled by each order.

---

Listing Orders

Use case: PRO::PO::0002::0001 — Priority: MVP3

Purchase Orders are listed through the general Query capabilities of DataAuthority Endpoints using POST /v1/order/order/query.

Status Groupings

Orders are categorized into status groupings for display:

Grouping	Statuses
Draft	NEW
Receiving	SUBMITTED, IN_PROCESS, PARTIALLY_RECEIVED
Completed	RECEIVED, CLOSED, ARCHIVED, CANCELLED

Other status values are not used in MVP2.

Query Format

{
  "filter": {
    "status": {
      "in": ["<STATUS_VALUE>"]
    }
  }
}

Filterable and Sortable Fields

Field	Type	Description
eId	String (UUID)	Entity ID of the Purchase Order
effective_as_of	Long	Unix Epoch (UTC) for the last update
created_at_effective	Long	Unix Epoch (UTC) for creation
status	Enumerated OrderStatus	Status of the Purchase Order
order_number	String	Order number
order_date_timestamp	Long	Unix Epoch (UTC) for the order date
order_date_time_zone	String	IANA timezone identifier
allow_partial	Boolean	Whether the order allows partial fulfillment
expedite	Boolean	Whether the order is expedited
deliver_by_timestamp	Long	Deliver-by Unix Epoch
delivery_address_*	PostalAddress	Delivery address sub-fields
procurement_*	Contact	Procurement contact sub-fields
supplier_name	String	Supplier name
supplier_address_*	PostalAddress	Supplier address sub-fields
order_method	Enumerated OrderMethod	Order method
sales_*	Contact	Sales contact sub-fields
goods_value_value	Decimal	Decimal goods value
goods_value_currency	String	Currency for goods value
accounting_reference	String	Accounting reference
terms_and_conditions	String	Terms and conditions
notes	String	Notes
private_notes	String	Private notes

For composite fields marked by *, the following sub-fields are available:

Address sub-fields: address_line_1, address_line_2, city, state, postal_code, country (Enumerated CountrySymbol), geo_location

Contact sub-fields: salutation, first_name, middle_name, last_name, job_title, email, phone, postal_address

Geo-location sub-fields: latitude, longitude, elevation

---

Process Order

Use case: PRO::PO::0004 — Priority: MVP2-B Partial

The process-order lifecycle encompasses four actions that advance a purchase order through its states. The submit step is partially implemented; receiving and completion are defined here as stubs.

Submit a Purchase Order

Use case: PRO::PO::0004::0001 — Priority: MVP2-B

The actor clicks Submit PO. The system validates required fields:

• Vendor name must be present.
• At least one line must exist.
• All lines must have a non-empty title and non-null quantity.

On validation success, the system sends start-processing events to all cards in REQUESTED state across all PO lines, transitioning them to IN_PROCESS. The PO status advances to SUBMITTED.

Validation error messages:

• “Vendor name is required.” — if vendor name is absent.
• “Add at least one line item.” — if no lines exist.
• “All lines must have a title and quantity.” — if any line is missing required fields.

API Route: PUT /v1/order/order/{eId}/submit

Submit and Release (Skip Receiving)

Use case: PRO::PO::0004::0002 — Priority: MVP3

The actor clicks Submit and Release. The same validation as Submit applies. On success, instead of transitioning cards to IN_PROCESS, the system sends receive events that transition cards directly from REQUESTED to FULFILLED. The PO status advances to RECEIVED or CLOSED. No receiving step is required.

This supports organizations that do not use a formal receiving workflow, or for orders where goods are already on hand and the PO is created retroactively.

Postcondition: Cards are in FULFILLED and immediately available on the shop floor. The PO is complete.

Record Receiving against a Purchase Order

Not yet specified in detail. Receiving is tracked through the Receiving module; see the Procurement domain index for related information.

Complete a Purchase Order

Not yet specified in detail.

Cancel a Purchase Order

Use case: PRO::PO::0007::0001 — Priority: MVP3

The actor opens a PO in NEW or SUBMITTED state and clicks Cancel. A confirmation dialog asks: “Cancel this purchase order?” On confirm, the system sends shelve events to all cards in REQUESTED state, reverting them to REQUESTING and returning them to the Order Queue. For cards in IN_PROCESS state, rollback behavior is TBD. The PO status advances to CANCELLED.

Postcondition: REQUESTED cards are returned to the Order Queue. The PO is cancelled and read-only.

---

Submit Order — Implementation Status

Use case: PRO::PO::0004::0003 — Not yet implemented

The Submit Order use case describes the desired submission workflow that transitions a draft PO into an externally committed state — validating the order, transitioning its status, and triggering downstream integrations such as vendor notification.

The existing services expose CRUD helpers (OrderRecordService, OrderFromItemsService, OrderFromCardsService) but do not change OrderStatus or initiate vendor communication. Orders remain in their previous state after creation or edits.

Outstanding Work

• Implement a submission flow that validates an order, transitions its status, and triggers downstream integrations.
• Coordinate with KanbanCardService to propagate events to associated Kanban Cards on submission.
• Define how to move orders from NEW/APPROVED to downstream states.