> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lmrp.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Incident lifecycle

> How a call becomes an incident, how units attend it, and what closing and reopening do.

## From call to incident

A call is a report from the public. An incident is what Control decides to do about it.

| A call is | Meaning | How it gets there |
| - | - | - |
| `RECEIVED` | Waiting for Control | `POST /api/cad/calls` |
| `ATTACHED` | Belongs to an incident | `/calls/{id}/convert` creates a new incident from it; `/calls/{id}/attach` adds it to an existing open one |
| `RESOLVED` | Needed no incident | `/calls/{id}/resolve` |

`ATTACHED` and `RESOLVED` are final. A call cannot be detached or moved to another incident.

Converting a call creates the incident with the call's location and description, and the priority and type Control chooses. An incident can also be created directly, with no call.

## An open incident

An incident has two states, `OPEN` and `CLOSED`. While it is open:

* **It can be edited.** An edit replaces priority, type, location, description and control notes together.
* **Units can be assigned and released.** Several units can attend; each unit attends one incident at a time.
* **More calls can be attached.**

| Field | Notes |
| - | - |
| `number` | Sequential across all incidents, shown as `CAD-000142`. Gaps are possible; numbers are never reused. |
| `priority` | `IMMEDIATE`, `URGENT`, `ROUTINE` or `LOW`. Open incidents list in this order. |
| `type` | Free text, up to 80 characters |
| `location` | Free text, up to 240 characters |
| `controlNotes` | Control's working notes. Crews assigned to the incident can read them. |
| `version` | Advances on every change to the incident, including assignments and attached calls |

## Units on an incident

```mermaid theme={null}
stateDiagram-v2
    direction LR
    AVAILABLE --> ASSIGNED: Control assigns
    ASSIGNED --> EN_ROUTE: Crew or Control
    EN_ROUTE --> ON_SCENE: Crew or Control
    ON_SCENE --> EN_ROUTE: Crew or Control
    ASSIGNED --> AVAILABLE: Control releases
    EN_ROUTE --> AVAILABLE: Control releases
    ON_SCENE --> AVAILABLE: Control releases
```

Only Control moves a unit onto or off an incident. In between, the crew or Control can move it among the assigned statuses. Closing the incident releases every unit at once.

## Closing

`POST /api/cad/incidents/{id}/close` does three things in one transaction:

1. Releases every assigned unit to `AVAILABLE`, or `OFF_DUTY` if it has no crew.
2. Marks the incident `CLOSED` and stamps `closedAt`.
3. Records one `UNIT_REMOVED` event per unit and an `INCIDENT_CLOSED` event.

Attached calls stay attached. A closed incident cannot be edited, and nothing can be assigned or attached to it.

<Note>
  A closed incident's `units` list is empty, because those units have been released. To see who attended, read the incident's events.
</Note>

Closing records no outcome or reason. That is a known gap.

## Reopening

`POST /api/cad/incidents/{id}/reopen` sets the incident back to `OPEN` and clears `closedAt`. It does not bring back the units that were released; Control assigns again.

## The event trail

Each step leaves an event, readable with `GET /api/cad/events?incidentId=...`, oldest first.

| Step | Events |
| - | - |
| Call recorded | `CALL_RECORDED` |
| Incident created | `INCIDENT_CREATED` |
| Call converted or attached | `CALL_ATTACHED` |
| Incident edited | `INCIDENT_UPDATED`, plus `PRIORITY_CHANGED` if the priority moved |
| Unit assigned | `UNIT_ASSIGNED` |
| Status changed | `UNIT_STATUS_CHANGED`, with `source: "SELF"` when the crew did it |
| Unit released | `UNIT_REMOVED` |
| Incident closed, reopened | `INCIDENT_CLOSED`, `INCIDENT_REOPENED` |

Each event carries `detail` with the before and after values, and `actor`: the display name of the user, the name of the service credential, or `System`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.