2. Is the tracking URL from the same company as the integration?
4. Segment dispatch vs. tracking dispatch
6. Review of IDs according to the Carrier Equipment Report
8. Errors and their interpretation
List all vehicles error - Error message: status - 403, {"error_message":"invalid API key"}
List all vehicles error - Error message: timeout when calling Motive API.
Location failed to update - Error message: status - 403, {"error_message":"invalid API key"}
Location failed to update - Error message: No match for vehicle id on our end
10. Ensure dispatch of the unit
11. Carrier side token visibility
1. General or one-time error?
When an error is detected in a GPS integration, the first recommended step is to understand if it is a punctual error in a specific reading, or on the contrary it is a general error that affects the entire segment and the integration never started working.
How to check
We can go to the tracking tab of the segment in question and view the tracking logs history.
We can open the notification channels of the GPS in question, either in the error channel or in the log channel, and see if the same message is recurring or not.
How to analyze it
- Did the automatic integration never started working? This is a general error in the integration and we need to go further in Troubleshooting.
- Has it been tracking well in automatic prior to the error and only missing a few readings at the moment or intermittently? Then it's probably coverage, we make a note of it, let it sit for a few minutes for a couple more calls and check again. Sometimes it's not a failure of the integration, but simply that the unit has lost coverage for a specific time.
- Has it been tracking fine all the way through...and suddenly stopped tracking 3-4-5 readings ago? Perhaps it has arrived at the destination and we have already been taken out of visibility even though we still have it in our system in In Transit status. If the integration works through token credentials (or another type of credentials such as User, Password, etc) it is recommended to contact the transport line to confirm that the unit arrived at destination and this is the reason why they have cut the visibility of the token. In this case, remember that ideally the token should be active globally, without having to add and remove units to it, precisely to avoid these situations and that the token becomes a process similar to the mirror account generation process in each load. It is recommended to invite the carrier to leave the visible units in the token, instead of adding and removing them.
2. Is the tracking URL from the same company as the integration?
It is common that a carrier does not have 100% of its fleet tracking with the same GPS.
There are situations where, for example:
- They are migrating from one GPS to another, and they have % of the fleet with one GPS and another % with another GPS.
- The installation of the GPS in the line is recent, and there are some units still to be installed due to complications in the appointments.
- The dispatched unit belongs to a business partner or permit holder, which has a different GPS than the main transport line. (In fact, thanks to GPS integrations, illicit third-party contracting practices are sometimes uncovered).
- Etc.
For these reasons, even if the integration and dispatch are correct, the integration throws an error, because the system tries to track with the available integration, but when the call is made, it is empty because the unit is tracking with a different GPS solution.
How to check
We can go to the tracking tab of the segment in question and check the mirror account (CE) provided as a manual tracking back up.
How to analyse it
- If the EC and the integration belong to the same GPS, continue with the troubleshooting.
- If the CE provided does not correspond to the integrated GPS, it is recommended to:
- Confirm with the transport line that the data is correct, and that the unit will not track via integration with that GPS.
- Disable automatic tracking, so as not to receive recurring notifications on the channel causing unnecessary noise.
- Switch to automated tracking via cellular Fr8App.
- In case the carrier or operator does not operate Fr8App cellular, switch to manual tracking via mirror account.
- Contact your integration department to start carrier integration with the newly detected GPS.
3. Segment Status
At this point, it is recommended to look at the current status of the segment.
How to analyse it
- If the integration works, for example, through token credentials (it can also be through credentials such as User, Password, etc...) and the load is in the final status of the load life cycle, such as In Destination, Delivery Appointment Confirmed, Box in Delivery Yard, etc., it is very likely that the carrier has removed the visibility of the unit within the token. In this case, it is recommended to confirm this fact with the carrier and change the status of the load, and take the opportunity to talk to the carrier to invite them to switch to a global read token to avoid these problems in the future instead of unit visibility at specific times.
- If the load is still In Transit, and there is no visibility, move forward with troubleshooting.
4. Segment dispatch vs. tracking dispatch
The BO dispatch data in the SEGMENTS and TRACKING tabs must match.
Be careful because only the FIRST time the status Dispatched is set in the segment tab, the data is automatically copied to the corresponding segment in the tracking tab.
If you then edit the fields in the segment tab, they will NOT be automatically applied to the TRACKING tab. It is necessary to go to the tracking tab to dump the new data manually.
5. Check critical fields
GPS integrations have some critical dispatch fields that must be correctly filled in for the integration calls to work correctly.If these critical fields are not filled correctly, the integration will not work.
Please review in detail the critical fields for this integration to work.
Note that some integrations, the critical fields are optional (e.g. tractor id OR tractor plates), while others are mandatory (e.g. tractor id AND tractor plates).
A typical error is to have made an incorrect dispatch at initial loading times, putting dummy data in the fields (e.g. ND, AAA, PTE or similar), and then forgetting to update this information.
Another typical error is to have copied extra spaces in the dispatch fields, before or after the data, so that although not visible, the data in the field did not match the data available in the GPS database. Since July 2023, our platform has been modified so that the spaces are not read, and this is no longer a reason for error in the integration calls.
In the case of Motive (Gomotive), the critical fields are the TRACTOR NUMBER or the BOX NUMBER.
6. Review of IDs according to the Carrier Equipment Report
Some integrations have a Carrier Equipment Report, which details the IDs assigned to the units by the carrier.
What is a Carrier Equipment Report and what is it for?
Let's imagine that a carrier has a tractor with ID A-95.
When the carrier dispatches the unit to us, it tells us the data as A95, a95 or similar.
But the day they registered it in their GPS platform, as they all started with A-, they recorded them with 95 only.
In all cases, we are talking about the same unit...but there are differences in its identifier, and when our platform asks for that unit in transit to the GPS, if the data does not match 100%, it will return an error response.
For this reason, some GPS integrations have a Carrier Equipment report, where we can search the unit IDs, to understand the exact ID that should be asked for in the location call.
How to analyze it?
At this point of troubleshooting:
- We will check if this GPS integration has a Carrier Equipment Report or not.
- If it does, we will look for the unit in the report. Here we recommend to do a wide search: try by id, by license plate, with dashes, without dashes, with letters and without letters, etc.
- In case the unit is found: check that the id of the report and the id registered in the box match 100%.
- If it was correct and they already match 100%, continue with the trouble shooting.
- If it was not correct, and there were small differences: correct the data in the tracking box with the new id, and wait for the next GPS call to check that it works.
- If no similar unit is found in the equipment report, it may be because the wrong unit has been dispatched, or the unit is correct but not visible in the integration token. In either case, talk to the carrier to discuss the situation.
Motive (Gomotive) DOES have a Transport Equipment Report.
7. Multitracking check
What is multitracking?
Multitracking is the possibility to add several GPS integrations to the same carrier.
How does multitracking work?
In the call, if there are several integrations for the same carrier, each one is called in an integration order for that carrier.
This used to cause errors to appear on unused channels.
For example:
- CARRIER 1 is integrated for Samsara, Webfleet and Monarch.
- A new segment appears in transit for the carrier.
- We ask coordinates to the 3 integrations.
- If that unit tracks with Samsara, errors will appear in the Webfleet and Monarch channels and caused a lot of unnecessary noise in the channels.
Error -MULTITRACKING
The solution is the following: the error will only appear on the channel of the last GPS in the list.
In the previous example:
- A segment of CARRIER 1 from before for reason x, brings mirror account of XXX (does not correspond to any of the 3 integrations), or simply does not bring CE because we are integrated but none of the 3 gets to work.
- The call will go first to Samsara, no answer, then it will go to Webfleet, no answer, then it will go to Monarch, no answer. Then it will dump an error IN THE CHANNEL OF THE LAST GPS IN THE LIST, ENDING IN -MULTITRACKING.
- Thanks to this distinction, we should already know that none of the 3 integrations worked, but we are only being warned on the channel of the last one so as not to have unnecessary noise on all channels.
How to deal with Multitracking error
- We should check all available integrations following their troubleshooting,
- and/or talk to the carrier to understand this particular segment, which GPS solution it should work with to fine tune our bug fix.
8. Errors and their interpretation
The different error messages that you will receive in this GPS integration are detailed below, so that you know how to interpret them.
Some integrations will have two types of errors:
- Errors called on point: These are general errors of the integration, not of a specific unit in transit. They serve to warn about the status of a carrier's tokens in general. Several messages can be accumulated in the on-point calls, which tend to be recurrent as they are general errors that cannot be repaired in a few minutes. However, we should not ignore them or fail to react to them, because important new errors may slip through the cracks. We must review, identify and react to each of them on calls.
- Errors called every x minutes: These are errors of a specific unit in transit.
As a general rule, when the integrations have positioned correctly at some point and you start receiving error messages without having touched anything on the development side (as long as the information entered in the segment is correct -trailer, tractor, name and/or license plates-), the problem is on the GPS provider's side.
There may be several reasons for the failure, such as temporary loss of visibility, expiration of credentials, unit positioning errors, positioning device failure, etc.
Errors called on point
List all vehicles error - Error message: status - 403, {"error_message":"invalid API key"}
This error indicates that the API Key we had has expired and we have to contact the carrier to generate a new API Key following the steps described in the article Requirements for Integration via Motive (Gomotive) and provide it back to us.
List all vehicles error - Error message: timeout when calling Motive API.
This error indicates that it has taken longer than allowed to get a response from the GPS provider's server.
It can be due to multiple reasons and must be taken into account:
- If there has been previous positioning, the error is on the supplier's side.
- If the error is punctual: it can be ignored
- If the error persists for a long time and no locations have been obtained between errors: contact the supplier as it may be due to significant visibility loss of the unit or equipment failure.
Errors called every x minutes
Location failed to update - Error message: status - 403, {"error_message":"invalid API key"}
This error indicates that the API Key we had has expired and we have to contact the carrier to generate a new API Key following the steps described in the article Requirements for Integration via Motive (Gomotive) and provide it back to us.
Location failed to update - Error message: No match for vehicle id on our end
This error indicates that we don't have visibility into the unit we're requesting in the call because there's a mismatch between the trailer ID we're requesting and the ID registered on the GPS provider's platform.
How to respond to this error:
- Make sure the trailer ID or name entered in the segment tracking tab is correct. To do this, check the units for which we're receiving positioning in this integration for that carrier using the Carrier Equipment report. If it's correct and this wasn't the reason, check the unit's dispatch again.
- If the dispatch and ID are correct, it means the token isn't globally readable, but rather units are being added and removed. You should call the carrier with two objectives: request visibility into the unit in transit, which is showing an error, and request that the token be converted to globally readable to avoid these human errors in future shipments.
9. Carrier specific errors
Sometimes errors are due to carrier specific circumstances that affect your integration even though the integration per se is working properly.
We recommend that as you progress in the use of this GPS integration, you dedicate some space to record recurring errors with your carriers, to identify them and work with the transport line.
10. Ensure dispatch of the unit
At this point, it may be a human error in dispatching the unit.
Steps to follow:
- Internally, by mirror account. Despite having integration, in case these fail, the recommended good practice is to always have a mirror account of the segment available as a back up. Open the provided EC, and check if the moving unit data coincide with the data dumped in our system. Sometimes, thanks to this, we realize that the EC belongs to a different unit than the one indicated in the dispatch. This usually happens when there was a last minute unit change that was not updated correctly in BO.
- Internally, through communications of the operation. Before leaving talk to the carrier, check first if it is an internal error, rechecking again that the dispatch data dumped into BO is correct.
- Externally, talking to the carrier. Talk to the carrier to recheck the dispatched unit.
If the data was correct, continue with troubleshooting.
If there was human error in the data, correct and wait for the next call to see if it tracks automatically.
11. Carrier side token visibility
At this point, maybe the integration is fine and the data is fine...but the token (or User, Password, etc...) we were given was for reading specific units and not global read...and maybe the carrier's dispatcher has not added the unit to be visible in our account.
Proceed by calling the carrier, dispatcher contacts, and ask them to recheck if we have visibility of that specific unit, and take the opportunity to invite them to switch to GLOBAL READ.