From abe0f3f05214616aad42e32c2f69bc4b5dc81478 Mon Sep 17 00:00:00 2001 From: "Ronald A. Richardson" Date: Wed, 27 May 2026 14:40:25 +0800 Subject: [PATCH 1/2] docs(Order Configs): correct flow projection + align example with fleetops MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The OrderConfig public projection (Http/Resources/v1/OrderConfig.php) exposes a flattened, public-safe view of an activity graph. The previous doc described `flow` as a simple ordered list and the example used aspirational values that don't match the seeded default transport config in fleetops. This commit: - Documents `flow` as a graph projection. Explains that the editable wiring (logic, events, options, activities/child links, sequence, key, internalId) is filtered out, that consumers should drive UI from each row's `code` (with the canonical codes: created, dispatched, started, enroute, completed, canceled), and that array order is insertion-order — not graph progression. - Enumerates `pod_method` values: `scan`, `signature`, `photo`, or null (per config/fleetops.php). - Fixes the `id` prefix to `order_config_` (HasPublicId trait builds the prefix from `publicIdType` directly). - Corrects `version` type to string (semver — DB column is varchar, defaults to `0.0.1`). - Clarifies `status` default (`private` for newly created configs). - Replaces the example values with the actual default Fleet-Ops transport config seeded by FleetOps::createTransportConfig — real colors (#1f2937), real details, pod_method "scan", tags, and the insertion-order activity list. --- .../Order Configs/.resources/object.yaml | 48 ++++++++++--------- 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/postman/collections/Fleetbase API/Order Configs/.resources/object.yaml b/postman/collections/Fleetbase API/Order Configs/.resources/object.yaml index 82e32e1..98e8544 100644 --- a/postman/collections/Fleetbase API/Order Configs/.resources/object.yaml +++ b/postman/collections/Fleetbase API/Order Configs/.resources/object.yaml @@ -1,23 +1,23 @@ $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. + 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, raw flow logic, events, options, the editable activity graph) are filtered out. 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, + "description": "Default order configuration for transport", + "tags": ["transport", "delivery"], + "status": "private", + "version": "0.0.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 } + { "code": "created", "status": "Order Created", "details": "New order was created.", "color": "#1f2937", "complete": false, "pod_method": "scan", "require_pod": false }, + { "code": "enroute", "status": "Driver Enroute", "details": "Driver is en-route.", "color": "#1f2937", "complete": false, "pod_method": "scan", "require_pod": false }, + { "code": "started", "status": "Order Started", "details": "Order has been started", "color": "#1f2937", "complete": false, "pod_method": "scan", "require_pod": false }, + { "code": "completed", "status": "Order Completed", "details": "Order has been completed.","color": "#1f2937", "complete": true, "pod_method": "scan", "require_pod": false }, + { "code": "dispatched", "status": "Order Dispatched", "details": "Order has been dispatched.","color": "#1f2937", "complete": false, "pod_method": "scan", "require_pod": false } ], "created_at": "2026-04-01T10:00:00.000000Z", "updated_at": "2026-04-01T10:00:00.000000Z" @@ -25,7 +25,7 @@ example: | 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. @@ -43,21 +43,23 @@ 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 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 + Public-safe projection of the config's activity graph. Internally each activity is a node in a directed graph (an activity's `activities` field lists its child activity codes), but this projection flattens the graph into a list of activity rows and drops the editable wiring (logic, events, options, activities/child links, sequence, key, internalId). + Each row carries: + - `code` (string) — canonical activity identifier. Well-known codes for the default transport config are `created`, `dispatched`, `started`, `enroute`, `completed`; `canceled` is reserved for cancellations. Treat `code` as the stable identifier and drive UI from it rather than from the row's position in the array. + - `status` (string) — human-readable label (e.g. `Order Dispatched`). + - `details` (string|null) — long-form description. + - `color` (string|null) — hex colour hint for status UI. + - `complete` (boolean) — `true` for terminal activities (e.g. `completed`). Multiple activities can be terminal. + - `pod_method` (string|null) — proof-of-delivery method required by this activity. One of `scan`, `signature`, `photo`, or `null` when no POD is configured. + - `require_pod` (boolean) — whether proof-of-delivery is required to advance past this activity. + Array order reflects how activities are declared in the underlying flow object (insertion order) and is **not** guaranteed to follow graph progression. Consumers needing the workflow sequence should manage the operator console — the public surface does not expose child-activity links. - name: created_at type: timestamp description: When the config was created. From cc7ad4e58e6036bf49591e15e23da31ab4e2df77 Mon Sep 17 00:00:00 2001 From: "Ronald A. Richardson" Date: Wed, 27 May 2026 14:51:07 +0800 Subject: [PATCH 2/2] docs(Order Configs): document full flow shape (graph + activity fields) The actual API response returns `flow` as an object/map keyed by activity code, with each Activity carrying the full editable shape (key, code, color, logic, events, status, actions, details, options, complete, entities, sequence, activities, internalId, pod_method, require_pod). The previous doc framed `flow` as a projected array and omitted the graph-link (`activities`) and editor wiring (logic, events, actions, options, entities, sequence, internalId), which are exactly what integrators need to read the workflow. This commit replaces that with the full shape: - `flow` is typed `object` and described as the activity graph keyed by canonical activity code. Documents the well-known codes (created, dispatched, started, enroute, completed, canceled), notes that map order is insertion order rather than graph progression, and points consumers at the per-activity `activities` field for traversal. - Each activity field is documented as a nested `` so the docs surface every key in the response. - `logic` documents the gate shape (`type` + `conditions`) and the supported operators (exists, in/has, notIn/doesntHave, contains, beginsWith, endsWith, and standard comparisons) sourced from Flow/Logic.php and Flow/Condition.php. - `pod_method` enumerates `scan | signature | photo | null` (from config/fleetops.php). - Example replaced with the actual default-seeded transport config response from fleetops. --- .../Order Configs/.resources/object.yaml | 169 ++++++++++++++++-- 1 file changed, 150 insertions(+), 19 deletions(-) diff --git a/postman/collections/Fleetbase API/Order Configs/.resources/object.yaml b/postman/collections/Fleetbase API/Order Configs/.resources/object.yaml index 98e8544..535291a 100644 --- a/postman/collections/Fleetbase API/Order Configs/.resources/object.yaml +++ b/postman/collections/Fleetbase API/Order Configs/.resources/object.yaml @@ -1,7 +1,7 @@ $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, raw flow logic, events, options, the editable activity graph) 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": "order_config_A1b2C3d4E5", @@ -12,13 +12,98 @@ example: | "tags": ["transport", "delivery"], "status": "private", "version": "0.0.1", - "flow": [ - { "code": "created", "status": "Order Created", "details": "New order was created.", "color": "#1f2937", "complete": false, "pod_method": "scan", "require_pod": false }, - { "code": "enroute", "status": "Driver Enroute", "details": "Driver is en-route.", "color": "#1f2937", "complete": false, "pod_method": "scan", "require_pod": false }, - { "code": "started", "status": "Order Started", "details": "Order has been started", "color": "#1f2937", "complete": false, "pod_method": "scan", "require_pod": false }, - { "code": "completed", "status": "Order Completed", "details": "Order has been completed.","color": "#1f2937", "complete": true, "pod_method": "scan", "require_pod": false }, - { "code": "dispatched", "status": "Order Dispatched", "details": "Order has been dispatched.","color": "#1f2937", "complete": false, "pod_method": "scan", "require_pod": false } - ], + "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" } @@ -48,18 +133,64 @@ fields: type: string description: Semver-style schema version (e.g. `0.0.1`). - name: flow - type: array of objects + type: object description: |- - Public-safe projection of the config's activity graph. Internally each activity is a node in a directed graph (an activity's `activities` field lists its child activity codes), but this projection flattens the graph into a list of activity rows and drops the editable wiring (logic, events, options, activities/child links, sequence, key, internalId). - Each row carries: - - `code` (string) — canonical activity identifier. Well-known codes for the default transport config are `created`, `dispatched`, `started`, `enroute`, `completed`; `canceled` is reserved for cancellations. Treat `code` as the stable identifier and drive UI from it rather than from the row's position in the array. - - `status` (string) — human-readable label (e.g. `Order Dispatched`). - - `details` (string|null) — long-form description. - - `color` (string|null) — hex colour hint for status UI. - - `complete` (boolean) — `true` for terminal activities (e.g. `completed`). Multiple activities can be terminal. - - `pod_method` (string|null) — proof-of-delivery method required by this activity. One of `scan`, `signature`, `photo`, or `null` when no POD is configured. - - `require_pod` (boolean) — whether proof-of-delivery is required to advance past this activity. - Array order reflects how activities are declared in the underlying flow object (insertion order) and is **not** guaranteed to follow graph progression. Consumers needing the workflow sequence should manage the operator console — the public surface does not expose child-activity links. + 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.