Fall '24 Trimble Maps

Overview

The integration with Trimble Maps provides Trip Management functionality for use with the Fleet Management module in the TMS. Trip routing and notifications may be managed with driver availability to more efficiently manage Fleet operations.

Setup

Trimble provides an API Key that is required for enabling the Trimble integration for Fleet Management.

Navigate to TMS Admin → Configuration → Global Settings. Confirm the Trimble box is Checked for Use Platform Events For.

Enter Credentials

Enable the Trimble integration by completing the following steps.

1. Navigate to TMS Admin.

2. Select Credentials. 

3. Select the Global Services tab.

4. Find Trimble in the list and open the card.

5. Check the Enabled box.

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

7. Click the Save button when finished.

Valid credentials are required from all applicable ELD provider subscriptions. See examples in the table below.

Trimble accounts have a “Stop Resequencing” setting that can update the Stop order when making changes to Trip Plans. It is recommended to disable this setting in the Trimble account. Contact Trimble for more information.

Remote Site Settings

Upgrading from previous versions of the TMS may have outdated information.

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 Trimble and click the Edit link.

5.  Update the Remote Site URLs to match the Service URLs below.

Service URL: https://tripmanagement.alk.com
Test Service URL: https://tripmanagement.alk.com

Create an API User

If an API User already exists in an org, add the Trimble API User permission set to the existing API User.

The Trimble integration requires an API user and Connected App to properly send and receive information to and from the TMS.

A connected app is required to allow the send information to and from Trimble. Through the connected app there are several OAuth authorization flows supported by Salesforce.

Create a new API user.

1. Navigate to Setup and then search for and click the Users link.

2. Click the New User button and enter the following information.

   1. First Name: API

   2. Last Name: User

   3. Email: Set as the system admin's email address.

   4. Username: Change if necessary.

   5. User License: Salesforce Integration

   6. Profile: Minimum Access - API Only Integrations

      The User First Name and Last Name can be any value, but should reference API for clarity.

3. Click Save.

4. In the Permission Set Assignments section, click Edit Assignments.

5. Select the Trimble API User Permission Set and click Add.

6. Click Save.

Verify Connected App

Verify that the Trimble Maps API Connection Connected App is created and available in the org. Complete the following steps to finish configuring the connected app.

1. From Setup → App Manager find Trimble Maps API Connection.

2. From the drop-down, select Edit.

3. Check the Enable Client Credentials Flow box.

4. Click Save.

5. Return to Setup → App Manager and find the Trimble Maps API Connection app.

6. From the drop-down, select Manage.

7. Choose the Edit Policies button.

8. In the Client Credentials Flow section, find the Run As field.

9. Click the Run As Lookup button.

10. Select the Trimble Maps API User created above.

11. Click Save.

Create a Connected app by following the steps below. Skip these steps when the Trimble Maps API Connection App already exists.

1. Navigate to Setup and search for Apps and select the App Manager link.

2. Click the New Connected App button.

3. Select Create a Connected App and choose Continue.

4. Enter the following information into the fields.

   1. Connected App Name: Trimble Maps API Connection

   2. API Name: Auto-Generated based on the Connected App Name.

   3. Contact Email: System admin’s email.

   4. Enabled OAuth Setting: Checked.

   5. Callback URL: https://login.salesforce.com/.

   6. Selected OAuth Scopes: Add Full Access (full) and Perform requests at any time (refresh_token, offline_access).

   7. Enable Client Credentials Flow: Checked.

5. Click Save.

6. From the list of apps, find the new Trimble Maps API Connection app.

7. Click the Manage button from the drop-down.

8. Choose the Edit Policies button.

9. From the Client Credentials Flow section find the Run As field and choose the Trimble Maps API User.

10. Click Save.

Copy Consumer Key and Secret

1. Navigate to Setup and then search for and click the App Manager link. 

2.  In the Trimble API row click the arrow and select to View. 
   

3. Click Manage Consumer Details to access the Consumer Key and Consumer Secret which are required for the Trimble connected app. Copy the Key and Secret for later use.

   

   

Setup Client Credentials Flow

1. Navigate to Setup and then search for and click the App Manager link. 

2. In the Trimble API app row click the arrow and select to View.

3. Click  Manage at the top of the page.
   

4. Click Edit Policies.

5. Under Client Credentials Flow Set Run As to the API user.
   

6. Click Save.

7. Navigate to Setup and then search for and click the Company Information link.

8. Copy the 18 character Organization ID.

9. Complete the Trimble integration setup by opening a case with Revenova Support. Include the Consumer Key, Consumer Secret, 18-character Organization ID, and Organization URL in the support case.

Trimble API Calls

Performing actions in the Fleet Management Console initiates calls to the Trimble end points. See individual call information below for information required to send in each API call.

Plan Trip

The Trimble Plan Trip API end point provides routing information based on the stop locations for a Fleet Trip Plan. Calling the Trimble Plan Trip endpoint creates a Trip Plan within the Trimble system. The call is made when the Trip Plan Segment Status is set to Configured. Trimble returns an ID for referencing the route in other calls.

TMS Fields Sent in Plan Trip call

All Trip Plan Segment Stops are included in the Plan Trip call. The location, sequence, and appointment information (when present) is included for each Stop. Each Stop location MUST have either geolocation or address information.

*Fields marked with an asterisk are required.

**The Driver Time Until Break field is only sent if two drivers are present.

***If the Due Out Time and Appointment End Time for the previous Trip Plan Leg are present, this value is the Appointment Time - Due Out Time.

The ID for Driver 1 is sent when two drivers are included in a Trip Plan. The Cycle Time Remaining, Drive Time Remaining, and Time Until Break fields are sent for both drivers.

Sample Plan Trip Request Payload

