Skip to content

Purchase Order Management

Tracking

Concepts

General

Organization:
A legal entity that can enter into contracts with other Organizations. It may represent a company, a department within a company, government agencies, ….

Contact:
A person that can act on behalf of an organization.

Vendor:
An Organization that commercially offers goods for sale.

Customer:
An organization that commercially acquires goods.

Supplier:
An organization that fulfills goods in response to a commercial transaction.

Consumer: An organization that receives goods resulting from a commercial transaction

Carrier: An Organization responsible for the physical transfer of goods from a Supplier to a Consumer. Note that at this point we do not distinguish between physical carriers, freight forwarders, brokers, etc. The system is focused on the Delivery and Receiving of goods and the Carrier is understood to be the one the provides the Bill of Lading at the time of delivery.

Note

In Supply Chain Management in general, the term Carrier is used to refer to the organization that physically moves goods from one location to another. With additional detail on the roles played by other organizations like Freight Forwarders, Brokers, etc. to manage the
different aspects of assigning risk, responsibilities and activities to different parties and depending on the Incoterms agreed between the parties.

For the purpose of this document and the scope of Arda’s product at this time, Carrier is a general term for the party that will be presenting the Bill of Lading at the time of delivery of goods. Furthermore, in many cases, this will be left unspecified with the understanding that it is either the supplier or there are other arrangements outside what the system manages.

Other Parties:
Organizations that may participate in a commercial transaction aside from the ones mentioned above like Insurers, Financing Providers, Government agencies

Tenant: An organization that has a contract with Arda Systems to access and use
Arda’s products.

Purchase Order (PO):
A request from a Customer to a Vendor to purchase goods. If the Purchase Order is accepted by the Vendor, it becomes a contract for the supply of goods by the Supplier to the Consumer subject to the terms and conditions specified in the order.

Purchase Order Line (PoLine):
Information that specifies a quantity of a given item to be purchased Within the context of a PO. The PoLine specifies the unit price and total price of the quantity
of the item plus any additional information relevant for the transaction that is not already contained in the general information of the PO

Constraints for Oct2025 Purchase Orders Feature Release

  1. In the context of a Purchase Order
    1. Vendor and Supplier are assumed to be the same organization
    2. Customer and Consumer are assumed to be the same organization, which matches the organization that owns the Tenant in the Arda System.
    3. The system will not explicitly consider or manage Freight Operators or Other Parties
  2. The system will not keep or manage organizations separately from a Purchase Order itself other than as Supply information in Items.

Requirements Summary

The system will provide Restful API, and User Interface to access the functionality:

  1. Creating a PO:
    1. As an empty PO from scratch (with no lines)
    2. From a set of Kanban Cards in the Order Queue
    3. As a Copy of a pre-existing PO
    4. From a set of Items selected from the Item List.
  2. Viewing PO’s
    1. Listing PO’s showing the information in their headers with ability to filter, sort and paginate through the list.
    2. Listing PO’s based on their State (See Lifecycle). The API and UI components to support this should be generic
      enough to allow quick iteration on the user experience (e.g. show specialized lists for certain states) based on feedback after initial release.
      These lists will show by default all POs that belong to the tenant that are in the applicable states. For the CLOSED orders, the list will default to orders in the last month, these lists will:
      1. Filter by a time window of the last modification.
      1. The time window should not exceed 3 months in length.
      2. Should not specify dates older than 3 years from the current date.
      3. Have a default time window of 30 days that can be overridden by the user within the constraints above.
      2. Filter and Sort based on header field values. (Details to be determined)
      3. Filter (not sort) based on Item Names of PoLines
      4. Paginate through the results.
      5. Set a maximum number of PO’s returned in a single page to 200 entries.
    3. Viewing the details of PO. Including Header information and PO Lines.
    4. Viewing additional detail of a PO Line.
  3. Editing a PO if its state and User permissions allow. Editing a PO includes:
    1. Editing Header information
    2. Adding or removing PoLines
      1. Duplicate one or multiple PoLines (they don’t duplicate attached Kanban Cards if any)
      2. From a selection of Items
      3. From a selection of Kanban Cards in the Order Queue
    3. Editing individual PoLines.
    4. Reordering PoLines.
  4. Executing actions on the PO, which include (see lifecycle for a complete list)
    1. Submitting a PO
    2. Printing a PO
    3. Receiving goods associated with a PO
    4. Closing a PO

Information Model

uml diagram

General Information Contents

All entities will include the following information:

Field Name Type Description Notes
id UUID A unique to the entity in the system Generated by the system. Not editable
rId UUID A unique identifier for a particular version of the entity Not editable
createdBy Text The identification of the user that created the entity Not Editable
createdAt TimeCoordinates The time when the entity was created, specifying when it was created in the real world and when it was recorded by the system.
author Text The identification of the users that made the latest change (version) of the entity.
asOf TimeCoordinates The time when the latest change was made (effective and recorded).

