215 lines
7.2 KiB
Markdown
215 lines
7.2 KiB
Markdown
---
|
|
title: "CAD Usage Guide"
|
|
description: "The CAD module stores transient operational state for dispatch activity, assignments, dispatch orders, support requests, group profiles, grouped views, and hydrated UI payloads. CAD state is in-memory and follows the active server or mission lifecycle."
|
|
---
|
|
|
|
## Data Model
|
|
|
|
Most CAD records are flexible JSON objects. The service normalizes important
|
|
IDs and returns structured mutation results for higher-level workflows.
|
|
|
|
Common generated IDs:
|
|
|
|
- Orders: `cad-order:<sequence>`
|
|
- Requests: `cad-request:<sequence>`
|
|
- Assignments usually share a task ID or order ID.
|
|
|
|
## Commands
|
|
|
|
### Activity
|
|
|
|
| Command | Arguments | Returns |
|
|
| --- | --- | --- |
|
|
| `cad:activity:append` | `activity_json` | `OK`. |
|
|
| `cad:activity:recent` | `limit` | Recent activity array JSON. |
|
|
|
|
### Assignments
|
|
|
|
| Command | Arguments | Returns |
|
|
| --- | --- | --- |
|
|
| `cad:assignments:list` | none | Assignment array JSON. |
|
|
| `cad:assignments:assign` | `entry_id`, `assignment_json` | Assignment mutation result JSON. |
|
|
| `cad:assignments:acknowledge` | `entry_id`, `patch_json` | Assignment mutation result JSON. |
|
|
| `cad:assignments:decline` | `entry_id`, `patch_json` | Assignment mutation result JSON and removes assignment. |
|
|
| `cad:assignments:upsert` | `entry_id`, `assignment_json` | `OK`. |
|
|
| `cad:assignments:delete` | `entry_id` | `OK`. |
|
|
|
|
### Orders
|
|
|
|
| Command | Arguments | Returns |
|
|
| --- | --- | --- |
|
|
| `cad:orders:list` | none | Order array JSON. |
|
|
| `cad:orders:create` | `order_seed_json` | Dispatch order mutation result JSON. |
|
|
| `cad:orders:create_from_context` | `context_json` | Dispatch order mutation result JSON. |
|
|
| `cad:orders:close` | `entry_id` | Dispatch order mutation result JSON and removes order/assignment. |
|
|
| `cad:orders:upsert` | `entry_id`, `order_json` | `OK`. |
|
|
| `cad:orders:delete` | `entry_id` | `OK`. |
|
|
|
|
### Requests
|
|
|
|
| Command | Arguments | Returns |
|
|
| --- | --- | --- |
|
|
| `cad:requests:list` | none | Request array JSON. |
|
|
| `cad:requests:submit` | `request_json` | Request mutation result JSON. |
|
|
| `cad:requests:submit_from_context` | `context_json` | Request mutation result JSON. |
|
|
| `cad:requests:close` | `entry_id` | Request mutation result JSON and removes request. |
|
|
| `cad:requests:upsert` | `entry_id`, `request_json` | `OK`. |
|
|
| `cad:requests:delete` | `entry_id` | `OK`. |
|
|
|
|
### Profiles and Views
|
|
|
|
| Command | Arguments | Returns |
|
|
| --- | --- | --- |
|
|
| `cad:profiles:list` | none | Profile array JSON. |
|
|
| `cad:profiles:update_from_context` | `context_json` | Profile mutation result JSON. |
|
|
| `cad:profiles:upsert` | `entry_id`, `profile_json` | `OK`. |
|
|
| `cad:profiles:delete` | `entry_id` | `OK`. |
|
|
| `cad:groups:build` | `groups_seed_json` | Group array JSON. |
|
|
| `cad:view:hydrate` | `hydrate_seed_json` | Hydrated CAD payload JSON. |
|
|
|
|
## Generated Mission Requests
|
|
|
|
Dispatchers can request framework-generated mission tasks from the CAD
|
|
dispatcher board. The server hydrates the available generated task types from
|
|
the task mission manager as `generatedTaskTypes`; the client uses that hydrated
|
|
list for the dropdown.
|
|
|
|
Generated mission requests are controlled by the server CBA setting
|
|
`forge_server_task_enableGenerator`:
|
|
|
|
- Enabled: CAD receives the generated task type list and dispatchers can request
|
|
a specific generator type.
|
|
- Disabled: CAD receives an empty generated task type list, the task request UI
|
|
is disabled, and server-side request handling rejects any manual request.
|
|
|
|
The framework-owned request entry point is
|
|
`forge_server_task_fnc_requestMissionTask`. Server CAD uses this framework
|
|
handler directly; it does not call mission-local generator functions.
|
|
|
|
Custom mission generators can still create CAD-visible tasks directly by
|
|
registering task catalog entries and task statuses. See
|
|
[Custom Mission Generators](/getting-started/custom-mission-generators) for the supported
|
|
integration path and the current generated-task provider limitation.
|
|
|
|
## Submit a Support Request
|
|
|
|
```sqf
|
|
private _fields = createHashMapFromArray [
|
|
["pickup_location", "Grid 123456"],
|
|
["precedence", "urgent"],
|
|
["security", "secure"]
|
|
];
|
|
|
|
private _context = createHashMapFromArray [
|
|
["type", "medevac_9line"],
|
|
["fields", _fields],
|
|
["groupId", "alpha"],
|
|
["groupCallsign", "Alpha 1-1"],
|
|
["submittedByUid", getPlayerUID player],
|
|
["submittedByName", name player],
|
|
["priority", "emergency"],
|
|
["position", getPosATL player],
|
|
["createdAt", diag_tickTime]
|
|
];
|
|
|
|
private _result = "forge_server" callExtension ["cad:requests:submit_from_context", [
|
|
toJSON _context
|
|
]];
|
|
```
|
|
|
|
Supported priority values are `routine`, `priority`, and `emergency`. Unknown
|
|
values normalize to `priority`.
|
|
|
|
## Create a Dispatch Order
|
|
|
|
```sqf
|
|
private _context = createHashMapFromArray [
|
|
["assigneeGroupId", "bravo"],
|
|
["assigneeGroupCallsign", "Bravo 1-1"],
|
|
["targetGroupId", "alpha"],
|
|
["targetGroupCallsign", "Alpha 1-1"],
|
|
["targetPosition", getPosATL player],
|
|
["createdByUid", getPlayerUID player],
|
|
["createdByName", name player],
|
|
["requestId", "cad-request:1"],
|
|
["requestType", "logreq"],
|
|
["requestTitle", "LOGREQ | Alpha 1-1"],
|
|
["requestSummary", "Ammo resupply requested"],
|
|
["requestFields", createHashMap],
|
|
["note", "Support Alpha 1-1 at current position."],
|
|
["priority", "priority"],
|
|
["createdAt", diag_tickTime]
|
|
];
|
|
|
|
private _result = "forge_server" callExtension ["cad:orders:create_from_context", [
|
|
toJSON _context
|
|
]];
|
|
```
|
|
|
|
## Assignment Workflow
|
|
|
|
Task contracts have two separate phases. Dispatch assignment reserves a
|
|
contract for a group and sets the CAD assignment state to `assigned`, but it
|
|
does not accept or start the task. The assigned group leader must acknowledge
|
|
the assignment before task ownership is bound and task logic starts. If the
|
|
leader declines, the CAD assignment is removed and the contract returns to the
|
|
open board. Task status follows the same lifecycle: `available` on creation,
|
|
`assigned` after dispatch assignment, and `active` after acknowledgement.
|
|
|
|
```sqf
|
|
private _assignment = createHashMapFromArray [
|
|
["groupId", "bravo"],
|
|
["assigneeGroupCallsign", "Bravo 1-1"],
|
|
["assignedByUid", getPlayerUID player],
|
|
["assignedByName", name player],
|
|
["assignedAt", diag_tickTime],
|
|
["state", "assigned"]
|
|
];
|
|
|
|
"forge_server" callExtension ["cad:assignments:assign", [
|
|
"task-123",
|
|
toJSON _assignment
|
|
]];
|
|
|
|
private _ack = createHashMapFromArray [
|
|
["state", "acknowledged"],
|
|
["acknowledgedByUid", getPlayerUID player],
|
|
["acknowledgedAt", diag_tickTime]
|
|
];
|
|
|
|
"forge_server" callExtension ["cad:assignments:acknowledge", [
|
|
"task-123",
|
|
toJSON _ack
|
|
]];
|
|
```
|
|
|
|
## Hydrate the CAD UI
|
|
|
|
```sqf
|
|
private _session = createHashMapFromArray [
|
|
["uid", getPlayerUID player],
|
|
["orgId", "default"],
|
|
["isDispatcher", true],
|
|
["groupId", "alpha"],
|
|
["isLeader", true]
|
|
];
|
|
|
|
private _seed = createHashMapFromArray [
|
|
["groups", _liveGroups],
|
|
["activeTasks", _activeTasks],
|
|
["generatedTaskTypes", _generatedTaskTypes],
|
|
["session", _session]
|
|
];
|
|
|
|
private _result = "forge_server" callExtension ["cad:view:hydrate", [toJSON _seed]];
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
```sqf
|
|
private _payload = _result select 0;
|
|
if (_payload find "Error:" == 0) exitWith {
|
|
systemChat format ["CAD error: %1", _payload];
|
|
};
|
|
```
|