Trucker Tools

Trucker Tools provides GPS/Cell-based tracking of loads via the driver’s (smart) phone or in-cab ELD. The Revenova TMS integration with Trucker Tools provides Carrier load tracking and status updates sent from Trucker Tools and received in the TMS.

Trucker Tools is a Load Tracking API service. See other integration information for Trucker Tools Rate and Load Board API Service article.

Trucker Tools provides “push” status updates to the TMS via a sites-based web service. Inbound load status packets from Trucker Tools are processed as Platform Events.

Setup

Enter Credentials

Enable the Trucker Tools integration by completing the following steps.

1. Navigate to TMS Admin. 

2. Select Credentials. 

3. Select the Global Services tab.

4. Find Trucker Tools in the list and open the card. 

5. Check the Enabled and Receive Updates boxes.

6. Enter the User ID and Password 1 into the text fields.

7. Click the Save button when finished.

Valid credentials are required from a Trucker Tools subscription. Trucker Tools provides the Encrypted Customer Account Number. See examples in the table below.

Inbound Packet IP Ranges: Any load status post-backs from Trucker Tools that do not originate from this IP mask are rejected as a security feature. Any changes to this range are provided by Revenova.

Remote Site Settings

Confirm that all Remote Site Settings are created for the Trucker Tools integration.

Upgrading from previous versions of the TMS may have outdated information. Check that the Remote Site Settings for the Trucker Tools integration URL are up to date.

1. Click the Setup gear icon in the top right corner.

2. From the drop-down, click Setup.

3. In the Quick Find Toolbar type Remote Site Settings and click the link.

4. From the list of remote sites find following Remote Sites and add or edit as necessary.

   1. TruckerTools: https://api.truckertools.com

   2. TruckerToolsDocuments: https://assets.truckertools.com

Partner Community Setup

The Trucker Tools integration requires a webhook to send tracking information to the TMS. Create an API Site to accept inbound API traffic.

1. Create a Salesforce Site for API Guest User Access.

2. Set the public access for the Site.

3. Activate and Publish the Site.

4. Enter the API URL into the field for Inbound API Community URL under TMS Admin, in the Configuration section. 

5. Add the following extension to the end of the URL to match the example below: /services/apexrest/rtms/tmslistener?org=[18-character org id]&source=TruckerTools&pwd=[credentials code field]

6. Send the URL, customer company name, and contact information to integrations@truckertools.com.

{API Community URL}/services/apexrest/rtms/tmslistener?org=[18-character org id]&source=TruckerTools&pwd=[credentials code field]

Example: https://revenova.my.site.com/api/services/apexrest/rtms/tmslistener?org=00D180000008oA9EAI&source=TruckerTools&pwd=4wGFDgnT950Ovg1

The Salesforce-generated API Community URL is case sensitive.

TMS Admin

Configuration

The following field may be set under TMS Admin, Configuration to use as default tracking settings when using Trucker Tools.

Tracking Update frequency (Minutes): The number of minutes between inbound load location updates from Trucker Tools. The TMS does not process load location updates less than the entered value since the last load location update.

Use Platform Events For: Confirm the check box for TruckerTools is checked.

Transportation Profile

It is possible to set a default Tracking Provider for each Carrier on their Transportation Profile.

Tracking Provider: The default selection in the Load Tracking Admin LWC of tracking information for a load. 

The Trucker Tools integration supports multiple stops for the same Account location. Tracking notifications indicated Stops as Picked Up or Delivered.

Carrier Load Tracking

Carrier load tracking is initiated on the Carrier Banner LWC. Click the antenna button to open the Load Tracking Administration LWC to begin tracking the load. 

Start and stop a tracking session by clicking the On and Off buttons. Active tracking sessions may be updated by changing load information and then click Update Tracking.

Load Field Set TMS35, Transportation Profile TMS7, and Transportation Profile TMS8 can be adjusted to display additional fields in the Load Tracking Administration modal. See the Field Set Summary for more information.

Start Load Tracking

The start new load tracking call sends load, Carrier, and stop information to Trucker Tools. The Tracking Number field is returned. The Start Time field on the Load Tracking Administration modal defaults to the appointment time of the pickup stop.

If an org contains multiple loads with the same Load Number, the tracking sessions with Trucker Tools may provide incorrect data. When a Start Load Tracking request is sent for a Load Number that already exists in the Trucker Tools system, the existing load is overridden with the most recent load information.

Sample Start Load Tracking JSON Request Payload