{
  "name": "Trip-Name",
  "tmsTripId":"TMS-Trip-Identifier",
  "plannedStartLocation": {
    "Coords":{
        "Lat": "42.364551",
        "Lon": "-71.180604"
        }
    },
  "stops": [
    {
      "Location": {
      "Coords": {
          "Lat": "42.346689",
          "Lon": "-71.098860"
            },
        "Label": "Fenway Park"
      },
      "earliestArrivalTime":"2023-09-19T16:45:00",
      "latestArrivalTime":"2023-09-19T18:00:00",
      "stopType":"Origin",
      "stopSequence":0,
      "plannedDuration":60
    },
    {
      "Location": {
        "Address": {
          "StreetAddress": "116 Federal Street",
          "City": "Pittsburgh",
          "State": "PA",
          "Zip": "15212",
          "County": "Allegheny"
        },
        "Label": "PNC Park"
      },
      "earliestArrivalTime":"2023-09-20T17:00:00",
      "latestArrivalTime":"2023-09-20T18:00:00",
      "atRiskThreshold":30,
      "stopType":"Work",
      "stopSequence":0,
      "plannedDuration":120
    },
    {
      "Location": {
        "Address": {
          "StreetAddress": "4900 Marie P Debartolo Way",
          "City": "Santa Clara",
          "State": "CA",
          "Zip": "95054"
        },
        "Label": "Levi's Stadium"
      },
      "earliestArrivalTime":"2023-09-20T23:00:00",
      "latestArrivalTime":"2023-09-21T06:00:00",
      "atRiskThreshold":30,
      "stopType":"Destination",
      "stopSequence":0
    }
  ],
  "tmsId":1,
  "hosSolution":2,
  "costPerMile":1.725,
  "vehicle": {
    "tspVehicleId":"Documentation 1"
  },
  "driverHoursOfService": {
    "enabled":true,
    "hosRuleType":"USFed607LH"
  }
}

Sample Plan Trip Response Payload

