The Atlas Labs MobileCAD API supports realtime bidirectional communication with integrators using the WebSocket protocol. Use of the WebSocket protocol enables integrators to receive data such as timestamps in realtime, alleviating the need for polling.
On top of the WebSocket protocol, Atlas Labs uses the SignalR library for Remote Procedure Calls (RPC) on certain library functions. For example, when timestamps are received by the API from the field clients, timestamp information is forwarded to the connected WebSocket clients using SignalR Hubs. For additional information on SignalR, visit www.asp.net/signalr.
For integrators not using the .NET Framework, a Java client is available at github.com/signalR/java-client.
In order to interact with the API using the WebSocket protocol, a client must be successfully authenticated and must include the bearer token in the Authorization header. See the
Authentication Example for sample code on obtaining an authentication token.
Once an authentication token has been obtained, it may be used with the SignalR hub as follows:
HubConnection atlasHub = new HubConnection(baseUrl /* https://api.atlaslabs.io */);
atlasHub.Headers.Add("Authorization", "Bearer " + token /* string variable containing token contents */);
atlasHub.Start().Wait();
Timestamp data is exchanged with the Atlas Labs API using SignalR hubs. The hub of particular interest here is DispatchHub and includes the following
RPC functions:
The OnUpdateJobTimestamp method is called on the client by the server when a timestamp is received from a vehicle. Upon receipt of the timestamp, the CAD system should notify the client
of acceptance or rejection of the timestamp by calling the JobTimestampProcessed hub method.
HubConnection atlasHub = new HubConnection(baseUrl);
atlasHub.Headers.Add("Authorization", "Bearer " + token /* string variable containing token contents */);
atlasHub.Error += ex => Console.WriteLine("SignalR error: {0}", ex.Message /* ex is an Exception object */);
atlasProxy = atlasHub.CreateHubProxy("DispatchHub");
// Method called on client from server. TimestampDto is object type sent from server.
atlasProxy.On<TimestampDto>("OnUpdateTimestamp", ts => Console.WriteLine("Timestamp received: " + ts.StatusDisplay));
// Start connection to server
atlasHub.Start(new WebSocketTransport()).Wait();
JobTimestampProcessed is an API method called by the CAD system when a timestamp has been rejected or accepted. When called by the CAD system, the timestamp result is forwarded
to the MobileCAD client indicating the success or failure of the attempted status change. The following illustrates use of the JobTimestampProcessed hub method:
public void AcceptTimestamp(TimestampDto ts)
{
// JobTimestampProcessed sends a ResultDto containing a copy of the original timestamp along with Success = true (if accepted)
ResultDto<TimestampDto> result = new ResultDto<TimestampDto>(ts);
result.Success = true;
atlasProxy.Invoke("JobTimestampProcessed", result).Wait();
}
public void RejectTimestamp(TimestampDto ts)
{
ResultDto<TimestampDto> result = new ResultDto<TimestampDto>(ts);
result.Success = false;
result.AddError("No job found with ID " + ts.JobRef.Id.ToString() + " (Ref1 " + ts.JobRef.ExtRef1 + ", Ref2 " + ts.JobRef.ExtRef2 + ")");
atlasProxy.Invoke("JobTimestampProcessed", result).Wait();
}
The following are specific packet exchanges using the WebSocket protocol with the Atlas Labs DispatchHub SignalR hub: