TruckMate 2024.1 New Features: Web/APIs

Required upgrade (TM-173710)

TruckMate 2024.1 and later requires DB2 version 11.5.9.

You must upgrade your instance of DB2 to this version before upgrading TruckMate.

The TruckMate ART Server is a high-performance, multi-threaded HTTP server running TruckMate API services designed using Representational State Transfer (RESTful) API principles.

The ART Server currently supports the following public APIs:

TruckMate REST API Bundle
Master Data APIs
Freight Bill Import
Profile Import
Imaging

The API release notes cover all changes made to all TruckMate public APIs.

TruckMate API

Public link: https://truckmatecloudhub.trimble-transportation.com/tm/documentation

The TruckMate REST APIs are a comprehensive set of RESTful services, allowing developers to integrate TruckMate with custom or third-party applications, automate tasks, and much more.

Some ways you can use these APIs include:

Internal systems: Share data and streamline internal business processes
External data sharing and connection: Share TruckMate data with third party systems
Application integrations: Access TruckMate data in real time
Embedded content: Request TruckMate data to include onto your site

Available endpoints and methods differ depending on the license keys and authorization methods used.

To use the TruckMate REST APIs, we recommend upgrading directly to the latest version of TruckMate instead of an earlier release. This gives you access to the most current, improved, and expanded set of API methods and endpoints.

The following additional information is available on the Trimble Transportation Learning Center:

TruckMate REST API Service Getting Started
The TM4Web OpenAPI JSON information can be viewed as a website.

This may be especially useful if you are in the early stages of implementing REST APIs and do not have an ART Server running yet.
The OpenAPI JSON file itself is available for downloading.
ART Server Administrator Guide

These tables list issues in alphabetical order by case number.

Orders API

Case Issue	Case Name	Description
TM-171941	POST PTLORDER custom-defined fields	Creating a new "pickup request" order can now include the custom-defined fields. These fields can also be added after the "pickup request" order is created so long as the order does not already have custom-defined fields.
TM-172316	Creating orders with two or more dangerous goods flag set and UN numbers via API caused same UN number to be assigned on the Dangerous Goods tab	Fixed an issue where creating orders with detail lines that referenced distinct UN numbers through the Orders API would result in duplicate records on the Dangerous Goods section of the order.
TM-173046	POST Orders fails with invalid email format
TM-173274	webUsers GET /orders?type=Q	Added support for web user authorization (client web users) for quotes: (GET orders?type=Q GET orders/{\orderId}?type=Q).
TM-173279	ART $filter supports operator - contains	Improved the $filter parameter implementation, adding support for the "contains" operator, allowing for substring matching within fields. In addition, support was added for the "or" operator expanding query capabilities by allowing multiple conditions to be evaluated.

Case Issue

Case Name

Description

TM-171941

POST PTLORDER custom-defined fields

Creating a new "pickup request" order can now include the custom-defined fields. These fields can also be added after the "pickup request" order is created so long as the order does not already have custom-defined fields.

TM-172316

Creating orders with two or more dangerous goods flag set and UN numbers via API caused same UN number to be assigned on the Dangerous Goods tab

Fixed an issue where creating orders with detail lines that referenced distinct UN numbers through the Orders API would result in duplicate records on the Dangerous Goods section of the order.

TM-173046

POST Orders fails with invalid email format

TM-173274

webUsers GET /orders?type=Q

Added support for web user authorization (client web users) for quotes:

(GET orders?type=Q
GET orders/{\orderId}?type=Q).

TM-173279

ART $filter supports operator - contains

Improved the $filter parameter implementation, adding support for the "contains" operator, allowing for substring matching within fields. In addition, support was added for the "or" operator expanding query capabilities by allowing multiple conditions to be evaluated.

Trips API

Case Issue	Case Name	Description
TM-166095	ART GetTripsAPI should not call mileage server via PopulateStopList	When Trip Stop Geocoding is disabled, there will be no call sent to the mileage server to get the latitude and longtitude of the stops involved in a trip. The values "0000000N" and "0000000E" will be populated to lat and long fields in the response. Notes: If the stop-clientId has latitude and longitude included in its profile, the latitude and longitude will be populated from the profile instead of the mileage server. Trip Stop Geocoding can be configured in Application Configurator with the ART > Disable Trip Stop Geocoding options.
TM-172738	REST API - GET /trips is not an accurate Trip Stops snapshot	Fixed an issue where the resources allocated to stops returned by the Trips API was not consistent with stop data in the trip optimizer.
TM-172780	Geocoding of stops is not respecting the default mileage profile	Fixed and issue where the default mileage profile was not respected in getting lat/long of a stop.

Case Issue

Case Name

Description

TM-166095

ART GetTripsAPI should not call mileage server via PopulateStopList

When Trip Stop Geocoding is disabled, there will be no call sent to the mileage server to get the latitude and longtitude of the stops involved in a trip. The values "0000000N" and "0000000E" will be populated to lat and long fields in the response.

Notes:

If the stop-clientId has latitude and longitude included in its profile, the latitude and longitude will be populated from the profile instead of the mileage server.
Trip Stop Geocoding can be configured in Application Configurator with the ART > Disable Trip Stop Geocoding options.

TM-172738

REST API - GET /trips is not an accurate Trip Stops snapshot

Fixed an issue where the resources allocated to stops returned by the Trips API was not consistent with stop data in the trip optimizer.

TM-172780

Geocoding of stops is not respecting the default mileage profile

Fixed and issue where the default mileage profile was not respected in getting lat/long of a stop.

Master Data API

Public link: https://truckmatecloudhub.trimble-transportation.com/masterData/documentation