{
    "tripStatus": "Planned",
    "modifiedOn": "2023-11-24T14:41:42+00:00",
    "tripDistance": 3177.805,
    "tripDriveDuration": 2938.7,
    "tripDuration": 5638.7,
    "hoursOfServiceRemaining": {
        "enabled": true,
        "remainingDriveTimeUntilBreak": 1440.0,
        "remainingDriveTime": 12240.0,
        "remainingOnDutyTime": 23040.0,
        "hoSRuleType": "USFed607LH",
        "remainingCycleDutyTime": 28800.0,
        "cycleTimeGains": [
            0.0,
            0.0,
            36000.0,
            37680.0,
            36780.0,
            38520.0
        ],
        "lastCycleResetDateTime": null,
        "last24HourBreakDateTime": null,
        "remainingCanadaOnDutyTime": 23040.0,
        "remainingDriveTimeUntilBreakDriver2": null,
        "remainingDriveTimeDriver2": null,
        "remainingOnDutyTimeDriver2": null,
        "remainingCycleDutyTimeDriver2": null,
        "cycleTimeGainsDriver2": null,
        "lastCycleResetDateTimeDriver2": null,
        "last24HourBreakDateTimeDriver2": null,
        "remainingCanadaOnDutyTimeDriver2": null,
        "alternateHoSRuleType": null,
        "remainingTimeUntilFullDayBreak": 0.0,
        "remainingTimeUntilFullDayBreakDriver2": null,
        "remainingDrivingTimeInWeek": 0.0,
        "remainingOnDutyTimeInDay": 0.0,
        "remainingConsecutiveDrivingTime": 0.0,
        "remainingFortnightlyTime": 0.0,
        "currentOffDutyTime": null,
        "currentOffDutyTimeDriver2": null
    },
    "url": "https://tripmanagement.alk.com/trip-viewer/token/ejvhhgguyf45m7tbdcgubmpsixfh5a3tycj3yci3ep/details/96301560?region=NA",
    "tripCost": 5481.714,
    "tripTolls": 0.0,
    "remainingLegDistance": 0.0,
    "remainingLegDriveDuration": 0.0,
    "tmsTripId": "TMS-Trip-Identifier",
    "name": "Trip-Name",
    "stops": [
        {
            "plannedETA": "2023-11-24T09:59:23-05:00",
            "currentETA": "2023-11-24T09:59:23-05:00",
            "currentETD": "2023-11-24T10:59:23-05:00",
            "earliestArrivalTime": "2023-09-19T16:45:00-05:00",
            "latestArrivalTime": "2023-09-19T18:00:00-05:00",
            "plannedDuration": 60.0,
            "actualDuration": 0.0,
            "plannedDepartureTime": "2023-11-24T10:59:23-05:00",
            "legDistance": 5.298,
            "legDriveDuration": 17.683,
            "activeDriver": 1,
            "stopId": 1044395852,
            "location": {
                "address": {
                    "streetAddress": "26 Jersey Street",
                    "city": "Boston",
                    "state": "MA",
                    "zip": "02215",
                    "county": "Suffolk",
                    "country": null
                },
                "coords": {
                    "lat": "42.346689",
                    "lon": "-71.09886"
                },
                "label": "Fenway Park"
            },
            "waypoint": false,
            "stopSequence": 0,
            "stopType": "Origin"
        },
        {
            "plannedETA": "2023-11-24T18:54:15-05:00",
            "currentETA": "2023-11-24T18:54:15-05:00",
            "currentETD": "2023-11-24T19:24:15-05:00",
            "earliestArrivalTime": "2023-11-24T18:39:15-05:00",
            "latestArrivalTime": "2023-11-24T19:09:15-05:00",
            "plannedDuration": 30.0,
            "actualDuration": 0.0,
            "plannedDepartureTime": "2023-11-24T19:24:15-05:00",
            "legDistance": 499.976,
            "legDriveDuration": 474.867,
            "activeDriver": 1,
            "stopId": 1044395853,
            "location": {
                "address": {
                    "streetAddress": "4057 Admiral Peary Highway",
                    "city": "Ebensburg",
                    "state": "PA",
                    "zip": "15931",
                    "county": null,
                    "country": "United States"
                },
                "coords": {
                    "lat": "40.460145",
                    "lon": "-78.769005"
                },
                "label": "@Martin General Store"
            },
            "waypoint": false,
            "stopSequence": 1,
            "stopType": "RestStopShort"
        },
        {
            "plannedETA": "2023-11-24T20:45:27-05:00",
            "currentETA": "2023-11-24T20:45:27-05:00",
            "currentETD": "2023-11-24T22:45:27-05:00",
            "earliestArrivalTime": "2023-09-20T17:00:00-05:00",
            "latestArrivalTime": "2023-09-20T18:00:00-05:00",
            "plannedDuration": 120.0,
            "actualDuration": 0.0,
            "plannedDepartureTime": "2023-11-24T22:45:27-05:00",
            "legDistance": 70.134,
            "legDriveDuration": 81.2,
            "activeDriver": 1,
            "stopId": 1044395854,
            "location": {
                "address": {
                    "streetAddress": "116 Federal Street",
                    "city": "Pittsburgh",
                    "state": "PA",
                    "zip": "15212",
                    "county": "Allegheny",
                    "country": null
                },
                "coords": {
                    "lat": "40.44797",
                    "lon": "-80.003972"
                },
                "label": "PNC Park"
            },
            "waypoint": false,
            "stopSequence": 2,
            "stopType": "Work"
        },
        {
            "plannedETA": "2023-11-24T23:10:49-05:00",
            "currentETA": "2023-11-24T23:10:49-05:00",
            "currentETD": "2023-11-25T09:10:49-05:00",
            "earliestArrivalTime": "2023-11-24T22:55:49-05:00",
            "latestArrivalTime": "2023-11-24T23:25:49-05:00",
            "plannedDuration": 600.0,
            "actualDuration": 0.0,
            "plannedDepartureTime": "2023-11-25T09:10:49-05:00",
            "activeDriver": 1,
            "stopId": 1044395855,
            "location": {
                "address": {
                    "streetAddress": "Pennsylvania Turnpike  (I-76)",
                    "city": "New Brighton",
                    "state": "PA",
                    "zip": "15066",
                    "county": "Beaver",
                    "country": "United States"
                },
                "coords": {
                    "lat": "40.749895",
                    "lon": "-80.207553"
                },
                "label": "Rest Stop"
            },
            "waypoint": false,
            "stopSequence": 3,
            "stopType": "RestStopLong"
        },
        {
            "plannedETA": "2023-11-25T15:58:41-06:00",
            "currentETA": "2023-11-25T15:58:41-06:00",
            "currentETD": "2023-11-25T16:28:41-06:00",
            "earliestArrivalTime": "2023-11-25T15:43:41-06:00",
            "latestArrivalTime": "2023-11-25T16:13:41-06:00",
            "plannedDuration": 30.0,
            "actualDuration": 0.0,
            "plannedDepartureTime": "2023-11-25T16:28:41-06:00",
            "legDistance": 502.913,
            "legDriveDuration": 467.867,
            "activeDriver": 1,
            "stopId": 1044395856,
            "location": {
                "address": {
                    "streetAddress": "3130 May Road",
                    "city": "Peru",
                    "state": "IL",
                    "zip": "61354",
                    "county": null,
                    "country": "United States"
                },
                "coords": {
                    "lat": "41.366681",
                    "lon": "-89.151536"
                },
                "label": "@Sapp Bros. Peru"
            },
            "waypoint": false,
            "stopSequence": 4,
            "stopType": "RestStopShort"
        },
        {
            "plannedETA": "2023-11-25T19:08:53-06:00",
            "currentETA": "2023-11-25T19:08:53-06:00",
            "currentETD": "2023-11-26T05:08:53-06:00",
            "earliestArrivalTime": "2023-11-25T18:53:53-06:00",
            "latestArrivalTime": "2023-11-25T19:23:53-06:00",
            "plannedDuration": 600.0,
            "actualDuration": 0.0,
            "plannedDepartureTime": "2023-11-26T05:08:53-06:00",
            "legDistance": 178.514,
            "legDriveDuration": 160.2,
            "activeDriver": 1,
            "stopId": 1044395857,
            "location": {
                "address": {
                    "streetAddress": "4126 Hwy 21",
                    "city": "Brooklyn",
                    "state": "IA",
                    "zip": "52211",
                    "county": null,
                    "country": "United States"
                },
                "coords": {
                    "lat": "41.698446",
                    "lon": "-92.359026"
                },
                "label": "@Pilot Travel Center #495"
            },
            "waypoint": false,
            "stopSequence": 5,
            "stopType": "RestStopLong"
        },
        {
            "plannedETA": "2023-11-26T11:56:07-07:00",
            "currentETA": "2023-11-26T11:56:07-07:00",
            "currentETD": "2023-11-26T12:26:07-07:00",
            "earliestArrivalTime": "2023-11-26T11:41:07-07:00",
            "latestArrivalTime": "2023-11-26T12:11:07-07:00",
            "plannedDuration": 30.0,
            "actualDuration": 0.0,
            "plannedDepartureTime": "2023-11-26T12:26:07-07:00",
            "legDistance": 529.301,
            "legDriveDuration": 467.233,
            "activeDriver": 1,
            "stopId": 1044395858,
            "location": {
                "address": {
                    "streetAddress": "103 Prospector Drive",
                    "city": "Ogallala",
                    "state": "NE",
                    "zip": "69153",
                    "county": null,
                    "country": "United States"
                },
                "coords": {
                    "lat": "41.113633",
                    "lon": "-101.712174"
                },
                "label": "@TA-Ogallala #90"
            },
            "waypoint": false,
            "stopSequence": 6,
            "stopType": "RestStopShort"
        },
        {
            "plannedETA": "2023-11-26T14:52:10-07:00",
            "currentETA": "2023-11-26T14:52:10-07:00",
            "currentETD": "2023-11-27T00:52:10-07:00",
            "earliestArrivalTime": "2023-11-26T14:37:10-07:00",
            "latestArrivalTime": "2023-11-26T15:07:10-07:00",
            "plannedDuration": 600.0,
            "actualDuration": 0.0,
            "plannedDepartureTime": "2023-11-27T00:52:10-07:00",
            "legDistance": 162.261,
            "activeDriver": 1,
            "location": {
                "address": {
                    "streetAddress": "8020 Campstool Road",
                    "city": "Cheyenne",
                    "state": "WY",
                    "zip": "82007",
                    "county": null,
                    "country": "United States"
                },
                "coords": {
                    "lat": "41.136222",
                    "lon": "-104.707177"
                },
                "label": "@Pilot Travel Center #402"
            },
            "waypoint": false,
            "stopSequence": 7,
            "stopType": "RestStopLong"
        },
    "tspDriverId": null,
    "vehicle": {
        "tspVehicleId": "Documentation 1",
        "isHighValue": false
    },
    "plannedStartTime": "2023-11-24T14:41:40+00:00",
    "plannedStartLocation": {
        "address": {
            "streetAddress": "42 North Beacon Street  (US-20)",
            "city": "Watertown",
            "state": "MA",
            "zip": "02472",
            "county": "Middlesex",
            "country": "United States"
        },
        "coords": {
            "lat": "42.364551",
            "lon": "-71.180604"
        },
    },
    "costPerMile": 1.725,
    "tripOptions": [],
    "region": "NA",
    "externalOrderIds": [],
    "alkTripId": 96301560
}

TMS Field Updates

See additional Trimble Plan Trip documentation here.

Modify Trip

Changes may be made to existing Fleet Trip Plans that are already created in the Trimble system. The Modify Trip endpoint is called whenever any of the following information is updated in the Fleet Management Console.

• Changing the Power Unit assigned to a Trip Plan Segment.

• Assigning a different Load to a Trip Plan Segment.

• A Trip Plan Leg is added to a Trip Plan Segment.

• A Trip Plan Leg is deleted from a Trip Plan Segment.

• Changing a Trip Plan Leg Start or End Location.

• Changing the Appointment Start or End Time or the Due Out Dates or Times.

Trimble returns a successful response or an error code.

Once a Trip is dispatched, the Leg 1 Start Location cannot be modified.

Calling the Trimble Modify Trip endpoint changes the Trip Plan within the Trimble system but does not change the status.

TMS Fields Sent in Modify Trip call

All Trip Plan Segment Stops are included in the Modify Trip call. The location, sequence, and appointment information (when present) is included for each Stop. Each Stop location MUST have either geolocation or address information.

*Fields marked with an asterisk are required.

**The Driver Time Until Break field is only sent if two drivers are present.

***If the Due Out Time and Appointment End Time for the previous Trip Plan Leg are present, this value is the Appointment Time - Due Out Time.

The ID for Driver 1 is sent when two drivers are included in a Trip Plan. The Cycle Time Remaining, Drive Time Remaining, and Time Until Break fields are sent for both drivers.

Sample Modify Trip Request Payload

{
  "tripId": "136",
  "plannedStartTime": "2017-09-21T14:11:52.522Z",
  "plannedStartLocation": {
    "Coords": {
      "Lat": "42.346619",
      "Lon": "-71.096961"
    }
  },
  "externalOrderIds": ["123", "abc", "123+abc"],
  "stops": [
    {
      "Location": {
        "Address": {
          "StreetAddress": "4 Yawkey Way",
          "City": "Boston",
          "State": "MA",
          "Zip": "02215",
          "County": "Suffolk"
        },
        "Label": "Fenway Park"
      },
      "earliestArrivalTime": "2017-09-21T14:11:52.522Z",
      "latestArrivalTime": "2017-09-21T15:11:52.522Z",
  	  "actualDepartureTime":"2017-09-21T14:11:52.522Z",
      "stopStatus": "Completed",
      "stopType": "Origin",
      "stopSequence": 0
    },
    {
      "Location": {
        "Address": {
          "StreetAddress": "1000 Ballpark Way",
          "City": "Arlington",
          "State": "TX",
          "Zip": "76011"
        },
        "Label": "Globe Life Park"
      },
      "earliestArrivalTime": "2017-09-21T14:11:52.522Z",
      "latestArrivalTime": "2017-09-21T15:11:52.522Z",
      "atRiskThreshold": 30,
      "stopType": "Work",
      "stopSequence": 1
    },
    {
      "Location": {
        "Address": {
          "StreetAddress": "100 Park Blvd",
          "City": "San Diego",
          "State": "CA",
          "Zip": "92101"
        },
        "Label": "Petco Park"
      },
      "earliestArrivalTime": "2017-09-21T14:11:52.522Z",
      "latestArrivalTime": "2017-09-21T15:11:52.522Z",
      "atRiskThreshold": 30,
      "stopType": "Destination",
      "stopSequence": 2
    }
  ],
}

Sample Modify Trip Response Payload

{
  "success": true,
  "message": null
}

No TMS Field Updates

See additional Trimble documentation here.

Update Trip Status

Calls to the Update Trip Status end point change the Trimble route based on the Status of the Fleet Trip Plan Segment. The call is first made when a Trip Plan Segment Status is moved from Dispatched to In Progress. If changes are made to the Trip Plan Segment Status field, the call is made to update the status in the Trimble environment.

The Update Trip Status call is made to update the Trimble Trip Plan.

The call is made to the Update Trip Status end point when a Trip Plan Segment Status field is set to Dispatched. The Trimble Trip Plan is updated to a status of In Progress.

Fleet Assets must have a Geolocation. An Error Log record is created if a Fleet Asset does not have a Geolocation.

TMS Fields Sent in Update Trip Status call

*Fields marked with an asterisk are required.

Sample Update Trip Status Request Payload

{
  "tripId": 12345,
  "status": 2,
  "timeStamp": "2018-03-20T15:00:42.624Z",
  "loc": {
    "Coords": {
      "Lat": "42.364551",
      "Lon": "-71.180604"
    }
  }
}

Sample Update Trip Status Response Payload

{
  "success": true,
  "errorCode": 0
}

No TMS Field Updates

Update Trip Status Error Codes

See additional Trimble documentation here.

Get Trip

Trimble provides a map with routing information that is available for viewing in the TMS. Once a Trip Plan Segment Status field is Configured, the View Trip button in the Fleet Management Console is used to view the map and route. An assigned driver is not required to view the make the Get Trip call.

TMS Fields Sent in Get Trip call

*Fields marked with an asterisk are required.

TMS Field Updates

URL opens the Trimble Trip View UI. This URL is not stored in the TMS.

Sample Get Trip Request Payload

{
  "tripId": "Trip Plan Segment",
}

Sample Get Trip Response Payload

{
  "tripStatus": "Planned",
  "modifiedOn": "2019-01-22T18:08:46+00:00",
  "tripDistance": 3123.933,
  "tripDriveDuration": 3282,
  "tripDuration": 3282,
  "hoursOfServiceRemaining": null,
  "url": "https://trip-viewer.trimblemaps.com/trip-viewer/token/7pjpf0xirx81aessnfgg97q/details/203697073?region=NA",
  "tripCost": 6302.57,
  "tripTolls": 0,
  "tmsTripId": "ALK1234",
  "name": "Boston to San Diego",
  "stops": [
    {
      "plannedETA": "2017-09-21T10:20:53-04:00",
      "currentETA": "2017-09-21T10:20:53-04:00",
      "earliestArrivalTime": "2017-09-21T10:11:52-04:00",
      "latestArrivalTime": "2017-09-21T11:11:52-04:00",
      "plannedDuration": 0,
      "actualDuration": 0,
      "plannedDepartureTime": "2017-09-21T10:20:53-04:00",
      "stopStatus": "Open",
      "stopArrivalStatus": "OnTime",
      "atRiskThreshold": 15,
      "tooEarlyThreshold": null,
      "legDistance": 2.247,
      "legDriveDuration": 9,
      "metadata": null,
      "amenities": null,
      "truckServices": false,
      "alternateRestStops": null,
      "poiId": 0,
      "setId": 0,
      "persistentId": 0,
      "activeDriver": 1,
      "location": {
        "address": {
          "streetAddress": "4 Hawley Place",
          "city": "Boston",
          "state": "MA",
          "zip": "02110",
          "county": "Suffolk",
          "country": null,
          "stateName": null,
          "stateAbbreviation": null,
          "countryAbbreviation": null
        },
        "coords": {
          "lat": "42.356016",
          "lon": "-71.058228"
        },
        "label": "Fenway Park"
      },
      "stopSequence": 0,
      "stopType": "Origin"
    },
    {
      "plannedETA": "2017-09-22T08:44:46-05:00",
      "currentETA": "2017-09-22T08:44:46-05:00",
      "earliestArrivalTime": "2017-09-21T09:11:52-05:00",
      "latestArrivalTime": "2017-09-21T10:11:52-05:00",
      "plannedDuration": 0,
      "actualDuration": 0,
      "plannedDepartureTime": "2017-09-22T08:44:46-05:00",
      "stopStatus": "Open",
      "stopArrivalStatus": "Late",
      "atRiskThreshold": 30,
      "tooEarlyThreshold": null,
      "legDistance": 1310.714,
      "legDriveDuration": 1403,
      "metadata": null,
      "amenities": null,
      "truckServices": false,
      "alternateRestStops": null,
      "poiId": 0,
      "setId": 0,
      "persistentId": 0,
      "activeDriver": 1,
      "location": {
        "address": {
          "streetAddress": "200 Union Avenue",
          "city": "Memphis",
          "state": "TN",
          "zip": "38103",
          "county": "Shelby",
          "country": null,
          "stateName": null,
          "stateAbbreviation": null,
          "countryAbbreviation": null
        },
        "coords": {
          "lat": "35.142195",
          "lon": "-90.049621"
        },
        "label": "AutoZone Park"
      },
      "stopSequence": 1,
      "stopType": "Work"
    },
    {
      "plannedETA": "2017-09-22T17:03:13-05:00",
      "currentETA": "2017-09-22T17:03:13-05:00",
      "earliestArrivalTime": "2017-09-21T09:11:52-05:00",
      "latestArrivalTime": "2017-09-21T10:11:52-05:00",
      "plannedDuration": 0,
      "actualDuration": 0,
      "plannedDepartureTime": "2017-09-22T17:03:13-05:00",
      "stopStatus": "Open",
      "stopArrivalStatus": "Late",
      "atRiskThreshold": 30,
      "tooEarlyThreshold": null,
      "legDistance": 470,
      "legDriveDuration": 498,
      "metadata": null,
      "amenities": null,
      "truckServices": false,
      "alternateRestStops": null,
      "poiId": 0,
      "setId": 0,
      "persistentId": 0,
      "activeDriver": 1,
      "location": {
        "address": {
          "streetAddress": "1000 Ballpark Way",
          "city": "Arlington",
          "state": "TX",
          "zip": "76011",
          "county": "Tarrant",
          "country": null,
          "stateName": null,
          "stateAbbreviation": null,
          "countryAbbreviation": null
        },
        "coords": {
          "lat": "32.750284",
          "lon": "-97.08119"
        },
        "label": "Globe Life Park"
      },
      "stopSequence": 2,
      "stopType": "Work"
    },
  ],
  "tspDriverId": "fred",
  "vehicle": {
    "tspVehicleId": "111111",
    "isHighValue": false
  },
  "plannedStartTime": "2017-09-21T10:11:52-04:00",
  "plannedStartLocation": {
    "address": {
      "streetAddress": "22 Lansdowne Street",
      "city": "Boston",
      "state": "MA",
      "zip": "02215",
      "county": "Suffolk",
      "country": "United States",
      "stateName": null,
      "stateAbbreviation": null,
      "countryAbbreviation": null
    },
    "coords": {
      "lat": "42.346619",
      "lon": "-71.096961"
    },
    "label": null
  },
  "allowDriverToDeclineTrip": true,
  "oocThreshold": 1,
  "hosSolution": "ALK",
  "sendOptions": null,
  "driverHoursOfService": {
    "useCycleReset": false,
    "enabled": false,
    "terminalDayStartTime": "12:00:00-4:00",
    "remainingDriveTimeUntilBreak": 28800,
    "useCustomPlaces": true,
    "remainingDriveTime": 39600,
    "teamDriving": false,
    "remainingOnDutyTime": 50400,
    "customBreakDurations": {
      "shortBreakDuration": 3600,
      "endOfDutyBreakDuration": 43200,
      "cycleResetBreakDuration": 144000,
      "driverSwitchBreakDuration": 300,
      "borderCrossingWaitDuration": 7200
    },
  },
  "afSetIds": null,
  "afSetNames": null,
  "alkTripId": 136
}

See additional Trimble documentation here.

Cancel Trip

The Trimble Cancel Trip end point is called to cancel an existing route within the Trimble system. This end point is called when a Trip Plan Segment or Trip Plan is deleted in the Fleet Management Console. The call is also made when a Trip Plan Segment is Undispatched or a Trip Plan Segment is manually changed from Dispatched to Planned or Configured.

A trip must exist before the Cancel Trip call can be made.

TMS Fields Sent in Cancel Trip call

*Fields marked with an asterisk are required.

Sample Cancel Trip Request Payload

{
  "tripId": "Trip Plan Segment",
}

Sample Cancel Trip Response Payload

{
  "success": true,
  "message": null
}

TMS Field Updates

See additional Trimble documentation here.

Update StopStatus

The Trimble Update StopStatus end point is called to update the status of a given Stop in a route.

Stops are added with the default Trimble value “Open” when creating Trip Plans in the Fleet Management Console. The TMS calls the Update StopStatus when the Arrival Date and Arrival Time or Departure Date and Departure Time are added to a Trip Plan Leg.

Adding the Arrival Date and Time sends them with the “Arrived” Stop Status value to Trimble.

Arrival and Departure Dates and Times cannot be changed once received by Trimble. Arrival and Departure Dates and Times may be updated in the TMS, but changing the values does not send the values to Trimble.

If both the Arrival and Departure Dates and Times are saved at the same time, the Departure Date and Time are sent. Trimble auto-populates the Stop arrival time to be the same as the departure time.

Adding the Departure Date and Time sends the Departure Date and Time with the “Completed/Departed” Stop Status value to Trimble.

Trimble updates the Trip Plan status to “Completed” when the last Stop value is “Arrived.”

TMS Internal Logic

• Each time the Trip Plan is saved, the Trip Plan Leg Status is recalculated.

  • When an Appointment Date and Time is populated, the Trip Plan Leg is set to Configured.

  • When a Trip Plan Status is Dispatched and the Due Out Date and Time is before the current date and time or the Arrival Date is present, the Trip Plan Status is set to Dispatched.

  • When a Departure Date is present, the Trip Plan Status is set to Completed.

  • Arrival and Departure Date/Times are set by the Fleet Management Job and Trimble Notifications.

TMS Fields Sent in Update Stop Status call

*Fields marked with an asterisk are required.

**If the Arrival Date and Time or Departure Date and Time are present, these fields are sent. The current date and time are only sent if those values are not set.

Sample Update StopStatus Request Payload

{
  "tripId": 136,
  "stopId": 0,
  "stopState": 2,
  "actualDepartureTime": "2017-09-06T19:37:16+00:00",
  "stopDuration": 32
}

Sample Update Stop Status Response Payload

{
  "success": true,
  "message": null
}

No TMS Field Updates

A success is returned to the TMS.

See additional Trimble Update StopStatus documentation here.

Update Positions

The Trimble Update Positions end point is called to update the location of a Fleet Asset traveling a route. The Update Positions call is made to update Fleet Asset locations when running the Fleet Management 1 or 2 jobs. This call is only made when the Fleet Asset belongs to a Trip Plan Segment and the Trip Plan Segment Status is Dispatched.

TMS Fields sent in Update Positions call

*Fields marked with an asterisk are required.

**If this field does not have a value the current date and time is sent.

Sample Update Positions Request Payload

{
  "tripId": "136",
  "locations": [
    {
      "coords": {
        "lat": "40.058447",
        "lon": "-78.081017"
      },
      "speed": 45,
      "heading": 26,
      "altitude": 1000,
      "deviceDT": "2017-09-06T19:05:16+00:00"
    },
    {
      "coords": {
        "lat": "40.061247",
        "lon": "-78.099054"
      },
      "deviceDT": "2017-09-07T01:05:16-04:00"
    }
  ]
}

Sample Update Positions Response Payload

{
  "success": true,
  "message": null
}

No TMS Field Updates

See Trimble Update Positions documentation here.

Inbound Trip Notifications Service

The TMS integration with Trimble provides real-time notifications for several possible alert types received over the course of a trip. These alerts are delivered by Trimble and processed and stored in the TMS.

The TMS listens for notifications sent from Trimble and updates Trip records according to the notification type. The following notifications are received from Trimble and stored in the TMS.

The time period, distance, interval, and update frequency settings for receiving notifications into the TMS are set per Trimble account. To change these settings, contact Trimble support.

ETA Event

An ETA Event alert is sent whenever the GPS position for a trip impacts the current ETA. Trimble sends an ETA Event when the ETA changes based on the following trip scenarios.

• The ETA of a Stop is outside the TMS Appointment Date and Time fields sent in the Plan Trip call.

• The currentETA is a time interval later than the plannedETA. The The plannedETA is returned in the Plan Trip response and stored in the Event Detail field.

TMS Field Updates from an ETA Event Notification

Sample ETA EVENT Notification Payload

{
  "properties": {
    "tripId": 140859211,
    "tripStatus": "InProgress",
    "tspDriverId": "Trimble_user@trimble.com",
    "notificationType": "eta",
    "estimatedArrivalInfo": {
      "stopInfo": {
        "plannedETA": "2022-06-01T12:03:33-04:00",
        "currentETA": "2022-06-01T12:22:02-04:00",
        "earliestArrivalTime": "2022-06-01T11:30:00-04:00",
        "latestArrivalTime": "2022-06-01T12:15:00-04:00",
        "stopId": 1270094413,
        "stopArrivalStatus": "Late",
        "location": {
          "address": {
            "streetAddress": "762 Hylan Boulevard",
            "city": "Staten Island",
            "state": "NY",
            "zip": "10305",
            "county": "Richmond",
            "country": null
          },
          "coords": {
            "lat": "40.601683",
            "lon": "-74.07256"
          },
          "label": "StopLabel"
        },
        "stopSequence": 4,
        "stopType": "Work"
      },
      "publishedOn": "06/01/2022 15:09:27+00:00",
      "deviceDT": "2022-06-01T15:09:25+00:00"
    }
  }
}

Stop Status Update

Updates to a stop status generates a Stop Status Update notification that is sent to the TMS. Updates are processed and stored in the TMS as Arrival or Departed.

TMS Field Updates from Stop Status Update Notification

Sample Stop Status Update Notification Payload

{
  "properties": {
    "tripId": 140859022,
    "tripStatus": "InProgress",
    "tspDriverId": "fred",
    "notificationType": "stop_status_update",
    "stopStatusEvents": {
      "stopId": 1270093363,
      "stopSequence": 1,
      "eventType": "DepartedStop",
      "stopLocation": {
        "address": {
          "streetAddress": "976 South Union Avenue",
          "city": "Los Angeles",
          "state": "CA",
          "zip": "90015",
          "county": "Los Angeles",
          "country": "United States"
        },
        "coords": {
          "lat": "34.049881",
          "lon": "-118.273503"
        },
        "label": "StopLabel"
      },
      "publishedOn": "06-01-2022T15:09:27+00:00",
      "deviceDT": "2022-06-01T15:09:25+00:00"
    }
  }
}

Weather

Weather alert notifications are sent to the TMS when the Trimble service determines a Trip will experience weather. Both planned and active Trips are analyzed to determine if they will encounter a weather alert. The weather is checked by Trimble on a regular basis and notifications are sent when necessary.

TMS Field Updates from Weather Notification

Sample Weather Notification Payload

{
  "properties": {
    "tripId": "140858769",
    "tripStatus": "InProgress",
    "tspDriverId": "Trimble_User@trimble.com",
    "notificationType": "weather",
    "weatherInfo": {
      "enterTime": "2022-06-01T15:04:41+00:00",
      "exitTime": "2022-06-01T15:45:35+00:00",
      "enterLocation": {
        "address": {
          "streetAddress": "Kingman Road Northeast",
          "city": "Nashville",
          "state": "KS",
          "zip": "67112",
          "county": "Kingman",
          "country": "United States"
        },
        "coords": {
          "lat": "37.38",
          "lon": "-98.46"
        },
        "label": null
      },
      "weatherAlert": {
        "id": "https://alerts.weather.gov/cap/wwacapget.php?x=KS1263F9BDB374.FloodWarning.1263F9EC6CC8KS.ICTFLWICT.73f3167bd92c0295cc9d75692944123d",
        "dispUpdated": "2022-05-31T21:13:00-05:00",
        "dispPublished": "2022-05-31T21:13:00-05:00",
        "title": "Flood Warning issued May 31 at 9:13PM CDT until June 04 at 3:34AM CDT by NWS",
        "summary": "...FLOOD WARNING IN EFFECT UNTIL 915 AM CDT WEDNESDAY... * WHAT...Flooding caused by excessive rainfall is expected. * WHERE...A portion of South Central Kansas, including the following counties, Butler, Harvey, Kingman and Sedgwick. * WHEN...Until 915 AM CDT Wednesday. * IMPACTS...Flooding of rivers, creeks, streams, and other low-lying",
        "alertEvent": "Flood Warning",
        "dispEffective": "2022-05-31T21:13:00-05:00",
        "dispExpires": "2022-06-04T03:34:00-05:00",
        "status": "Actual",
        "category": "Met",
        "urgency": "Expected",
        "severity": "Moderate",
        "certainty": "Likely",
        "areaDesc": "Sedgwick",
        "countryCode": "US"
      },
      "publishedOn": "06-01-2022T15:05:37+00:00"
    }
  }
}

Out of Route

The Out of Route notification is sent when the total mileage of a completed Trip is different from the original planned mileage. The mileage threshold is determined as a Trimble account setting.

Out of Route notifications are sent once at the end of a Trip.

TMS Field Updates from Out of Route Notification

Sample Out of Route Notification Payload

{
  "properties": {
    "tripId": "4039704",
    "tripStatus": "Completed",
    "notificationType": "OutOfRoute",
    "outOfRouteInfo": {
      "driverId": "Driver1",
      "oorDistance": 2158.64,
      "publishedOn": "2024-07-16T16:20:13+00:00"
    }
  }
}

Out of Corridor

The Out of Corridor notification is sent when a Trip deviates from a planned route beyond a certain mileage threshold.

Out of Corridor notifications are sent each time the GPS position is detected outside of the mileage threshold. The mileage threshold is determined as a Trimble account setting.

TMS Field Updates from Out of Corridor Notification

Sample Out of Corridor Notification Payload

{
  "properties": {
    "tripId": 140858769,
    "tripStatus": "InProgress",
    "tspDriverId": "test_driver@trimble.com",
    "notificationType": "out_of_corridor",
    "outOfCorridorInfo": {
      "coords": {
        "lat": "37.57476",
        "lon": "-98.3625"
      },
      "oocDistance": 211.38,
      "status": "LeftRoute",
      "publishedOn": "2022-06-01T15:40:41+00:00",
      "deviceDT": "2022-06-01T15:40:41+00:00"
    }
  }
}

Traffic

Traffic alert notifications are sent to the TMS when the Trimble service detects a Trip will be impacted by traffic. Both planned and active Trips are analyzed to determine if they will encounter a Traffic alert.

Traffic Incidents that trigger a notification send to the TMS.

• Construction

• Road Closures

• Congestion

• Accidents

The Trimble service checks for traffic incidents when the following occurs.

• The Trip is planned.

• Every 12 hours for all Planned Trips.

• When the tripStatus field changes to In Progress. The field is set to In Progress when the following occurs.

  • The first stop is completed.

  • The first GPS position is received for the Trip.

• When an ETA Event alert is detected.

• When an arrival or departure is detected for any Stops in a Trip.

TMS Field Updates from Traffic Notification

Sample Traffic Notification Payload

{
  "properties": {
    "tripId": 6879052,
    "tripStatus": "Planned",
    "driverId": "Trimble_user@trimble.com",
    "notificationType": "traffic_incident_planned",
    "trafficIncidentInfo": {
      "incidentId": -2091160570,
      "shortDesc": "I-70: paving repairs from I-70 Exits 11 / IN-46 to Exit 1 National Ave",
      "address": {
        "streetAddress": "I-70, US-40",
        "city": "West Terre Haute",
        "state": "IN",
        "zip": null,
        "county": "Vigo",
        "country": "United States"
      },
      "coords": {
        "lat": 39441256,
        "lon": -87512693
      },
      "publishedOn": "08/30/2024 20:00:11 +00:00"
    }
  }
}

Approaching Stop

Approaching Stop notifications are sent to the TMS when a Fleet Asset is within 15 minutes of the Stop. The notification includes the number of minutes the Asset is away from the Stop, as well. This notification is sent separately from the Update Stop Status notification.

TMS Field Updates from Approaching Stop Notification

Sample Approaching Stop Notification Payload

{
  "properties": {
    "message": "Asset {tspDriverId} is approaching Stop {stopLabel} and is currently {xx} minutes away",
    "tripId": 140859022,
    "tspDriverId": "fred",
    "notificationType": "approachingStop",
    "stopDetails": {
      "stopId": 1270093363,
      "stopSequence": 1,
      "stopArrivalStatus": "OnTime",
      "currentETA": "2022-06-01T15:00:00+00:00",
      "stopLocation": {
        "address": {
          "streetAddress": "976 South Union Avenue",
          "city": "Los Angeles",
          "state": "CA",
          "zip": "90015",
          "county": "Los Angeles",
          "country": "United States"
        },
        "coords": {
          "lat": "34.049881",
          "lon": "-118.273503"
        },
        "label": "StopLabel"
      },
      "publishedDateTime": "06-01-2022T15:09:27+00:00",
      "deviceDateTime": "06-01-2022T15:09:26+00:00"
    }
  }
}

Excessive Dwell

The Excessive Dwell notification is sent when a Stop dwell time is greater than 10% of the plannedDuration time field. The plannedDuration field value is the TMS Appointment Time - Due Out Time fields that are sent during the Plan Trip and Modify Trip API calls.

TMS Field Updates from Excessive Dwell Notification

Sample Excessive Dwell Notification Payload

{
  "properties": {
    "message": "{tspDriverId} has exceeded the planned Dwell time for {stopLabel}",
    "tripId": 140859211,
    "tspDriverId": "Trimble_user@trimble.com",
    "notificationType": "excessiveDwell",
    "stopDetails": {
      "plannedETA": "2022-06-01T12:03:33-04:00",
      "actualArrivalTime": "2022-06-01T12:13:33-04:00",
      "plannedDuration": 30,
      "currentDuration": 45,
      "stopId": 1270094413,
      "stopArrivalStatus": "Late",
      "stopType": "Work",
      "location": {
        "address": {
          "streetAddress": "762 Hylan Boulevard",
          "city": "Staten Island",
          "state": "NY",
          "zip": "10305",
          "county": "Richmond",
          "country": null
        },
        "coords": {
          "lat": "40.601683",
          "lon": "-74.07256"
        },
        "label": "StopLabel"
      },
      "stopSequence": 4
    },
    "publishedOn": "06/01/2022 15:09:27+00:00",
    "deviceDT": "2022-06-01T15:09:25+00:00"
  }
}

See Trimble Notification documentation here.

Field Reference Table

The following table relates TMS fields with the equivalent Trimble fields included in Trimble API calls.