{
  "partnerId": 0,
  "loadTrackExternalId": "string",
  "accountId": "stringst",
  "loadNumber": "string",
  "dispatcherId": "string",
  "dispatcherEmail": "string",
  "dispatcherPhoneNumber": "string",
  "textmessage": "string",
  "loadType": "string",
  "trailerType": "string",
  "revenueType": "string",
  "autoStartTime": "hh:mm",
  "driverCell": "string",
  "trailerNumber": "string",
  "truckNumber": "string",
  "driverName": "string",
  "driverType": "companyDriver",
  "driverComments": "string",
  "loadNotes": "string",
  "isTeamLoad": false,
  "carrierDispatcherEmail": "user@example.com",
  "carrier": {
    "CompanyName": "string",
    "docketNumber": "string",
    "contactName": "string",
    "contactPhone": "string",
    "contactPhoneExt": "string",
    "contactEmail": "user@example.com"
  },
  "broker": {
    "companyName": "string",
    "docketNumber": "MC456123",
    "contactName": "string",
    "contactPhone": "string",
    "contactPhoneExt": "string",
    "contactEmail": "string"
  },
  "shipper": {
    "loadNumber": "string",
    "name": "string",
    "shipperId": "string",
    "emails": "string",
    "emailInterval": 0
  },
  "metadata": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "stops": [
    {
      "orderNumber": 1,
      "address": "string",
      "city": "string",
      "state": "VA",
      "zipcode": "20148",
      "lat": 0,
      "lon": 0,
      "datetime": "10/14/2021 12:14:45 EST",
      "geofenceRadius": 0,
      "notes": "string",
      "stopExternalId": "string",
      "metadata": [
        {
          "name": "string",
          "value": "string"
        }
      ]
    }
  ],
  "actions": [
    {
      "name": "string",
      "driverInput": false,
      "options": [
        {
          "name": "string"
        }
      ],
      "required": false,
      "isLastAction": true,
      "item": "trailer",
      "id": "string"
    }
  ]
}

The Stop Appointment Time fields are sent as part of the start tracking call, if they are available. If not available, the Shipping/Receiving Hours are sent.

Error - Carrier Banner: Unable to tunnel through proxy. Proxy returns "HTTP/1.1 503 Service Unavailable.

This error means that the Trucker Tools webservice is down. This error is resolved when Trucker Tools webservice is restored.

Sample Start Load Tracking JSON Response Payload

{
  "status": true,
  "timeStamp": "string",
  "loadId": 0,
  "mapLink": "string",
  "statusPageLink": "string",
  "detailsLink": "string",
  "errorCode": 101,
  "errorMessage": "Account not found"
}

TMS Field Updates

See Trucker Tools Create Load Track documentation here.

Update Load Tracking

The update tracking call sends new load and stop information to Trucker Tools. See the table below for unacceptable field changes.

When fields require changing from the Unacceptable table below, stop the current tracking session. Make any necessary changes in the TMS, and then begin a new tracking session.

Unacceptable Changes

Sample JSON Update Tracking Request Payload.

{
  "partnerId": 0,
  "loadTrackExternalId": "string",
  "accountId": "stringst",
  "loadNumber": "string",
  "dispatcherId": "string",
  "dispatcherEmail": "string",
  "dispatcherPhoneNumber": "string",
  "textmessage": "string",
  "loadType": "string",
  "trailerType": "string",
  "revenueType": "string",
  "autoStartTime": "hh:mm",
  "driverCell": "string",
  "trailerNumber": "string",
  "truckNumber": "string",
  "driverName": "string",
  "driverType": "companyDriver",
  "driverComments": "string",
  "loadNotes": "string",
  "isTeamLoad": false,
  "carrierDispatcherEmail": "user@example.com",
  "carrier": {
    "CompanyName": "string",
    "docketNumber": "string",
    "contactName": "string",
    "contactPhone": "string",
    "contactPhoneExt": "string",
    "contactEmail": "user@example.com"
  },
  "broker": {
    "companyName": "string",
    "docketNumber": "MC456123",
    "contactName": "string",
    "contactPhone": "string",
    "contactPhoneExt": "string",
    "contactEmail": "string"
  },
  "shipper": {
    "loadNumber": "string",
    "name": "string",
    "shipperId": "string",
    "emails": "string",
    "emailInterval": 0
  },
  "metadata": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "stops": [
    {
      "orderNumber": 1,
      "address": "string",
      "city": "string",
      "state": "VA",
      "zipcode": "20148",
      "lat": 0,
      "lon": 0,
      "datetime": "10/14/2021 12:14:45 EST",
      "geofenceRadius": 0,
      "notes": "string",
      "stopExternalId": "string",
      "metadata": [
        {
          "name": "string",
          "value": "string"
        }
      ]
    }
  ],
  "actions": [
    {
      "name": "string",
      "driverInput": false,
      "options": [
        {
          "name": "string"
        }
      ],
      "required": false,
      "isLastAction": true,
      "item": "trailer",
      "id": "string"
    }
  ]
}