In addition, Orders belong to a tenant, so they will also have:

Field Name Type Description Notes
tenantId UUID The identification of the tenant that owns this entity.

Entities

Purchase Order

Field Name Type Default User Editable Description Notes
status Enumerated NEW No The current status of the order in its lifecycle. Not directly editable, but it changes with signal/actions that the user performs on the Order
orderNumber String PO##### (Sequential) No A human-readable identification for the Order In the future, it will be configurable by the tenant.
orderDate Date Creation Date Yes The date when the order is submitted (see lifecycle).
allowPartial Boolean True Yes Whether the PO allows partial deliveries of the goods.
deliverBy DateTime Creation Date Yes The date when the goods are expected to be completely delivered.
deliveryAddress Address blank once Tenant and/or Facility information is available, it will be defaulted from there Yes The address to which the goods are expected to be delivered.
procurement Contact User Info Yes Information to contact the Customer organization regarding the order.
supplierName String blank, or fromthe lines if available Yes The Supplier that will be commercially responsible for fulfillment
supplierAddress Address blank, or fromthe lines if available Yes The address of the Supplier organization
orderMethod Enumerated UNKNOWN or from the lines if available Yes The method by which the order is submitted to the Supplier. In the future, this may affect the behavior of the system when submitting the order.
sales Contact From Supplier Information if available Yes Information to contact the Vendor organization regarding the order.
goodsValue Money Calculated in USD (future will change) No The sum of value for all PoLines in the order.
taxesAndFees Map emptyMap Yes A map of charges with a text for identification in the PO to be borne by the Customer as part of the order. E.g, delivery charges, fees, taxes, etc.
totalAmount Money Calculated No The sum of the goodsValue plus the taxesAndFees entries.
termsAndConditions String blank Yes A free form text identifying Terms and Conditions agreed for this order.
notes String blank Yes Other notes.
privateNotes String blank Yes Notes private to the Customer Organization and not part of the communication to the Vendor.
orderLines Int Calculated No the number of PoLines in the order.
Notes
  1. All fields become read-only once the order is not in the NEW state. except for privateNotes.
  2. When the order is created as a copy of another order, all fields, except for privateNotes, orderNumber and orderDate should be copied from the source order.
  3. In the future, additional default logic may be available to populate some fields based on tenant configuration.

PoLine

Field Name Type Default User Editable Description Notes
status Enumerated BLANK No The current status of the line in its lifecycle. Not directly editable, but it changes with signal/actions that the user performs on the line
item Reference blank or taken from the card or source PO for copies Only when blank.User should deleteand add another line. A reference to the item that represent the goods the PoLine requests. It contains the name of the Item, a UUID identifying the item and optionally a second UUID representing the rId of the version of the item.
supplierSku String from the item and vendor No The SKU or identification code used by the Supplier for the item. Taken from the Item information if available, blank otherwise
quantity Quantity 0 eaches or taken from the Card or source PO Special editing rules for quantities.Change needs to be confirmed by user before being effective. The amount of the goods requested with an associated Unit of Measure.
unitCost Money from the item and vendor Yes The cost of each unit of goods with a specified currency for the given Unit of Measure. Taken from the Item information if a cost per the given unit is specified, blank otherwise
cost Money unitCost * quantity.amount No The total cost of the goods specified by the line.
received Quantity 0 %Unit% with the UoM of the reorder Qty or 0 eaches Yes The amount of goods that are received directly associated with this PoLine It will be expressed in the same units as the quantity.
notes String blank Yes Free form text for instructions or special communication to the Vendor from the Customer.
privateNotes String blank Yes Notes private to the Customer Organization and not part of the communication to the Vendor.
Notes
  1. All fields become read-only once the order is not in the NEW state. except for notes and received.

Lifecycle

Order Lifecycle

uml diagram

Order States

State Description Notes
NEW The order has been created and in the process of being edited and defined.
APPROVED The order has been defined within the Customer and is ready to send to the Vendor
SUBMITTED The order has been submitted to the Vendor
ACCEPTED The Vendor has accepted the order but not started fulfillment
IN_PROCESS Vendor has started processing the order and goods are expected to be delivered
PARTIALLY_RECEIVED Some goods included in the Order have been delivered, but not all
RECEIVED All goods included in the order have been delivered
CLOSED The order is marked as complete by the Customer, triggering any Accounting effects
CANCELLED The order has been cancelled before Submission or afterwards and the Vendor has accepted the cancellation
REJECTED Some goods for the order have been delivered, but the Customer has rejected at least part of them The business consequences may vary from just noting an irregularity to the complete invalidation of the order. This is out of scope for this release
DISPUTED There is a disagreement between the Vendor and the Customer regarding the fulfillment of the Order, from the point of view of the Customer. This may signal a number of different situations. At this point the system will treat it as just a marker that cab be used by the business to take other actions

