AdminConsole
Stateful journeys/Routes & Navigation
statefulincident aggregate
Search + Routes + InTouch · command and evidence lifecycle

Coordinated incident response

Resolve an incident location, select a capable available responder, route and observe the unit, adapt to hazards, establish arrival, resolve with evidence, and review every decision.

Open implementation workshop Run verified appExplore lifecycle
Lifecycle state machine

Every state means something operational

A state is not a UI label. It determines which actor may act, what evidence exists, what may be retried, and how recovery proceeds.

01
reported

Reported

A stable CAD or operations identifier, incident type, severity, caller reference, required capability, and location intent are recorded.

02
located

Located

A provider-backed Mappls identity, coordinate, formatted address, confidence, and resolution method are committed.

03
dispatched

Dispatched

A capable available unit is selected with matrix ETA, route identity, constraints, and attributable rationale.

04
en_route

En route

The assigned unit accepted and current event-time telemetry drives route progress and ETA.

05
on_scene

On scene

Distance, speed, and dwell policy establish arrival; scene hazards and coordination remain active.

06
resolved

Resolved

Outcome, responsible responder, and external evidence references are committed.

07
reviewedterminal

Reviewed

A commander signs off the replay, disposition, response timings, telemetry count, hazards, and evidence completeness.

Command → decision → event

Transitions are attributable and retry-safe

Commands express intent. The aggregate validates current state and invariants, commits one new version, and emits a fact in the same transaction.

Command & actorAllowed fromResultIdempotency strategy
report_incidentCall taker
new aggregate
reportedincident.reported

Use the external CAD or operations identity across retries.

resolve_locationDispatcher
reported
locatedincident.located

Bind the accepted candidate, method, confidence, and operator decision to one command.

dispatchDispatcher
located
dispatchedincident.dispatched

Compare incident version and reserve the selected unit under the same command identity.

accept_dispatchResponder
dispatched
en_routedispatch.accepted

The assigned unit generates and persists a command ID before transmission.

record_positionTelematics service
en_route
en_routeunit.position_recorded

Use provider event identity and preserve event and receipt time.

confirm_arrivalResponder
en_route
on_sceneincident.arrived

Bind distance, speed, dwell, policy version, and incident version.

resolveResponder
on_scene
resolvedincident.resolved

Commit outcome, responder, evidence manifest, and outbox atomically.

reviewIncident commander
resolved
reviewedincident.reviewed

Review identity and incident terminal version form the stable key.

Durable records

Persist enough to recover and explain

Keep provider responses, business identity, state, events, and side-effect delivery distinct so each can be reconciled safely.

Incident aggregate

Business identity, lifecycle, location, assignment, hazards, outcome, and review.

incidentIdexternalIncidentIdstateversionseverityrequiredCapability

Location decision

Provider-backed location and human confirmation evidence.

mapplsPincoordinateformattedAddressmethodconfidence

Assignment decision

Capability, availability, matrix, route, constraints, and selection rationale.

unitIdrouteIdcapabilitiesetaselectedByreason

Telemetry envelope

Immutable responder position and vehicle evidence.

providerEventIdunitIdeventTimereceivedTimepositionquality

Review record

Attributable disposition and metrics derived from committed events.

reviewerdispositiontimingspositionCounthazardCount
Non-negotiable rules

Protect truth at the aggregate boundary

  1. 1

    One external report maps to one incident aggregate.

  2. 2

    Only available units with the required capability are eligible for ranking.

  3. 3

    A unit is assigned to at most one active incident in the same operational context.

  4. 4

    Only the assigned unit can accept dispatch and publish operational telemetry.

  5. 5

    Raw telemetry preserves event and receipt time; late evidence never regresses latest state.

  6. 6

    Arrival requires explicit distance, speed, and dwell evidence.

  7. 7

    Resolution cannot occur without external evidence references.

Failure and recovery

Know what to do before it breaks

Recovery changes durable truth only through the same rules as normal operation. A timeout is an unknown outcome, not evidence that nothing happened.

Caller location is ambiguous

Detect

Search candidates are low-confidence, far apart, or conflict with caller/device context.

Recover

Keep the report unresolved, ask a targeted confirmation question, and record the chosen candidate and reason.

Two dispatchers select the same unit

Detect

Unit reservation or incident expected version conflicts.

Recover

Return the current assignments and require an intentional new selection from refreshed availability.

Telemetry is late or out of order

Detect

Event time is behind the incident position watermark.

Recover

Store it, emit a late-evidence event, and do not replace latest route progress.

Route becomes unsafe after dispatch

Detect

A new hazard, closure, or restriction intersects the current route or approach policy.

Recover

Record the hazard, calculate a versioned replacement route, and keep the last safe guidance until accepted.

Resolution side effects fail

Detect

Incident is resolved while notification or downstream outbox entries remain pending.

Recover

Retry the outbox independently; never re-resolve the incident to trigger delivery.

Operational telemetry

Observe the journey, not merely HTTP status

Measure state age, event health, retries, reconciliation, and sensitive-data access alongside latency and error rate.

  • Report-to-location and call-to-dispatch time
  • Eligible responder count and rejected capability reasons
  • Matrix ranking, selected unit, override, and route latency
  • Telemetry freshness, ordering lag, and route revision
  • Hazard age and approach-policy changes
  • Arrival evidence pass/fail and override rate
  • Scene-to-resolution time and evidence completeness
  • Outbox backlog and review completion
Grounded implementation

Contracts, repositories, workshops, tutorials, and runnable evidence

Only explicitly indexed evidence is linked. Empty sections are not backfilled with invented endpoints or package names.