Developer Guide

Prerequisites

Before data that is sent to the API can be routed to field responders, IamResponding will need several pieces of information:

• A unique criteria for triggering an incident.alert to be delivered to a field agency (i.e. a new incident.details.id field value has been received).
• If the x-recipient-id header is not being used in the API call, it will be necessary to identify a data field that specifies which field agencies the data should be delivered to (i.e. "Station_ID", "agency", etc.). See the Routing Incident Data section for more information.
• A field that specifies a unique identifier for the incident that is common to all agencies assigned to the incident.(i.e. "incident_ID", "EID", etc.)
• If the IaR CAD Incident Schema is not being used to send data, it will be necessary to provide IamResponding with guidance for how to map fields from the incoming data to the IaR schema fields so that the information can be correctly presented in the IamResponding mobile application. See the section on Data Format and some examples.

This information should be provided to [email protected].

If data is sent in a format other than the IaR Incident Schema, API calls may fail until IamResponding has implemented a receiver for the nonstandard data.

Authentication

An API key is required to send data to the IaR CAD Incident API. This API key must be included in the x-api-key header field in the HTTP POST request. To obtain an API key, please contact [email protected].

API Endpoints

CAD incident data can be sent to the API via a HTTP POST endpoint.

Routing Incident Data

There are two methods than can be used to route CAD Incidentdata to specific IamResponding subscriber agencies:

Method 1 - X-Recipient-Id Header in the HTTP POST request

When this method is used, the CAD system making the API calls is responsible for specifying which IamResponding subscriber agencies should receive the data that is being sent. Each IamResponding subscriber is assigned a unique Recipient Id. Populating the HTTP POST request with one or more X-Recipient-Id headers.containing the agency Recipient Id(s) will route the data to the specified agencies. To obtain a list of IamResponding Recipient Id values for your jurisdiction, please contact [email protected].

Sample Recipient Id Table

Method 2 - Routing via CAD data field

When this method is used, a field in the received CAD data is used to route the data to the appropriate IamResponding subscriber agencies. For example, if the CAD data contains an agency field, the value(s) in that field can be mapped to specific IamResponding subscriber agencies. This mapping is performed by the IamResponding CAD Incident routing system. API users wishing to use this routing method must provide IamResponding with the name of the data field to be used for routing along with a table that specifies which values in the field map to the IamResponding subscriber agencies. Please contact [email protected] to set up CAD field incident routing.

Sample Field Mapping Table

Data Format

Regardless of which endpoint is used, the preferred data format is JSON using the IaR CAD Incident Schema. However, other data formats can be ingested and utilized.

If the data will be sent in a format other than the IaR schema, please provide data samples to [email protected] along with how fields in the data that is provided should be mapped to the fields in the IaR CAD Incident Schema. Examples can be found here.

Data Display in the IamResponding mobile app

This section shows how the data fields in the IaR CAD Incident Schema are presented to field responders in the IamResponding mobile app.

Incident Header Data

Certain data from the incident.Header data object will be presented in the IamResponding mobile app as shown:

Incident Details Data

All data from the incident.details object will be presented in Key: Value format in the Incident Details portion of the Incident Card in the order shown below. Data sent to the API may include additional fields in the incident.details object that are not described in the IaR CAD Incident Schema and they will still be displayed in this area underneath the standard schema fields.

911 Caller Data

All data from the incident.details.callers array will be presented in Key: Value format in the 911 Caller portion of the Incident Card in the order shown below. Data sent to the API may include additional fields in the caller objects that are not described in the IaR CAD Incident Schema and they will still be displayed in this area.

Incident Units Data

All units from the incident.units array with status field values of "Dispatched", "Enroute", and "On Scene" will be grouped in the top three areas of the Units portion of the Incident Card as shown below. Units with other values in the Status field will be displayed lower in the card.

Incident Comments

All Comments in the incident.comments array will be displayed in the Comments portion of the Incident Card as shown below. The newest comments will be at the top of the display with a red dot indicating that the comment is new since the last time the data was viewed.

Data Field Mapping Examples

Data formats other than the IaR CAD Incident JSON schema can be consumed if documentation is provided that describes how to map the incoming data into the IaR CAD IncidentJSON schema fields. Some examples of this type of documentation are provided below.

Mapping to Spillman CAD fields

Sample output from Spillman CAD:

Sample Field Mapping Table for Spillman CAD

Note Even though zone is not a standard field in the incident.details object, additional fields can be added to this object that may be of local interest. These fields will be shown in the Incident Details view in the IamResponding mobile app.

Mapping to IMC CAD Exchange fields

Sample output from IMC CAD Exchange:

Sample Field Mapping for IMC CAD Exchange

Note Even though zone and district are not standard fields in the incident.details object, additional fields can be added to this object that may be of local interest. These fields will be shown in the Incident Details view in the IamResponding mobile app.

Mapping to Intergraph fields

Sample output from Intergraph CADlink:

Sample Field Mapping Table for Intergraph CADlink

Mapping to GenConex CAD fields

Sample output from GenConex CAD:

Sample Field Mapping Table for GenConex CAD

Mapping to SouthernSoftware CAD fields

Sample output from SouthernSoftware CAD:

Sample Field Mapping Table for SouthernSoftware CAD

String Replacement in Data Fields

In many cases, CAD systems transmit data for some fields using abbreviations or codes that may be difficult to interpret. Defining string replacement criteria allows the IamResponding incident. API to present that information to the user in a more human-readable form for easier viewing. An example of the type of data that can be provided to IamResponding to configure field string replacement is shown below.

Example unit.id String Replacement

Example unit.status String Replacement