Order Lifecycle

The NMS API supports two primary ordering workflows, each driven by different data inputs: Program Orders and EMHS Orders. While they share a similar approval flow, their prerequisites and creation processes differ significantly based on the order type.

Workflow Overview

Program Orders

EMHS Orders

Program Orders (Statistics Driven)

Program Orders are scheduled orders for essential health programs. Most program orders (except LAB) require the submission of specific Patient Statistics templates before the corresponding order can be placed.

Order to Statistics Mapping

Each program order type is linked to specific statistics templates. You must submit all required stats for a given order type before creating the order.

Order Type	Required Statistics Templates
ARV	`ARV-ADULT`, `ARV-OI`, `ARV-PED`
HIV TEST KITS	`HIV` Statistics
RH (Reproductive Health)	`RH` Statistics
ANTI-TB	`TB` Statistics
MDR-TB	`MDR-TB` Statistics
LAB	None (Exception)

1. Prerequisite: Submit Required Statistics

Before creating a Program Order, submit the required statistics based on the mapping above. Each statistic has its own template identifier.

Submit Statistics (e.g., ARV-ADULT)

$ curl -X POST https://testapi.nms.go.ug/api/v1/stats/submit \
>   -H "Authorization: Bearer $TOKEN" \
>   -d '{
>     "templateCode": "ARV-ADULT",
>     "hfCode": "HF0124",
>     "financialYear": "2023/2024",
>     "cycle": "1",
>     "data": [...]
>   }'

2. Create Order (Draft)

Once all required statistics for the order type are submitted, create the draft order:

POST /api/v1/orders/program

$ curl -X POST https://testapi.nms.go.ug/api/v1/orders/program \
>   -H "Authorization: Bearer $TOKEN" \
>   -d '{
>     "hfCode": "HF0124",
>     "orderType": "ARV",
>     "financialYear": "2023/2024",
>     "cycle": "1",
>     "items": [...]
>   }'

The response returns a templateCode used for the subsequent approval steps.

Universal Approval Flow

Once an order (Program or EMHS) is created in Draft status, it follows this universal approval lifecycle:

1. Submit for Review

Transition the order from DRAFT to SUBMITTED.

POST /api/v1/orders/{type}/.../submit

$ curl -X POST "https://testapi.nms.go.ug/api/v1/orders/program/{templateCode}/submit" \
>   -H "Authorization: Bearer $TOKEN"

2. First-Level Review

A supervisor or NMS officer reviews and advances the order to REVIEWED.

POST /api/v1/orders/{type}/.../review?approve=true

$ curl -X POST "https://testapi.nms.go.ug/api/v1/orders/program/{templateCode}/review?approve=true" \
>   -H "Authorization: Bearer $TOKEN"

3. Final Approval

The order is authorized for fulfillment and moves to APPROVED.

POST /api/v1/orders/{type}/.../approve?approve=true

$ curl -X POST "https://testapi.nms.go.ug/api/v1/orders/program/{templateCode}/approve?approve=true" \
>   -H "Authorization: Bearer $TOKEN"

The templateCode is used for Program Orders, while EMHS orders typically use the planIdentifier or an internal order ID in their specific lifecycle paths. Refer to the API Reference for the exact path structures for each order type.