Unlike our 'traditional' range of GPS devices, the "Edge" range of devices use Forwarders to send data to an end point (or end points).
Details on setting up a Forwarder can be found here - Forward Edge Device Data to my Endpoint (Cellular).
See details on the Location Engine here - The Location Engine - Key Concepts
- The Location Engine (LE) is a robust Cloud solution that comprises queues and scalable virtual functions to ensure that messages are processed in order and delivered to the defined Endpoint Server.
- If many devices are set to use a particular connector/forwarder combination, all device data passes through the forwarder queue to be resolved into usable position data
- It is then passed on to the end server
- To prevent any data loss, messages are not discarded until a 2XX response is received from the end server
- If there is an issue with a particular message delivery, the entire queue, for all devices is blocked in order to avoid any data loss.
- "Traditional" devices actually operate similar to this, but the queue is per device - so an issue with a single data record being uploaded to the server only prevents data upload for that device
Key integration notes
- The end server should always respond 2XX and close the connection
- If unknown data fields are present in the message, they should be dropped and 2XX returned so the forwarder can continue transmitting messages
- If the device is not yet enabled on the end platform, the same applies.
Troubleshooting Forwarder Issues
At times, we may not receive data at the end server. This is generally due to:
- One of the above points not being adhered to
- Forwarder configuration issue when first setting up the forwarder
- One of the message types outlined in the integration document not being implemented and then received after a period of time - this is typically the device counter field which is sent infrequently and can slip through initial testing. Though this field should always be implemented.
If a 2XX response is not received, the message is reattempted every 15 minutes, so temporary server issues are tolerated without dropping messages and do not require action on the OEM Server side to resolve.
As all messages are sent through a single queue, not receiving data due to one device may be due to another message in the queue, from a different device, blocking the queue. To track this message down, we can check the forwarder logs.
Forwarder Logs can be viewed either from device Details > Forwarder Logs > Show all Forwarder Logs or from Forwarders > View Logs.
The Forwarder Logs will show any errors returned. Successful uploads are not reported.
The Error Data tab will tell us the message that caused the issue, from there, we can track down the device serial number.
How to Solve?
If this is a temporary server issue, no action is required. Messages are always reattempted every 15 minutes if the server is down etc. Partners should set up their server such that if there is an issue with a specific message (i.e. unknown data field) the message is discarded on the server and a 2XX response is returned so the forwarder may continue uploading data.
However if this is not the case, or the forwarder was not set up correctly in the first place, we may want to 'drop' a message from the OEM Server end.
i.e., in the above example, there is an authorisation error - we may need to add the right Authorization header to our forwarder setup. After checking this setup, the message is still reattempted with the old details, so we may want to drop it.
To drop a specific device's data, disable the device causing the issue (as identified by the serial present in the Error Data)
Once actions has been taken and if you are still not getting any data, disable the device(s) that appears in the Forwarder logs in OEM for some time. This is done from Device operations > Set Enabled > Untick the Enabled box. (It is recommended to leave the device disabled for at least an hour)
This will discard the message with the error data which was blocking the queue. Once we reenable the device, and we have fixed the underlying issues, the queue should continue.