Sample JSON Update Tracking Response Payload.

{
  "status": true,
  "timeStamp": "string",
  "loadId": 0,
  "mapLink": "string",
  "statusPageLink": "string",
  "detailsLink": "string",
  "errorCode": 101,
  "errorMessage": "Account not found"
}

TMS Field Updates

See Trucker Tools Update Existing Load Track documentation here.

Stop Load Tracking

The stop load tracking call sends a request to Trucker Tools to end the current tracking session. When the cancel request is received, the Load Track system cancels the Load Track if the driver has not started the session.

Sample JSON End Tracking Session Request Payload

{
  "partnerId": 0,
  "loadTrackExternalId": 0,
  "accountId": "stringst"
}

Sample JSON Response Payload.

{
  "status": false,
  "timeStamp": "string",
  "loadId": 0,
  "errorCode": 100,
  "errorMessage": "Invalid account"
}

TMS Field Updates

See Trucker Tools Cancel Load Track documentation here.

Tracking Updates from Trucker Tools (PUSH into Revenova)

Location Update

The update load tracking operation receives the latest location data from Trucker Tools.

Manual arrival or departure updates entered by a Driver in the Trucker Tools driver app display as Driver Update in the Comments field. The Stop Status does not change based on these manual updates from the driver app.

Sample JSON Location Update Payload

{
  "eventType": "LocationUpdate",
  "partnerId": 1,
  "accountId": "iqFionGLn7b6LAkFt9BEhQ==",
  "driverPhone": "2025551234",
  "loadNumber": "12345",
  "loadTrackExternalId": "98765"
}

TMS Field Updates

Example Load Tracking Log LWC with Trucker Tools tracking data.

See Trucker Tools Location Updates documentation here.

Status Update

The status update operation receives the latest stop arrival and departure information from Trucker Tools. 

Sample JSON Status Update Payload

{
  "eventType": "StatusUpdate",
  "partnerId": 1,
  "accountId": "iqFionGLn7b6LAkFt9BEhQ==",
  "driverPhone": "2025551234",
  "loadNumber": "12345",
  "loadTrackExternalId": "98765"
}

TMS Field Updates

The Last Reported City and Last Reported State fields are set to the Stop location fields by the TMS. This event is triggered when the Status Update even is received from Trucker Tools.

See Trucker Tools Event Status documentation here.

Document Event

The document event operation receives driver uploaded documents into the TMS. Documents are only processed when the Load Status is Delivered.

Sample JSON Document Events Payload

{
  "eventType": "DocumentUpdate",
  "partnerId": 1,
  "accountId": "iqFionGLn7b6LAkFt9BEhQ==",
  "driverPhone": "2025551234",
  "loadNumber": "12345",
  "loadTrackExternalId": "98765",
  "latestLocation": {
    "accuracy": 85.5,
    "city": "Washington",
    "country": "USA",
    "lat": "38.880029218784",
    "lon": "-77.00543319213574",
    "state": "DC",
    "timestamp": "1/15/2025 13:45 EST",
    "timestampSec": "1/15/2025 13:45:30 EST"
  },
  "latestStatus": {
    "name": "Not Started",
    "code": "NS",
    "timestamp": "1/15/2025 13:45 EST",
    "timestampSec": "1/15/2025 13:45:30 EST"
  },
  "document": {
    "timestamp": "1/15/2025 13:45:30 EST",
    "type": "Bill of Ladings",
    "url": "https://assets.truckertools.com/images/tt-scan-docs/scanImageuploads/filename.jpg",
    "location": {
      "accuracy": 85.5,
      "city": "Washington",
      "state": "DC",
      "country": "USA",
      "lat": "38.880029218784",
      "lon": "-77.00543319213574"
    }
  }
}

TMS Field Updates

See Trucker Tools Document Events documentation here.

API Field Mapping

The following table relates TMS data fields with the equivalent Trucker Tools fields used in API calls.

* Fields marked with an asterisk are required.

Trucker Tools Error Codes

The following table contains the codes sent by Trucker Tools that can appear in the TMS user interface.