Fleet Connectivity Extension API Developer's Guide

Fleet Connectivity Extension API Ecosystem

The Fleet Connectivity Extension API is part of an ecosystem in which a number of components exchange messages. The figure below provides an overview.
Figure 1. Fleet Connectivity Extension API Ecosystem

The physical components in this ecosystem are:

  • Dispatcher – a central function synonymous with an application that manages mobile assets
  • Assets – networked devices typically associated with mobile units in the fleet (for example delivery trucks)
  • Fleet Connectivity Web Service – an on-line service that acts as a conduit for communication between the dispatcher and the mobile assets

The following sections provides further information about these physical components.

Dispatcher

The dispatcher is a central function reponsible for managing mobile assets in the fleet through an application that uses the Fleet Connectivity Extension API. This is a REST API that allows the dispatcher to send jobs to the assets and regularly poll for updates on their status.

In reality, the dispatcher function can make use of one or more physical or logical dispatcher applications with identical functionality and responsibilities to ensure optimal load distribution and fault tolerance. Dispatcher applications can direct and monitor separate or overlapping sets of assets (for example per country or per store).

Asset

An asset represents a mobile unit in a fleet (for example a delivery truck, a car, or a motorcycle) and is capable of running an application created with a HERE iOS and Android Premium Edition SDKs that provides routing services to the asset and interacts with one or more dispatchers via the Fleet Connectivity Extension API. An application can have multiple assets, limited by the number specified in the commercial contract with HERE. Typically, an asset is monitored as it travels towards or from its destination defined by a set of WGS 84 coordinates.

Fleet Connectivity Web Service

The Fleet Connectivity Web Service is hosted by HERE to support communication between dispatcher applications and the mobile assets they manage. It is the pivotal element in the information flow within the ecosystem.

Information Flow

The information exchanged between dispatchers and assets with the help of the Fleet Connectivity Extension API indicates jobs to be carried out, status details, and updates. The figure below shows an example.

Figure 2. Fleet Connectivity Extension API Communication Example

In the Fleet Connectivity Extension API, the information is captured as messages representing jobs, events, and updates.

Job

A job is message containing a package of information that must include at least the geographic coordinates of the destination, but may also include other information depending on the application the asset uses. When a dispatcher sends a job to an asset, the job replaces any previous jobs that were sent to the asset. An empty job without a destination cancels the current destination so that the asset is idle.

Event

An event is a message with information about the status of an asset. It is sent from the asset to the Fleet Connectivity Web Service (through the Fleet Connectivity Extension API).

Update

An update is a message from the Fleet Connectivity Web Service sent through the Fleet Connectivity Extension API to the dispatcher with asset status information. An update may contain one or more events that describe a new estimated time of arrival or status information on a particular job, for example to indicate whether the job was accepted, cancelled, or denied.

Update messages expire after one month regardless of their state, but dispatcher applications should impose a use-case-dependent lower limit on the validity time of an update, usually a few hours. Until a message has expired, the dispatcher can retrieve it as many times as necessary.

Message Delivery, Handling and Expiry

The Fleet Connectivity Extension API does not guarantee to deliver a message to the application using the Mobile SDK within a certain (maximum) amount of time, because the device could be off, there could be network availability problems or the device running the application could be in a region, where a particular data plan does not permit a connection.

Jobs expire after one month regardless of their state, but asset applications should impose a use-case-dependent lower limit on the validity time of a job, usually a few hours. Until a job expires, the asset can retrieve the job message once or multiple times.

The Fleet Connectivity Extension does not maintain or communicate an explicit status of a job. The status can be determined by the application (device and dispatcher) based on the messages that have been received concerening the job. If an asset has received a destination, it computes the route and sends the estimated time of arrival to the dispatcher. This informs the dispatcher that the asset received and accepted the job.

Before receiving a message containing the estimated time of arrival and in between receiving updates, the dispatcher does not know whether the asset is off line or on line. An asset does not know whether or when the dispatcher received its route progress and delay update messages. There is no limit on the number or frequency of update messages for each asset, but the Mobile SDK minimizes the message traffic to save network bandwidth and cost.

For each job, the dispatcher determines how strictly to interpret the estimated time of arrival, that is, what deviation from the estimated time of arrival it allows before it expects notification. An asset must send an initial estimate of the arrival time to inform the dispatcher not only that it has accepted the job and is on its way to the destination, but also because the route calculation by the Mobile SDK may produce a different arrival time estimte than that computed by the dispatcher due to possibly different algorithms, map releases or different traffic information. After the initial estimated arrival time has been sent, and unless any event (traffic jam, accident, etc.) causes a delay, the next message notifies the dispatcher that the asset has reached the destination.

The Fleet Connectivity Extension does not maintain or communicate an explicit status of an update message. Hence, if multiple dispatchers are watching for update messages, they cannot know whether another dispatcher has already read or reacted to an update message. Also, assets cannot know whether a dispatcher has recieved their update(s).

Push or Pull Messages

Dispatchers can either poll periodically for new messages, or keep a long polling call open, which Fleet Connectivity Extension API only returns after something new arrived. The second option is preferred, because it minimizes the network and server utilization as well as the delay until a new message arrives at the dispatcher. Whenever the connection is lost or the server returned an empty response due to a timeout or too high number of connections, the dispatcher should simply launch the next long polling call, after a short wait time.

Assets can do the same like dispatchers, with the same properties. In addition, dispatchers can notify Android bases assets about the arrival of a new message using Google Push (FireBase Cloud Messaging). Therefore, the asset application must register for Google Push messages. Then the app doesn't have to poll or keep long polling requests open. It can even go into the background or become deactivated by Android. Also after phone switsch-off or network interruptions, the push messages arrive asap. Push notifications are empty, they just tell that the asset should call Fleet Connectivity Extension API, because a message is available.

Security

Both the dispatcher application and the asset application use the same set of app_id and app_code credentials to authenticate with the Fleet Connectivity Extension API for each request. The applications should authenticate the service by verifying the server certificate. The Fleet Connectivity Extension API does not use additional authentication or capability/restriction mechanisms. This means the sender_id in a job or event is trusted, and both the dispatchers and all assets have full rights to send and receive arbitrary messages.

You are free to use your existing proprietary authentication and authorization mechanisms on top of the security mechanism described above. Typically, an end user must enter a user name and password into the asset application. Then the asset application uses a defined asset_id for communication with the dispatcher through the Fleet Connectivity Extension API. Similarly, an end user logs in with a user name and password at the dispatcher application. Based on this, the dispatcher application uses a defined dispatcher_id when it communicates with the asset application through the Fleet Connectivity Extension API.