--- title: "Fall '24 Trimble Maps" slug: "fall-24-trimble-maps" tags: ["Fleet Management", "Admin", "Expanded Content", "Fall '24"] updated: 2025-01-15T17:00:35Z published: 2025-01-15T17:00:35Z canonical: "documents.revenova.com/fall-24-trimble-maps" --- > ## Documentation Index > Fetch the complete documentation index at: https://documents.revenova.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. | User ID | Password 1 | Password 2 | Customer Number | | --- | --- | --- | --- | | Required | Required | | | > [!WARNING] > 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** > [!NOTE] > 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 > [!NOTE] > 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**. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Trimble API User - 1.jpg) ### **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.![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/New%20Connected%20App.jpg) 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**.![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Border Connect - Connected App - 1.jpg) 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**. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Trimble Manage - 1.jpg) 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. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Trimble Manage - 2.jpg) ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Trimble Manage - 3.jpg) ### **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. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Trimble Manage - 4.jpg) 4. Click **Edit Policies**. 5. Under *Client Credentials Flow* Set **Run As** to the API user. ![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Trimble Manage - 5.jpg) 6. Click **Save**. 7. Navigate to **Setup** and then search for and click the **Company Information** link. 8. Copy the 18 character Organization ID.![](https://cdn.document360.io/b89abf73-101a-4754-a781-084aef8f68dd/Images/Documentation/Trimble Manage - 6.jpg) 9. Complete the Trimble integration setup by [opening a case](https://documents.revenova.com/docs/getting-started-with-revenova#create-a-revenova-support-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 Operation | Trimble Endpoint | Request Type | Response | | --- | --- | --- | --- | | Trip Plan Segment **Status** set to *Configured* | Plan Trip | POST | 200: Success | **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. | Object | Field | Type | Trimble Field | | --- | --- | --- | --- | | Driver | Cycle Time Remaining | Number(3, 2) | RemainingCycleDutyTime | | Driver | Drive Time Remaining | Number(3, 2) | RemainingDriveTime | | Driver | SFID | SFID | tspDriverId | | Driver | Time Until Break | Number(3, 2) | **RemainingDriveTimeUntilBreak | | Trip Plan | Name | Auto Number | *name | | | | “Work” | stopType | | | | Number | *stopSequence | | Trip Plan Leg | Appointment Date | Date | earliestArrivalTime, latestArrivalTime | | Trip Plan Leg | Appointment End Time | Time | latestArrivalTime | | Trip Plan Leg | Appointment End Time - Due Out Time | Time | ***plannedDuration | | Trip Plan Leg | Appointment Start Time | Time | earliestArrivalTime | | Trip Plan Leg | Due Out Date | Date | plannedStartTime, plannedDepartureTime | | Trip Plan Leg | Due Out Time | Time | plannedStartTime, plannedDepartureTime | | Trip Plan Leg | Start Geolocation | Geolocation | lat, lon | | Trip Plan Leg | Start City | Text(40) | city | | Trip Plan Leg | Start Postal Code | Text(20) | zip | | Trip Plan Leg | Start State/Province | Picklist | state | | Trip Plan Leg | Start Street Address | Text(100) | street address | | Trip Plan Segment | Load | Lookup(Load) | *externalOrderIds | | Trip Plan Segment | Name | Text(80) | *name | | Trip Plan Segment | Power Unit | Lookup(Fleet Asset) | tspVehicleId | | Trip Plan Segment | SFID | SFID | *tmsTripId | **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****.* > [!NOTE] > 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 ```json {  "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 ```json {    "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** | Object | Field | Type | Trimble Field | | --- | --- | --- | --- | | Trip Plan Segment | API Trip Id | Text(40) (External ID) | alkTripId | See additional Trimble Plan Trip documentation [here](https://developer.trimblemaps.com/restful-apis/trip-management/api-documentation/plan-trip/). ### **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. > [!NOTE] > 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 Operation | Trimble Endpoint | Request Type | Response | | --- | --- | --- | --- | | Multiple TMS actions | Modify Trip | PUT | 200: Success | **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. | Object | Field | Type | Trimble Field | | --- | --- | --- | --- | | Driver | Cycle Time Remaining | Number(3, 2) | RemainingCycleDutyTime | | Driver | Drive Time Remaining | Number(3, 2) | RemainingDriveTime | | Driver | SFID | SFID | tspDriverId | | Driver | Time Until Break | Number(3, 2) | **RemainingDriveTimeUntilBreak | | Trip Plan | Name | Auto Number | *name | | | | “Work” | stopType | | | | Number | *stopSequence | | Trip Plan Leg | Appointment Date | Date | earliestArrivalTime, latestArrivalTime | | Trip Plan Leg | Appointment End Time | Time | latestArrivalTime | | Trip Plan Leg | Appointment End Time - Due Out Time | Time | ***plannedDuration | | Trip Plan Leg | Appointment Start Time | Time | earliestArrivalTime | | Trip Plan Leg | Due Out Date | Date | plannedStartTime, plannedDepartureTime | | Trip Plan Leg | Due Out Time | Time | plannedStartTime, plannedDepartureTime | | Trip Plan Leg | Start Geolocation | Geolocation | lat, lon | | Trip Plan Leg | Start City | Text(40) | city | | Trip Plan Leg | Start Postal Code | Text(20) | zip | | Trip Plan Leg | Start State/Province | Picklist | state | | Trip Plan Leg | Start Street Address | Text(100) | street address | | Trip Plan Segment | Load | Lookup(Load) | *externalOrderIds | | Trip Plan Segment | Name | Text(80) | *name | | Trip Plan Segment | Power Unit | Lookup(Fleet Asset) | tspVehicleId | | Trip Plan Segment | SFID | SFID | *tmsTripId | **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****.* > [!NOTE] > 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 ```json {  "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 ```json {  "success": true,  "message": null } ``` **No TMS Field Updates** See additional Trimble documentation [here](https://developer.trimblemaps.com/restful-apis/trip-management/api-documentation/modify-trip/). ### **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. | TMS Trip Plan Segment Status | Trimble Route Status Value | Trimble Route Status | | --- | --- | --- | | Dispatched | 1 | Accepted | | Completed | 2 | Completed | | Configured | 4 | Received | | TMS Operation | Trimble Endpoint | Request Type | Response | | --- | --- | --- | --- | | Trip Plan Segment **Status** set to *Dispatched* | Update Trip Status | POST | 200: Success | 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*. > [!NOTE] > 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** | Object | Field | Type | Trimble Field | | --- | --- | --- | --- | | | | User Date/Time | timeStamp | | Fleet Asset | Geolocation | Geolocation | *lat, lon | | Trip Plan Segment | API Trip Id | Text(40) (External ID) | *tripId | | Trip Plan Segment | Status | Picklist | *status | **Fields marked with an asterisk are required.* Sample **Update Trip Status** Request Payload ```json {  "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 ```json {  "success": true,  "errorCode": 0 } ``` **No TMS Field Updates** **Update Trip Status Error Codes** | Error Code | Description | | --- | --- | | -1 | Trip can’t be found. | | -3 | Trip last modification happened after the timestamp of this request. | See additional Trimble documentation [here](https://developer.trimblemaps.com/restful-apis/trip-management/api-documentation/update-tripstatus/). ### **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 Operation | Trimble Endpoint | Request Type | Response | | --- | --- | --- | --- | | **View Trip** button | Get Trip | GET | 200: Success | **TMS Fields Sent in Get Trip call** | Object | Field | Type | Trimble Field | | --- | --- | --- | --- | | Trip Plan Segment | API Trip Id | Text(40) (External ID) | *tripId | **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 ```json {  "tripId": "Trip Plan Segment", } ``` Sample **Get Trip** Response Payload ```json {  "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](https://developer.trimblemaps.com/restful-apis/trip-management/api-documentation/get-trip/). ### **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 Operation | Trimble Endpoint | Request Type | Response | | --- | --- | --- | --- | | Trip Plan Segment deleted or set to *Undispatched* | Cancel Trip | POST | 200: Success | **TMS Fields Sent in Cancel Trip call** | Object | Field | Type | Trimble Field | | --- | --- | --- | --- | | Trip Plan Segment | API Trip Id | Text(40) (External ID) | *tripId | **Fields marked with an asterisk are required.* Sample **Cancel Trip** Request Payload ```json {  "tripId": "Trip Plan Segment", } ``` Sample **Cancel Trip** Response Payload ```json {  "success": true,  "message": null } ``` **TMS Field Updates** | Object | Field | Type | Field Update | | --- | --- | --- | --- | | Trip Plan Segment | API Trip Id | Text(40) (External ID) | Set to null | See additional Trimble documentation [here](https://developer.trimblemaps.com/restful-apis/trip-management/api-documentation/cancel-trip/). ### **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. > [!WARNING] > **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 Operation | Trimble Endpoint | Request Type | Response | | --- | --- | --- | --- | | Add the **Arrival Date** and **Time**, OR **Departure Date** and **Time** for a Trip Plan Leg | Update StopStatus | PUT | 200: Success | **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** | Object | Field | Type | Trimble Field | | --- | --- | --- | --- | | | | Stop Status API Value | *arrivalStatus | | | | **DateTimeNow() | *actualArrivalTime, actualDepartureTime | | Trip Plan Leg | Leg Number | Number(3, 0) | *stopId | | Trip Plan Leg | Status | Picklist | *stopState | | Trip Plan Segment | API Trip Id | Text(40) (External ID) | *tripId | | Trip Plan Segment | SFID | SFID | *tmsTripId | **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. | Arrival Status | Calculation | API Value | | --- | --- | --- | | Early | Arrival Time < Appointment Begin Time | 4 | | OnTime | Appointment Begin Time < Arrival Time < Appointment End Time (On Time) | 1 | | Late | Arrival Time > Appointment End Time (Late) | 3 | | Trip Plan Leg Status | Stop Status | API Value | | --- | --- | --- | | Dispatched | Arrived | 1 | | Completed | Completed/Departed | 2 | | Changes to the Trip Plan Leg | Reopen | 4 | Sample **Update StopStatus** Request Payload ```json {  "tripId": 136,  "stopId": 0,  "stopState": 2,  "actualDepartureTime": "2017-09-06T19:37:16+00:00",  "stopDuration": 32 } ``` Sample **Update Stop Status** Response Payload ```json {  "success": true,  "message": null } ``` **No TMS Field Updates** *A success is returned to the TMS.* See additional Trimble Update StopStatus documentation [here](https://developer.trimblemaps.com/restful-apis/trip-management/api-documentation/update-stopstatus/). ### **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 Operation | Trimble Endpoint | Request Type | Response | | --- | --- | --- | --- | | Fleet Management Job 1 Pass 3 Fleet Management Job 2 Pass 4 | Update Positions | POST | 200: Success | **TMS Fields sent in Update Positions call** | Object | Field | Type | Trimble Field | | --- | --- | --- | --- | | Fleet Asset | **ELD Last Update | Date/Time | deviceDt | | Fleet Asset | Geolocation | Geolocation | *Lat*,* Lon | | Fleet Asset | Heading (Degrees) | Number(3, 2) | heading | | Fleet Asset | Speed (kph), Speed (mph) | Number(10, 2) | speed | | Trip Plan Segment | API Trip Id | Text(40) (External ID) | *tripId | **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 ```json {  "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 ```json {  "success": true,  "message": null } ``` **No TMS Field Updates** See Trimble Update Positions documentation [here](https://developer.trimblemaps.com/restful-apis/trip-management/api-documentation/update-positions/). ## **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. > [!NOTE] > The time period, distance, interval, and update frequency settings for receiving notifications into the TMS are set per [Trimble](https://support.developer.trimblemaps.com/en/support/home/) 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** | Object | Field | Type | Trimble Field | | --- | --- | --- | --- | | Trip Event | Event Datetime | Date/Time | publishedOn | | Trip Event | Event Detail | Long Text Area(2000) | stopArrivalStatus + currentETA + plannedETA | | Trip Event | Event Type | Picklist | notificationType - set to *ETA Alert* by the TMS | | Trip Event | Is Alert | Checkbox | Field not sent by Trimble - set to *Checked* by the TMS | Sample **ETA EVENT** Notification Payload ```json {  "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** | Object | Field | Type | Trimble Field | | --- | --- | --- | --- | | Trip Event | Event Datetime | Date/Time | publishedOn | | Trip Event | Event Detail | Long Text Area(2000) | stopLocation ("Stop Status Update: " + address.streetAddress + address.city + address.state + address.zip) | | Trip Event | Event Type | Picklist | eventType (Arrival/Departed) | | Trip Plan Leg | Arrival Date | Date | publishedOn | | Trip Plan Leg | Arrival Time | Time | publishedOn | Sample **Stop Status Update** Notification Payload ```json {  "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** | Object | Field | Type | Trimble Field | | --- | --- | --- | --- | | Trip Event | Event Datetime | Date/Time | publishedOn | | Trip Event | Event Detail | Long Text Area(2000) | alertEvent + title + summary | | Trip Event | Event Type | Picklist | notificationType - set to *Weather Alert* by the TMS | | Trip Event | Is Alert | Checkbox | Field not sent by Trimble - set to *Checked* by the TMS | Sample **Weather** Notification Payload ```json {  "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** | Object | Field | Type | Trimble Field | | --- | --- | --- | --- | | Trip Event | Event Datetime | Date/Time | publishedOn | | Trip Event | Event Detail | Long Text Area(2000) | oorDistance | | Trip Event | Event Type | Picklist | notificationType - set to *Out of Route Alert* by the TMS | | Trip Event | Is Alert | Checkbox | Field not sent by Trimble - set to *Checked* by the TMS | Sample **Out of Route** Notification Payload ```json {  "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** | Object | Field | Type | Trimble Field | | --- | --- | --- | --- | | Trip Event | Event Datetime | Date/Time | publishedOn | | Trip Event | Event Detail | Long Text Area(2000) | oocDistance + status | | Trip Event | Event Type | Picklist | notificationType - set to *Out of Corridor Alert* by the TMS | | Trip Event | Is Alert | Checkbox | Field not sent by Trimble - set to *Checked* by the TMS | Sample **Out of Corridor** Notification Payload ```json {  "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** | Object | Field | Type | Trimble Field | | --- | --- | --- | --- | | Trip Event | Event Datetime | Date/Time | publishedOn | | Trip Event | Event Detail | Long Text Area(2000) | shortDesc | | Trip Event | Event Type | Picklist | notificationType - set to *Traffic Alert* by the TMS | | Trip Event | Is Alert | Checkbox | Field not sent by Trimble - set to *Checked* by the TMS | Sample **Traffic** Notification Payload ```json {  "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** | Object | Field | Type | Trimble Field | | --- | --- | --- | --- | | Trip Event | Event Datetime | Date/Time | publishedOn | | Trip Event | Event Detail | Long Text Area(2000) | message | | Trip Event | Event Type | Picklist | notificationType - set to *Approaching* by the TMS | | Trip Event | Is Alert | Checkbox | Field not sent by Trimble - set to *Checked* by the TMS | Sample **Approaching Stop** Notification Payload ```json {  "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** | Object | Field | Type | Trimble Field | | --- | --- | --- | --- | | Trip Event | Event Datetime | Date/Time | publishedOn | | Trip Event | Event Detail | Long Text Area(2000) | message + plannedDuration + currentDuration + plannedETA | | Trip Event | Event Type | Picklist | notificationType - set to *Dwell Exceeded Alert* by the TMS | | Trip Event | Is Alert | Checkbox | Field not sent by Trimble - set to *Checked* by the TMS | Sample **Excessive Dwell** Notification Payload ```json {  "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](https://developer.trimblemaps.com/restful-apis/trip-management/notifications-service/). ## **Field Reference Table** The following table relates TMS fields with the equivalent Trimble fields included in Trimble API calls. | Object | Field | Type | Trimble Field | | --- | --- | --- | --- | | Driver | Cycle Time Remaining | Number(3, 2) | RemainingCycleDutyTime | | Driver | Drive Time Remaining | Number(3, 2) | RemainingDriveTime | | Driver | SFID | SFID | tspDriverId | | Driver | Time Until Break | Number(3, 2) | RemainingDriveTimeUntilBreak | | | | DateTimeNow() | actualArrivalTime, actualDepartureTime | | | | Number | stopSequence | | | | Stop Status API Value | arrivalStatus | | | | User Date/Time | timeStamp | | | | “Work” | stopType | | Fleet Asset | ELD Last Update | Date/Time | deviceDt | | Fleet Asset | Geolocation | Geolocation | Lat*,* Lon | | Fleet Asset | Heading (Degrees) | Number(3, 2) | heading | | Fleet Asset | Speed (kph), Speed (mph) | Number(10, 2) | speed | | Trip Event | Event Datetime | Date/Time | publishedOn | | Trip Event | Event Detail | Long Text Area(2000) | alertEvent + title + summary | | Trip Event | Event Detail | Long Text Area(2000) | message | | Trip Event | Event Detail | Long Text Area(2000) | message + plannedDuration + currentDuration + plannedETA | | Trip Event | Event Detail | Long Text Area(2000) | oocDistance + status | | Trip Event | Event Detail | Long Text Area(2000) | oorDistance | | Trip Event | Event Detail | Long Text Area(2000) | shortDesc | | Trip Event | Event Detail | Long Text Area(2000) | stopLocation ("Stop Status Update: " + address.streetAddress + address.city + address.state + address.zip) | | Trip Event | Event Detail | Long Text Area(2000) | stopArrivalStatus + currentETA + plannedETA | | Trip Event | Event Type | Picklist | eventType (Arrival/Departed) | | Trip Event | Event Type | Picklist | notificationType - set to *Approaching* by the TMS | | Trip Event | Event Type | Picklist | notificationType - set to *Dwell Exceeded Alert* by the TMS | | Trip Event | Event Type | Picklist | notificationType - set to *ETA Alert* by the TMS | | Trip Event | Event Type | Picklist | notificationType - set to *Out of Corridor Alert* by the TMS | | Trip Event | Event Type | Picklist | notificationType - set to *Out of Route Alert* by the TMS | | Trip Event | Event Type | Picklist | notificationType - set to *Traffic Alert* by the TMS | | Trip Event | Event Type | Picklist | notificationType - set to *Weather Alert* by the TMS | | Trip Event | Is Alert | Checkbox | | | Trip Plan | Name | Auto Number | name | | Trip Plan Leg | Appointment Date | Date | earliestArrivalTime, latestArrivalTime | | Trip Plan Leg | Appointment End Time | Time | latestArrivalTime | | Trip Plan Leg | Appointment End Time - Due Out Time | Time | plannedDuration | | Trip Plan Leg | Appointment Start Time | Time | earliestArrivalTime | | Trip Plan Leg | Arrival Date | Date | publishedOn | | Trip Plan Leg | Arrival Time | Time | publishedOn | | Trip Plan Leg | Due Out Date | Date | plannedStartTime, plannedDepartureTime | | Trip Plan Leg | Due Out Time | Time | plannedStartTime, plannedDepartureTime | | Trip Plan Leg | Leg Number | Number(3, 0) | stopId | | Trip Plan Leg | Start City | Text(40) | city | | Trip Plan Leg | Start Geolocation | Geolocation | lat, lon | | Trip Plan Leg | Start Postal Code | Text(20) | zip | | Trip Plan Leg | Start State/Province | Picklist | state | | Trip Plan Leg | Start Street Address | Text(100) | street address | | Trip Plan Leg | Status | Picklist | stopState | | Trip Plan Segment | API Trip Id | Text(40) (External ID) | tripId | | Trip Plan Segment | SFID | SFID | tmsTripId | | Trip Plan Segment | Load | Lookup(Load) | externalOrderIds | | Trip Plan Segment | Name | Text(80) | name | | Trip Plan Segment | Power Unit | Lookup(Fleet Asset) | tspVehicleId | | Trip Plan Segment | Status | Picklist | status | The Salesforce ID, a record identifier comprised of 15 or 18 characters.