Skip to content

docs(Order Configs): correct flow projection + align example with fleetops #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
roncodes merged 2 commits into from
May 27, 2026
Merged

docs(Order Configs): correct flow projection + align example with fleetops #8

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
abe0f3f
docs(Order Configs): correct flow projection + align example with fle…
roncodes May 27, 2026
cc7ad4e
docs(Order Configs): document full flow shape (graph + activity fields)
roncodes May 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
185 changes: 159 additions & 26 deletions postman/collections/Fleetbase API/Order Configs/.resources/object.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,31 +1,116 @@
$kind: object
name: OrderConfig
description: |-
Read-only projection of an OrderConfig. Exposes the activity `flow` and config metadata so consumers can drive status filter chips, activity labels, and progress UI without learning the internal config schema. Internal-only fields (entities JSON, version, raw flow logic) are filtered out.
An OrderConfig defines the activity graph (state machine) used by orders of this type. Consumers read OrderConfigs to render status filter chips, activity labels, and progress UI driven by the canonical config rather than hardcoding their own status set. The `flow` field carries the full editable graph — including conditional logic, event hooks, and child-activity links — so integrations can both display and reason about state transitions.
example: |
{
"id": "ordercfg_A1b2C3d4E5",
"id": "order_config_A1b2C3d4E5",
"key": "transport",
"name": "Transport",
"namespace": "system:order-config:transport",
"description": "Default Fleet-Ops transport flow.",
"tags": [],
"status": "active",
"version": 1,
"flow": [
{ "code": "created", "status": "Order Created", "details": "", "color": "#6028b8", "complete": false, "pod_method": null, "require_pod": false },
{ "code": "dispatched", "status": "Order Dispatched", "details": "", "color": "#2563eb", "complete": false, "pod_method": null, "require_pod": false },
{ "code": "started", "status": "Order Started", "details": "", "color": "#2563eb", "complete": false, "pod_method": null, "require_pod": false },
{ "code": "enroute", "status": "Driver Enroute", "details": "", "color": "#2563eb", "complete": false, "pod_method": null, "require_pod": false },
{ "code": "completed", "status": "Order Completed", "details": "", "color": "#16a34a", "complete": true, "pod_method": null, "require_pod": false }
],
"description": "Default order configuration for transport",
"tags": ["transport", "delivery"],
"status": "private",
"version": "0.0.1",
"flow": {
"created": {
"key": "created",
"code": "created",
"color": "#1f2937",
"logic": [],
"events": [],
"status": "Order Created",
"actions": [],
"details": "New order was created.",
"options": [],
"complete": false,
"entities": [],
"sequence": 0,
"activities": ["dispatched"],
"internalId": "aac819a0-4d3f-4543-b7fa-e50804df83f1",
"pod_method": "scan",
"require_pod": false
},
"enroute": {
"key": "enroute",
"code": "enroute",
"color": "#1f2937",
"logic": [],
"events": [],
"status": "Driver Enroute",
"actions": [],
"details": "Driver is en-route.",
"options": [],
"complete": false,
"entities": [],
"sequence": 0,
"activities": ["completed"],
"internalId": "5422a0c3-8683-4cc2-a4b5-4d064067cd4d",
"pod_method": "scan",
"require_pod": false
},
"started": {
"key": "started",
"code": "started",
"color": "#1f2937",
"logic": [],
"events": [],
"status": "Order Started",
"actions": [],
"details": "Order has been started",
"options": [],
"complete": false,
"entities": [],
"sequence": 0,
"activities": ["enroute"],
"internalId": "b68fad7c-b09d-4161-a01c-a9a95e7f09a8",
"pod_method": "scan",
"require_pod": false
},
"completed": {
"key": "completed",
"code": "completed",
"color": "#1f2937",
"logic": [],
"events": [],
"status": "Order Completed",
"actions": [],
"details": "Order has been completed.",
"options": [],
"complete": true,
"entities": [],
"sequence": 0,
"activities": [],
"internalId": "8406520c-3f61-447b-8a48-d225d0f062d6",
"pod_method": "scan",
"require_pod": false
},
"dispatched": {
"key": "dispatched",
"code": "dispatched",
"color": "#1f2937",
"logic": [],
"events": [],
"status": "Order Dispatched",
"actions": [],
"details": "Order has been dispatched.",
"options": [],
"complete": false,
"entities": [],
"sequence": 0,
"activities": ["started"],
"internalId": "152fa650-34d0-45d8-8b4f-e5820bde4277",
"pod_method": "scan",
"require_pod": false
}
},
"created_at": "2026-04-01T10:00:00.000000Z",
"updated_at": "2026-04-01T10:00:00.000000Z"
}
fields:
- name: id
type: string
description: Public order-config identifier. Prefixed `ordercfg_`.
description: Public order-config identifier. Prefixed `order_config_`.
- name: key
type: string
description: Short identifier (e.g. `transport`). Stable across companies for system configs.
Expand All @@ -43,21 +128,69 @@ fields:
description: Free-form tags.
- name: status
type: string
description: Config lifecycle status (e.g. `active`).
description: Config lifecycle status. Newly created configs default to `private`; system configs may be `active`.
- name: version
type: integer
description: Schema version.
type: string
description: Semver-style schema version (e.g. `0.0.1`).
- name: flow
type: array of objects
type: object
description: |-
Ordered list of activities in the config's status flow. Each activity carries:
- `code` (string) — machine identifier (e.g. `created`, `dispatched`)
- `status` (string) — human-readable label
- `details` (string) — long-form description
- `color` (string) — hex colour hint for status UI
- `complete` (boolean) — true for terminal activities
- `pod_method` (string|null) — proof-of-delivery method, when set
- `require_pod` (boolean) — whether proof-of-delivery is required at this step
The activity graph as an object keyed by activity code. Each value is an **Activity** object — a node in the order's state machine. Activities are linked via their own `activities` field (an array of child activity codes), forming a directed graph from `created` through to a terminal state (`complete: true`). The well-known canonical codes are `created`, `dispatched`, `started`, `enroute`, `completed`, and `canceled`.

