Fleet Connectivity Extension API 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.
In the Fleet Connectivity Extension API, the information is captured as messages representing jobs, events, and updates.
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.
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).
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).