Developer's Guide

This guide outlines the process for building software integration solutions between third party dispatch systems and the Atlas Labs MobileCAD API.

This API is implemented using the RESTful type of web services architechural style, including the following conventions:

  • Resources are identified and accessed by URI. For example, the Job with identifier 100 may be operated on via the path api/Job/100. The list of all Jobs may be returned using the path api/Job.
  • Operations to resources are indicated by the HTTP verb used in the request. For example:
    • GET - Return a collection or individual element, depending on URI.
    • PUT - Replace the addressed element or collection. If element does not exist, it may be created.
    • POST - Create a new entry in the collection. The URI for the created entry is returned in the response.
    • DELETE - Delete collection or individual element, depending on URI.
    • PATCH - Change specific fields of element.
  • Client state is not kept by the server. Each request contains all information needed to provide the response. To edit a Job object for example, the client should perform a GET on the URI of the job to be modified. The server will respond with the entire Job object, which the client may modify, then resubmit using a POST.

The previous are just a few highlights of RESTful APIs. Developers should familiarize themselves with REST web service concepts before proceeding, if not already proficient.

Getting Started

Access to this API requires valid credentials. To manage these credentials, log into the administrator portal or contact Atlas Labs Support for additional assistance.

Definitions

This API references nomenclature that may vary between CAD vendors or industries. To prevent ambiguity, integrators should be aware of how Atlas Labs interprets these definitions.

  • Vehicles: Vehicles refer to the physical vehicle as opposed to a shift or crew. Use the Alias field to designate which shift, crew, or assignment is currently associated with a particular vehicle.
  • Destination: A destination represents a location where a vehicle is to stop. This may be in the form of a post assignment, pick up location or scene, or drop off location / destination. Destinations may be directly assigned to vehicles when they are not assigned to jobs, as is typically done for post assignments. If a vehicle is currently assigned to a job, only the destinations within that job may be changed.
  • Job: A Job is the equivalent to a dispatch system's incident, trip, assignment, request for service, etc. A job consists of a collection of destinations (typically two), timestamps, and a service level. Vehicle's may be assigned to multiple jobs at once, but each job may only be assigned to one vehicle.
  • Service Level: Service levels are associated with jobs and indicate the type of service request. At this time, Service Levels in the context of the Atlas Labs API are simply attributes of jobs. Future software releases may use the service level to determine most appropriate vehicle or drop-off locations.

Authentication

User authentication is provided using bearer tokens. The process for logging in is as follows:

  1. Submit username and password to authentication endpoint /Token using HTTP POST. The following fields may be submitted, using x-www-form-urlencoded for encoding:
    • username
    • password
    • grant_type (specify "password" for value)

    A quick verification of your account credentials can be performed using Postman and the following settings:
  2. Assuming valid credentials have been provided, the API will reply with the following json encoded fields in the response body:
    • access_token - This value goes in the Authorization header of subsequent requests and should be prepended with the token type.
    • token_type - Type of token used. This value prepended to the access_token constitutes the Authorization header value.
    • expires_in - Duration token is valid for, in seconds.
    • userName - Username corresponding to this account.
    • .issued - Server time in which the token was issued.
    • .expires - Server time in which the token is set to expire.
  3. Add the token type and token value to the Authorization header for API requests requiring authentication.

See the Authentication example for additional information.

Initialization

Following successful authentication, integrators should initialize their systems by synchronizing the following API objects with customer dispatch platforms.

  • Priorities
  • Service Levels
  • Vehicles

Initialization is typically accomplished by retrieving a list of objects previously defined in the API and comparing against the dispatch system. Any discrepancies should be corrected by submitting updates, deletions, and additions back to the API so as to bring it to the same state as the dispatch system.

Alternatively, Priorities and Service Levels may be added automatically by the API as Jobs are imported, if a Service Level or Priority does not yet exist. Vehicles however are NOT automatically added, and must be created by the integrator, or the user via the Management Portal.

See the Initialization example for additional information.

Work Flow

Once the API priorities, service levels, and vehicles are in sync with the customer CAD system, the API will be ready to receive and process job and destination information.

Job Creation or Modification

Jobs may be created by POSTING a job object to the appropriate URL. If a valid vehicle identifier is specified in the job object, the job will automatically be assigned to the specified vehicle at time of creation.

Vehicle Assignment

If a vehicle identifier is not included when a job is initially created, then a vehicle may be assigned using the Assign endpoint of the Job controller. Conversely, a job may be unassigned using the Unassign action of the Job controller.

Timestamping / Status Updates

Timestamps may be added to API jobs from customer CAD systems or the Mobile CAD client. When timestamps originate from the Mobile CAD client, they will be added to a queue such that integrators/CAD systems may retrieve them via polling. Alternatively, integrators may receive timestamps in realtime using a WebSocket connection to the API.

See the WebSockets page for additional information on implementation of the WebSockets API interfaces.