The map's key order reflects the order activities are declared in the underlying JSON — **not** graph progression. To walk the workflow, start from `flow.created` (or whichever activity has no inbound edges) and follow each activity's `activities` array. Treat each activity's `code` (and the map key) as the stable identifier; everything else is editable through the operator console.
fields:
- name: key
type: string
description: Canonical activity code. Mirrors the map key and the activity's `code`.
- name: code
type: string
description: Canonical activity code (e.g. `created`, `dispatched`, `started`, `enroute`, `completed`, `canceled`). Treat this as the stable identifier when rendering UI.
- name: status
type: string
description: Human-readable label for the activity (e.g. `Driver Enroute`).
- name: details
type: string
description: Long-form description of what this activity represents.
- name: color
type: string
description: Hex colour hint for status UI (e.g. `#1f2937`).
- name: sequence
type: integer
description: Editor-managed ordering hint, used by the operator UI when laying out the graph.
- name: complete
type: boolean
description: '`true` for terminal activities. The order is considered complete when it reaches an activity with `complete: true`. Multiple activities can be terminal (e.g. `completed`, `canceled`).'
- name: activities
type: array of strings
description: Child activity codes — the activities reachable from this one. This is the graph edge list; an empty array marks a terminal (leaf) node.
- name: pod_method
type: string
description: 'Proof-of-delivery method required at this activity. One of `scan`, `signature`, `photo`, or `null` when no POD is configured.'
- name: require_pod
type: boolean
description: Whether proof-of-delivery must be captured before the order can advance past this activity.
- name: logic
type: array of objects
description: |-
Conditional logic gates evaluated before this activity is considered reachable. Each gate has:
- `type` (string) — `and`, `or`, `not`, or `if`
- `conditions` (array of objects) — each `{ field, operator, value }`, where `operator` is one of `exists`, `in`/`has`, `notIn`/`doesntHave`, `contains`, `beginsWith`, `endsWith`, or a standard comparison (`=`, `!=`, `<`, `>`, `<=`, `>=`)
The default transport config carries an empty `logic` array (no gating).
- name: events
type: array of strings
description: Event names fired when this activity is entered (e.g. notification or webhook hooks). The default transport config carries an empty `events` array.
- name: actions
type: array of objects
description: Actions wired to this activity (reserved for editor-managed handlers). The default transport config carries an empty `actions` array.
- name: options
type: array of objects
description: Activity options exposed by the operator UI. The default transport config carries an empty `options` array.
- name: entities
type: array of objects
description: Entities (parcels, packages, line items) attached specifically to this activity. Most configs carry entities at the OrderConfig level rather than per-activity, so this is typically `[]`.
- name: internalId
type: string
description: UUID assigned by the order-config editor to identify this activity instance. Stable across edits and unrelated to the public `id`.
- name: created_at
type: timestamp
description: When the config was created.
Expand Down
Loading