Order Signals

Basic Order Signals
Signal Description Effects Notes
approve The User Marks the Order as APPROVED The Order’s fields and lines become fixed and readonly.
submit The Order has been sent to the Vendor The system will take actions to send the Order to the vendor depending on the orderMethod of each of its PoLines. See Behavior for more details.
accept The Order is accepted by the Vendor.
ship The order has started fulfillment by the vendor. Effects may vary by vendor regarding whether the order can be cancelled or not, or other aspects depending on the T&C. In the initial release, no effects are enforced or supported by the system other than marking the order status
receive Goods associated with the order are received. This signal contains parameters specifying the item and quantity of the goods received. The System will record those against the order’s PoLines.
complete_receive All the goods expected by the order have been received. In the initial release, the Order will not automatically transition to RECEIVED based on a computed reconciliation of received quantities vs. ordered quantities. In the future, orders will allow for configuration of this behavior.
complete The order is considered complete from the point of view of Material Flow Operations
cancel The order is cancelled, and no goods are expected to be received against it in the future. Initially the system simply records this signal and changes the status of the Order. It does not verify whether the Vendor has accepted cancellation or not, or any other business conditions. In the future this signal and the associated status of CANCELLED may be refined into multiple states and signals to track the cancellation process more closely (e.g., acceptance of cancellation by Vendor)
reject The Customer rejects goods delivered against the order At this time, the system simply records the event, which may provide information on the item and quantity rejected. In the future, more sophisticated rejection/receiving behaviors may be possible.
dispute The customer registers an issue with the order that prevents it from being closed and require busines resolution with the Vendor
Composite Order Signals

The UI and the API may allow Composite Signals that are equivalent to a sequence of elementary signals with the effects equivalent as if the elementary signals had occurred in rapid sequence. Including, but not limited to:

  • submit from a NEW state is equivalent to [approve, submit]
  • complete from any state is equivalent to the shortest sequence of signals that will result in CLOSED from the current state (e.g., [approve, submit, ship, complete_receive, complete])
  • …

Order Line Lifecycle

Note that the Status of the line may be implemented as a transient state that is only computed when the line is inspected by the system and not stored explicitly in the database. This is to avoid the need to update all lines of all orders that mention an item each time an item is modified or deleted.

uml diagram

Order Line States

State Description Notes
BLANK There is no item associated with the Line.
CURRENT The Item and the line are up-to-date The line when inspected in its DB representation may still show as CURRENT even if the item has changed or been deleted. The state updates upon inspection of the line.
STALE The Item referenced by the Line has changed, and the line is still editable.
INVALID The item referenced by the Line has been deleted, and the line is still editable.
RECEIVING The Order has been submitted, the line is no longer editable and goods are being received against it
COMPLETED The line is considered to have completed receiving, the received quantity is no longer editable

Order Line Signals

Signal Description Effects Notes
assign item The User assigns a new item to the PoLine The information from the item populates the POLine, overwriting previous values The UI should ask for confirmation when the user (re-)assigns an item to an already assigned Line
unassign item The User removes the assigned item from the Line No updates to the line.
item deleted The item assigned with the Line is deleted without first removing it from the line. No immediate action, the state implicitly becomes INVALID.
item changed The item assigned with the line is edited asynchronously to editing the line. No immediate action, the state implicitly becomes STALE.
line refreshed The line is inspected by the Purchase Order Module. Upon inspection, if the state is STALE, the system automatically refreshes it to the latest values of the item, respecting any edits the user may have done (e.g. changing quantities or units). if any updates cannot be applied, the Line must be marked as FIX in a way that the User can see and take action. (e.g., updating or confirming the edits).
If the line is INVALID, the system will remove the reference to the item and mark the line as UNASSIGNED		 The System should also flag any PoLines that are UNASSIGNED for the user
delete The User removes the Line from the Purchase Order The Line is deleted from the Order and its state is no longer tracked.
order submitted The parent order has been submitted to the vendor Order lines are no longer editable other than receiving quantity and private notes.
receive The User associates a quantity of goods received against the line The received field of the line is updated.
complete The User signals that receiving against the line is complete The line received field becomes read-only. Note that when an order transitions to RECEIVED, all its orders are automatically completed

Behaviors

Order Creation

Add Lines to Existing Order

Order Lifecycle

General Behavior of Order Actions

Each PoLine contains a reference to an Item. The reference contains the ID of the item (UUID), the name of the item and an optional rId (UUID) of the version of the item that is referenced. The rId is null while the order is in the NEW state.

Once an order is no longer NEW, neither itself nor its lines are editable and the item references of its lines are fixed to the version of the item that was current at the time of approval. Even if the item is deleted, the line remains valid as a record of what was approved/submitted to the vendor.

