Best practices for synchronization
The WebSocket is not a RESTful service
Though it can be used as such, you'd be much better served by writing a daemon to manage communication between your system and ours. In doing so, there are a few things to consider when trying to maintain synchronization with our service.
- JSON version keys and when to merge synchronized data.
- Processing and transmission time for collecting a list of resources.
- Synchronization messages are delayed up to 1 second before being sent to the client.
Version keys
Every subscribable object in Fleet Freedom comes with one or more version keys in an array. The array is always the "v" key on the object; like assetGeneral { "v": [123] }. Every time the object is updated by a user, an automated system, or some other factor, the version key value is incremented by 1. So, you should only accept a new message if the version key is greater than the one you have already. Accepting a message with the same version key should be redundant.
Processing and transmission time
The moment the server receives a request for a list of resources, it begins to gather the required data and collate it for transmission to the client. However, time passes between the time you start transmitting your request, and more time passes between the server receiving the request and starting to process the data, and more time again passes between data processing and transmission to the client. Because more than 0 time passes between request and response, it's possible that one or more resources can be updated before a list of resources is sent. If you wait to subscribe until after receiving the initial list, it's possible (but unlikely) you will miss some synchronization messages.
Synchronization delay
The system uses internal timers to delay the sending of resources being changed at a high frequency. A prime example would be a device that recently re-entered cellular coverage forwarding a bulk of historical messages. In this case, the system processes those messages as quickly as possible, but does not send every single message as it is processed. Instead it will wait for up to 1,000 ms before sending the most recent version (at the time) to the client. You can detect missing messages by checking that the version keys have only incremented by 1. To retrieve a missing resource change, you can run a report or perform an audit-get.
And so, because of the above considerations, we always recommend the following order of commands to ensure you have the latest versions of all objects.
tl;dr
- Subscribe to synchronization updates.
- Send the get__List command.
This order of operations means you may receive a synchronization message before the full resource list response is transmitted to you. In those cases, use the version keys of the objects to ensure the correct information is kept.
If you are using the Fleet Freedom JavaScript API, then it will handle all the synchronization for you.