The Master Data management API allows an external system to create, retrieve, update or delete TruckMate configuration data.Some data types include client, vendor and driver profiles, as well as sites, zones, commodity codes, etc.

Case Issue Case Name Description

Case Issue	Case Name	Description
TM-159558	MasterData GET /units
TM-172169	Add Rating Method to Master Data API	For a given client in Customer and Vendor Profiles, you can specify a "master client" that has all the desired rating method rules. This is done by entering a master client code in the Rate By Method field, which exists on the Client Rating subtab of the Rating tab. The /masterData/clients endpoint has been updated to allow specifying this field during a POST or PUT. In the API, the field is called `ratingMethodClientId`. In the request, you specify the master client code.
TM-172939	GET masterData/serviceLevels	Added support for retrieving service level records in the masterData REST API. GET masterData/serviceLevels GET masterData/serviceLevels/:serviceLevelId
TM-173279	ART $filter supports operator - contains	Improved the $filter parameter implementation, adding support for the "contains" operator, allowing for substring matching within fields. In addition, support was added for the "or" operator expanding query capabilities by allowing multiple conditions to be evaluated.

TM-159558

MasterData GET /units

TM-172169

Add Rating Method to Master Data API

For a given client in Customer and Vendor Profiles, you can specify a "master client" that has all the desired rating method rules. This is done by entering a master client code in the Rate By Method field, which exists on the Client Rating subtab of the Rating tab.

The /masterData/clients endpoint has been updated to allow specifying this field during a POST or PUT. In the API, the field is called ratingMethodClientId. In the request, you specify the master client code.

TM-172939

GET masterData/serviceLevels

Added support for retrieving service level records in the masterData REST API.

GET masterData/serviceLevels
GET masterData/serviceLevels/:serviceLevelId

TM-173279

ART $filter supports operator - contains

Other APIs

Case Issue	Case Name	Description
TM-172291	TM API Trips Stops are missing time component value for field appointmentTime	When the stop records are retrieved via GET-trip endpoints, the appointmentTime and appointmentTimeEnd fields are populated in DateTimeToISO8601 format based on the stop type. If the stop type is 'pick', the two date-time fields are populated with the 'Pick Up' time fields set in Customer Service. If the stop type is 'drop', the two date-time fields are populated with the 'Deliver' time fields set in Customer Service.
TM-172347	Pickup / Delivery Dates getting updated by TruckMate RESTful API service
TM-173265	Replace use of TMS_ORDERS_FILTERED
TM-173400	unNumber in serverDefaultValues does not match automation environment
TM-173414	Allow case-insensitive filtering in ART using $filter	Added support for oData filtering tolower operator to allow for case-insensitive filtering in the TruckMate and MasterData REST APIs.

Case Issue

Case Name

Description

TM-172291

TM API Trips Stops are missing time component value for field appointmentTime

When the stop records are retrieved via GET-trip endpoints, the appointmentTime and appointmentTimeEnd fields are populated in DateTimeToISO8601 format based on the stop type.

If the stop type is 'pick', the two date-time fields are populated with the 'Pick Up' time fields set in Customer Service.
If the stop type is 'drop', the two date-time fields are populated with the 'Deliver' time fields set in Customer Service.

TM-172347

Pickup / Delivery Dates getting updated by TruckMate RESTful API service

TM-173265

Replace use of TMS_ORDERS_FILTERED

TM-173400

unNumber in serverDefaultValues does not match automation environment

TM-173414

Allow case-insensitive filtering in ART using $filter

Added support for oData filtering tolower operator to allow for case-insensitive filtering in the TruckMate and MasterData REST APIs.

TM4Web

Case Issue	Case Name	Description
TM-172136	Remove DROPDOWN references in favor of COUNTRY_SUBDIVISION	Fixed an issue where the State dropdown within TM4Web was pulling from the wrong source of data in TruckMate. This has now been adjusted to use the COUNTRY and COUNTRY_SUBDIVISION tables, rather than DROPDOWN. Fixed an issue where if a country was selected that had no defined states/provinces, you would be unable to proceed with updating the form. This has been corrected so that if a country contains no states/provinces, you can proceed with the update.
TM-172281	TM4Web Bill Details are not displayed for Agent Deliveries	Fixed Agent Deliveries page loading issue if no web enabled Service Failure Codes have been configured, adding a warning message to the TM4Web log file.
TM-172987	Hidden Commodity Fields cause Unit and Unit Type requirements in TM4Web	Fixed an issue where unit fields were being incorrectly marked as required in TM4Web Order Entry / Details grid even though Web Administration has the related fields not configured to be marked as required.

Case Issue

Case Name

Description

TM-172136

Remove DROPDOWN references in favor of COUNTRY_SUBDIVISION

Fixed an issue where the State dropdown within TM4Web was pulling from the wrong source of data in TruckMate. This has now been adjusted to use the COUNTRY and COUNTRY_SUBDIVISION tables, rather than DROPDOWN.
Fixed an issue where if a country was selected that had no defined states/provinces, you would be unable to proceed with updating the form. This has been corrected so that if a country contains no states/provinces, you can proceed with the update.

TM-172281

TM4Web Bill Details are not displayed for Agent Deliveries

Fixed Agent Deliveries page loading issue if no web enabled Service Failure Codes have been configured, adding a warning message to the TM4Web log file.

TM-172987

Hidden Commodity Fields cause Unit and Unit Type requirements in TM4Web

Fixed an issue where unit fields were being incorrectly marked as required in TM4Web Order Entry / Details grid even though Web Administration has the related fields not configured to be marked as required.