When the order is NEW and therefore editable, the behavior of the order lines is as follows:

  1. When the orders are listed, the system will not show its order lines and the order lines will not be updated even if the items they reference are modified or deleted.

Note

Some computed fields of the order like goodsValue and totalAmount may show out of date values.

  1. Filtering by item name of the lines will be done against the last updated value of the item name in the line, not the current item name if it has been updated.

When an order is loaded for viewing, editing or any other action, the system will review the item references of its lines and update them to match the latest version of the Item at the time of the request. If the item has been deleted, the line will be marked as invalid and the order cannot be approved or submitted until all its invalid lines are either edited changing the item, or deleted.

Actions after approve, submit and ship

  1. submit the order, triggering any purchase process actions for its lines following their prescribed ORDER_METHOD (e.g. opening online URL’s, creating an email with the order, generating a PDF of the order for printing/emailing, …). If the Order has associated Kanban cards, the cards are moved to IN_PROCESS.
  2. receive: The system registers the received goods and counts them against the first order line that matches its values and has not been fully received yet (its received quantity less than ordered quantity). (an additional workflow improvement would be to allow the user to select which line to match).
  3. complete_receive: Similar to receive and the system will mark the order as COMPLETE

Actions after complete_receive

  1. close mark the order as CLOSED
  2. dispute mark the order as DISPUTED

Non-Happy Paths

  1. cancel will put the order in a CANCELLED state and prevent any future actions on it other than closing it.

Modifications to User Workflows for Ordering and Receiving

See Mapping Kanban Card State to Procurement Workflow for MVP0/MVP1 implementation

  1. The actions available on the Order Queue will change:
    1. The Order action on a card allows the user to either create a new Purchase Order from selected cards or add the cards to an existing Purchase Order in NEW state.
    2. When a Card is added to a Purchase Order, it moves from REQUESTING to REQUESTED.
      !!! note
      UX to decide how to present this information to the user in the Order Queue, or to have the user navigate to the Cards List to see them.
  2. When the Purchase Order is submitted, all the associated Cards move to IN_PROCESS.
  3. When the Purchase Order is Received, all its lines are complete and the associated Cards move to FULFILLED.

Interactions with Kanban Cards

In the Demo202509 release, Kanban Cards are the main entity supporting the Ordering process. With the introduction of Purchase Orders, there need to be changes to the User Interaction with Kanban Cards.

Listing of Kanban Cards

  1. The system needs to provide a list of Kanban Cards showing their State and other information.
  2. Each time a Kanban Card is loaded, the system will check if its associated Item has been changed or deleted and present an indication of that to the user.
  3. The list allows filtering by item name, state, preferred vendor and date range of last modification.

Board Display of Cards

The list of cards can be presented as a regular list/table or as a Board, for a Board display, There will be three board displays:

  1. Producer Board that shows cards in REQUESTING, REQUESTED, IN_PROCESS, READY and FULFILLING states, with actions to accept, start, complete and fulfill cards.
  2. Consumer Board that shows cards in FULFILLING, FULFILLED, IN_USE, DEPLETED and REQUESTING with actions to receive, use, deplete and request
  3. Overview Board with all States and actions available.

Any of these boards may hide columns depending on the user settings. Initially, the hide/show settings will be remembered by a system for the duration of a session. At a later release this will be extended to be remembered across sessions and be configurable by station at the tenant or user level.

Refreshing Kanban Cards

For the Kanban Cards that are marked as modified (i.e., the item they reference has been changed), the user can refresh the card to update its information to match the current version of the item.

If the item has been deleted, the card will be marked as invalid and cannot be used to create an order.

Actions on Cards independent of Orders

The user can change the state of a card from REQUESTED to any other state of the card except if there exists an Order that claims it as attached to one of its lines.

If there is an Order Line attached to a Kanban Card, the user will not be able to act on it. This should be indicated in any list or display of the card by a special state of LOCKED that is independent of the card lifecycle itself.

Implementation Tickets (Draft)

Implementation Notes

  • Purchase Order CRUD
    • Create PO from Blank
    • Create PO from Kanban Cards
    • Create PO from Copy
    • Edit PO
    • Flag and Handle Invalid Lines
  • Purchase Order Actions
    • Approve/Submit
    • Receiving
    • Complete Receiving
    • Non-Happy Path
    • Composites
  • Purchase Order PDF Printing.
  • Kanban Card Modifications
    • Add LOCKED Lifecycle to a Kanban Card
    • Implement UPDATE_REQUIRED and INVALID states to signal the associated Item has changed.
    • Implement refresh action and implement “auto-refresh” as the current default behavior.
    • Revert display of item name to use the item reference instead of the ItemDetails in the UI.
    • Implement Kanban Card List
    • Implement Kanban Card Boards

Comments