Unified Dispatch
APIEngine's Unified Dispatch is a polling/state-update bridge between SBN and an external eDispatch driver (AMS, IVDispatch, etc.). The driver polls APIEngine for active sessions and queued dispatches, takes ownership of a dispatch, and feeds external-party state changes (ACK, STARTED, ON-SITE, DONE, CLOSED, CANCEL, COMMENT) back into SBN. Each call runs one SBN stored procedure (fe_unif_dispatch_*).
Setup
No APIEngine settings are required; Unified Dispatch uses the normal APIEngine SBN connection. The stored procedures (fe_unif_dispatch_active, fe_unif_dispatch_check_queue, fe_unif_dispatch_status_set, fe_unif_dispatch_get_rec, fe_unif_dispatch_receive, fe_unif_dispatch_error) must exist in the SBN database (delivered with the matching SBN release).
The protocol identifier passed in {id} (e.g. AMS, IVDispatch) filters which dispatch types the calling driver wants to see. The SBN user who owns the driver's token is recorded as the dispatch operator.
Auth
Every route requires an APIEngine token in both versions. v95 and earlier: send it as the User-Token header, query string or form field. v96 and later: Authorization: Bearer <token> is also accepted. All status changes are made as the token's SBN user.
Response envelope
Responses carry Title, ReturnCode, ReturnMessage and ResultSet. The SBN ReturnCode maps to the HTTP status:
| ReturnCode | HTTP |
|---|---|
| 0 | 200 OK |
| 100 | 204 No Content |
| 101 | 404 Not Found (the alarm no longer has an active eDispatch) |
| 102 | 403 Forbidden |
| anything else | 503 Service Unavailable |
Endpoints
| Verb | Route | Purpose |
|---|---|---|
| GET | /api/v1/UnifiedDispatch/active/{id} | Poll for active eDispatch sessions for protocol {id}. |
| GET | /api/v1/UnifiedDispatch/check_queue/{id}/{last_tm} | Poll for new eDispatches ready to send; {last_tm} is the timestamp of the last logline the driver saw. |
| POST | /api/v1/UnifiedDispatch/update_status/{seq}/{ltm} | Acknowledge that the driver has processed loglines up to {ltm} for session {seq}. |
| POST | /api/v1/UnifiedDispatch/take/{s_inc}/{seq} | Driver claims responsibility for a dispatch. |
| POST | /api/v1/UnifiedDispatch/driver_ack/{s_inc}/{seq} | Driver ACK; resets the timeout timer (external party not yet replied). |
| POST | /api/v1/UnifiedDispatch/driver_request_sent/{s_inc}/{seq} | Driver has forwarded the request to the external party. Body: comment string. |
| POST | /api/v1/UnifiedDispatch/extern_ack/{s_inc}/{seq}/{extinc} | External party ACK; {extinc} is the external system's incident id. Body: comment. |
| POST | /api/v1/UnifiedDispatch/start/{s_inc}/{seq} | External party STARTED. Body: comment. |
| POST | /api/v1/UnifiedDispatch/on_site/{s_inc}/{seq} | External party ON-SITE. Body: comment. |
| POST | /api/v1/UnifiedDispatch/done/{s_inc}/{seq} | External party DONE. Body: comment. |
| POST | /api/v1/UnifiedDispatch/closed/{s_inc}/{seq} | External party CLOSED. Body: comment. |
| POST | /api/v1/UnifiedDispatch/cancel/{s_inc}/{seq} | External party CANCEL. Body: comment. |
| POST | /api/v1/UnifiedDispatch/comment/{s_inc}/{seq} | External party general comment/update. Body: comment. |
| POST | /api/v1/UnifiedDispatch/error/{error_id} | Driver reports an error condition; {error_id} is recorded as the alarm zone. Body: error description. |
{s_inc} is the SBN incident number, {seq} is the dispatch sequence number — together they identify a single dispatch instance. The two GET routes are designed to be polled on a short interval by the driver; the rest are event-driven. The routes are the same in both versions.
Comment body (version difference)
Routes marked "Body: comment" take the comment text in the request body.
- v95 and earlier: the raw body is used as the comment, so plain text works (for example
Content-Type: text/plainwith the bodyGuard en route). - v96 and later: the body must be a JSON string with
Content-Type: application/json(for example"Guard en route", including the quotes). Onextern_ackthe comment is optional.{s_inc},{seq},{last_tm}and{error_id}must be whole numbers or the route is not matched (404).