TruckMate 2024.4 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 these public APIs:

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

Freight Bill Import and Profile Import were deprecated in March 2024. These APIs will be removed in TruckMate 2025.2. Customers should convert to REST and MasterData APIs.

For more information, see TruckMate REST API service replaces TM4Web REST APIs.

The API release notes cover all changes made to 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.

These tables list issues in numerical order by case number.

Orders API

Case Issue	Case Name	Description
TM-171939	Bill number values should be limited to 17 characters and not 20 to support child /intermodal bills to be created off that record	Fixed an issue where the Orders API could post bill number values that were greater than 17 characters which creates issues if extra stops or intermodal bills are generated from the related order.
TM-172710	Sort order not incrementing properly when an order details record is created in the API.	Fixed an issue related to the Sort order not being incremented properly.
TM-176285	GET /orders - Vendor Web User - Fields returned should be limited	Vendor Web Users can now retrieve order fields based on WebAdmin > Vendor Feature > Load Offers > Vendor Load Offer Fields, while TID Vendor Users will receive all fields defined in the ART order schema.
TM-176573	ART - return only orders.totalCharges for web auth user	For TID Web Client users, the fields tax1, tax2, charges, and totalCharges are always included in the response for mapping the Bill Summary section in the TMS Connector.
TM-177483	POST /orders invalidJsonObject returned when using copyOrderId option	Fixed issue where using the copyOrderId option in the POST orders endpoint was resulting in an invalidJsonObject error message.
TM-177615	POST orders?type=Q invalidDBValue not returned	Fixed the error message returned when using an invalid client ID value for contacts client ID field value to return the invalidDBValue error code. Also, incorrectly formatted postal codes will return the invalidBusinessLogic error code when the related app config option is enabled.
TM-177856	Orders API - dangerousGoods - Add shippingName field (GET)	Added a new field called shippingName to dangerousGoods response object.
TM-177901	Barcodes are not being created automatically when items are populated in order details.	Fixed an issue with barcodes not being created automatically when items are populated in order details.
TM-178642	Orders API - Always return createdTime, pickUpByEnd, deliverByEnd when using TID for client web user	Orders API should return the createdTime, pickUpByEnd, and deliverByEnd fields when using a TID for client web users.

Case Issue

Case Name

Description

TM-171939

Bill number values should be limited to 17 characters and not 20 to support child /intermodal bills to be created off that record

Fixed an issue where the Orders API could post bill number values that were greater than 17 characters which creates issues if extra stops or intermodal bills are generated from the related order.

TM-172710

Sort order not incrementing properly when an order details record is created in the API.

Fixed an issue related to the Sort order not being incremented properly.

TM-176285

GET /orders - Vendor Web User - Fields returned should be limited

Vendor Web Users can now retrieve order fields based on WebAdmin > Vendor Feature > Load Offers > Vendor Load Offer Fields, while TID Vendor Users will receive all fields defined in the ART order schema.

TM-176573

ART - return only orders.totalCharges for web auth user

For TID Web Client users, the fields tax1, tax2, charges, and totalCharges are always included in the response for mapping the Bill Summary section in the TMS Connector.

TM-177483

POST /orders invalidJsonObject returned when using copyOrderId option

Fixed issue where using the copyOrderId option in the POST orders endpoint was resulting in an invalidJsonObject error message.

TM-177615

POST orders?type=Q invalidDBValue not returned

Fixed the error message returned when using an invalid client ID value for contacts client ID field value to return the invalidDBValue error code. Also, incorrectly formatted postal codes will return the invalidBusinessLogic error code when the related app config option is enabled.

TM-177856

Orders API - dangerousGoods - Add shippingName field (GET)

Added a new field called shippingName to dangerousGoods response object.

TM-177901

Barcodes are not being created automatically when items are populated in order details.

Fixed an issue with barcodes not being created automatically when items are populated in order details.

TM-178642

Orders API - Always return createdTime, pickUpByEnd, deliverByEnd when using TID for client web user

Orders API should return the createdTime, pickUpByEnd, and deliverByEnd fields when using a TID for client web users.

Trips API

Case Issue	Case Name	Description
TM-174159	Extract statuscode and zone defaulting from statchg	Made a modification to the Trip Status change logic in TruckMate to improve how the code functions within the overall product. Customers will be unlikely to notice any visible changes as a result of these modifications; these changes are all back-end adjustments to how the workflow will function overall. Additional notes on these changes can be found in the TruckMate 2024.3 Release Notes.
TM-174160	Extract the TL trip status change code from statchg	Made a modification to the Trip Status change logic in TruckMate to improve how the code functions within the overall product. Customers will be unlikely to notice any visible changes as a result of these modifications; these changes are all back-end adjustments to how the workflow will function overall. Additional notes on these changes can be found in the TruckMate 2024.3 Release Notes.
TM-177533	Trips API - more than one Terminal shares the same Base Route	Fixed a validation issue in the trips API when creating a P&D trip (POST /trips) using terminal zones that use a route that is shared among multiple terminals.
TM-177563	ART - PUT loadSummaryId endpoints - Update the Error Description	The error descriptions for the 400 errors have been updated to accurately reflect the cause, with modifications affecting the TM-Trips collection
TM-177805	'Route ID' not exposed to GET method of /trips API	Added routeId field to the trips API. GET /trips GET /trips/:tripNumber
TM-177838	ART - GET trips - add totalCarrierCost and totalCarrierDistance	Added two summary fields, totalCarrierCost and totalCarrierDistance, to the trips API that provide the total carrier cost and distance as it relates to carrier records on the trip. GET /trips GET /trips/:tripNumber
TM-177902	Dev: Minimal Implementation to allow the update of the start zone or end zone on a Trip for D&R GTA Go Live	Added support for updating trips' start and end zones using the trips API. PUT tm/trips/:tripNumber
TM-178051	TM Rest api trips stops/resources do not expand and show	Fixed an issue where stop resources were not being returned correctly in the trips API for some trip records.
TM-179242	GET trips - Move totalCarrierCost and totalCarrierDistance into tripSummary child resource	Moved totalCarrierCost and totalCarrierDistance fields into the tripSummary child resource in the Trips API. GET /trips/:tripNumber/tripSummary

Case Issue

Case Name

Description

TM-174159

Extract statuscode and zone defaulting from statchg

Made a modification to the Trip Status change logic in TruckMate to improve how the code functions within the overall product.

Customers will be unlikely to notice any visible changes as a result of these modifications; these changes are all back-end adjustments to how the workflow will function overall.

Additional notes on these changes can be found in the TruckMate 2024.3 Release Notes.

TM-174160

Extract the TL trip status change code from statchg

Made a modification to the Trip Status change logic in TruckMate to improve how the code functions within the overall product.

Customers will be unlikely to notice any visible changes as a result of these modifications; these changes are all back-end adjustments to how the workflow will function overall.

Additional notes on these changes can be found in the TruckMate 2024.3 Release Notes.

TM-177533

Trips API - more than one Terminal shares the same Base Route

Fixed a validation issue in the trips API when creating a P&D trip (POST /trips) using terminal zones that use a route that is shared among multiple terminals.

TM-177563

ART - PUT loadSummaryId endpoints - Update the Error Description

The error descriptions for the 400 errors have been updated to accurately reflect the cause, with modifications affecting the TM-Trips collection

TM-177805

'Route ID' not exposed to GET method of /trips API

Added routeId field to the trips API.

GET /trips
GET /trips/:tripNumber

TM-177838

ART - GET trips - add totalCarrierCost and totalCarrierDistance

Added two summary fields, totalCarrierCost and totalCarrierDistance, to the trips API that provide the total carrier cost and distance as it relates to carrier records on the trip.

GET /trips
GET /trips/:tripNumber

TM-177902

Dev: Minimal Implementation to allow the update of the start zone or end zone on a Trip for D&R GTA Go Live

Added support for updating trips' start and end zones using the trips API.

PUT tm/trips/:tripNumber

TM-178051

TM Rest api trips stops/resources do not expand and show

Fixed an issue where stop resources were not being returned correctly in the trips API for some trip records.

TM-179242

GET trips - Move totalCarrierCost and totalCarrierDistance into tripSummary child resource

Moved totalCarrierCost and totalCarrierDistance fields into the tripSummary child resource in the Trips API.

GET /trips/:tripNumber/tripSummary

Finance API

Case Issue	Case Name	Description
TM-178722	Add endpoint PUT /finance/currencyRates/:currencyRateId	Add support for the retrieval, creation, update and deletion of currency rate records for driver pay and general ledger in the Finance REST API: GET /finance/currencyRates POST /finance/currencyRates GET /finance/currencyRates:/currencyRateId PUT /finance/currencyRates:/currencyRateId DELETE /finance/currencyRates:/currencyRateId

Case Issue

Case Name

Description

TM-178722

Add endpoint PUT /finance/currencyRates/:currencyRateId

Add support for the retrieval, creation, update and deletion of currency rate records for driver pay and general ledger in the Finance REST API:

GET /finance/currencyRates
POST /finance/currencyRates
GET /finance/currencyRates:/currencyRateId
PUT /finance/currencyRates:/currencyRateId
DELETE /finance/currencyRates:/currencyRateId

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, and so on.

Case Issue	Case Name	Description
TM-166244	masterData - POST /drivers	Added support for POST /drivers and PUT /drivers/:driverId endpoints in the masterData REST API.
TM-173630	ART - Add codesByTripNumber parameter to masterData statusCodes endpoint	Added a new query parameter, codesByTripNumber, to the GET /statusCodes endpoint in the masterData REST API which can be used to retrieve the list of all possible next status codes for a given trip number value. Also, a new query parameter, tripNewStatus, has been added to the GET /zones endpoint in the masterData REST API which can be used together with the codesByTripNumber query parameter to retrieve a default zone for a trip given a new trip status value.
TM-175949	Data Governance mapping - Driver Availability	Added a new endpoint to the drivers API in the masterData REST API which provides the drivers projected availability. GET drivers/:driverId/availability
TM-177489	ART - GET drivers - Add fields for data governance	Added more fields to the following driver endpoints in the MasterData REST API, such as driver address information, contact information to allow for more complete information in the response payload. GET drivers GET drivers/driverId
TM-177846	create new ClientCommonDM library for common client code	A new library lib\ClientCommonDM was created. This lib will contain common client validations and other client-related functions/procedures that can possibly be shared between ART and delphi applications which can both access it since it is in a library. The ClientCommonDM library created here is just the basic lib, and functionality will be added in other JIRAs.
TM-178294	create new function validateClientBeforeDelete in lib\ClientCommonDM	masterData API - client deletion - Internal change - migrated some of the validations that are done before deleting a client to a new centralized library.
TM-179283	Unable to link existing employee to an existing driver or vice versa	Fixed an issue where an existing employee could not be linked to an existing driver or vice versa.

Case Issue

Case Name

Description

TM-166244

masterData - POST /drivers

Added support for POST /drivers and PUT /drivers/:driverId endpoints in the masterData REST API.

TM-173630

ART - Add codesByTripNumber parameter to masterData statusCodes endpoint

Added a new query parameter, codesByTripNumber, to the GET /statusCodes endpoint in the masterData REST API which can be used to retrieve the list of all possible next status codes for a given trip number value.

Also, a new query parameter, tripNewStatus, has been added to the GET /zones endpoint in the masterData REST API which can be used together with the codesByTripNumber query parameter to retrieve a default zone for a trip given a new trip status value.

TM-175949

Data Governance mapping - Driver Availability

Added a new endpoint to the drivers API in the masterData REST API which provides the drivers projected availability.

GET drivers/:driverId/availability

TM-177489

ART - GET drivers - Add fields for data governance

Added more fields to the following driver endpoints in the MasterData REST API, such as driver address information, contact information to allow for more complete information in the response payload.

GET drivers
GET drivers/driverId

TM-177846

create new ClientCommonDM library for common client code

A new library lib\ClientCommonDM was created. This lib will contain common client validations and other client-related functions/procedures that can possibly be shared between ART and delphi applications which can both access it since it is in a library. The ClientCommonDM library created here is just the basic lib, and functionality will be added in other JIRAs.

TM-178294

create new function validateClientBeforeDelete in lib\ClientCommonDM

masterData API - client deletion - Internal change - migrated some of the validations that are done before deleting a client to a new centralized library.

TM-179283

Unable to link existing employee to an existing driver or vice versa

Fixed an issue where an existing employee could not be linked to an existing driver or vice versa.

Other APIs

Case Issue	Case Name	Description
TM-166550	ConnectedDock terminal endpoint	Created OpenAPI documentation for Terminal resources in ConnectedDock application, including ichild-resource expand options.
TM-166551	ConnectedDock doors endpoint	Updated the ConnectedDock openAPI documentation to include the following endpoints: GET /doors GET /doors/:doorId GET /terminals/:terminalId/doors GET /terminals/:terminalId/doors/:doorId
TM-166552	ConnectedDock users endpoint	Created openAPI document for the DockUsers of ConnectedDock application, including expand as a parameter.
TM-166553	ConnectedDock trips endpoint	Removed the description for the GET /dock/trips endpoint from the OpenAPI document.
TM-166554	ConnectedDock orders endpoint	Created OpenAPI documentation for DockOrder and added support for expanding child resources in the ConnectedDock API.
TM-166557	ConnectedDock configs endpoint	Amended OpenAPI configuration for the configs endpoint in Connected Dock API. Added pagination parameters, increased theValue field limit size, and 401 will be returned for empty or incorrect authorization values.
TM-166577	ConnectedDock company endpoint	Added the company endpoint to the ConnectedDock openAPI.json.
TM-174075	TruckMate API - Missing count field	Added count field to the response body in the TruckMate REST API for the following endpoints: GET /reports GET /webUsers GET /webAddressBook
TM-177951	Performance: Fix API views - LIMIT key word performance issue	Updated query used to retrieve order and trip records in the TruckMate REST API and client records in the Master Data API to follow DB2 recommendations around the usage of limit and offset for optimal performance. GET tm/orders GET tm/trips GET masterData/clients
TM-178198	Add a GET to pull REFER Settings from TruckMate	Add support to retrieve trip reefer monitoring settings using the TruckMate REST API GET /tm/tripReeferMonitoring.
TM-178390	Documents API - Fix semantic error on openAPI document	Fixed semantic error in the OpenAPI document for the Documents endpoint in TM - TruckMate.
TM-178466	ART - distinction between null, empty string and a field not present	Fixed an issue in the Orders API where pre-populated values from client profile when entering a client ID could not be overridden with a blank string value.
TM-178695	Deprecate FB Import REST API	Added deprecation header and marked endpoints as deprecated in the FB Import REST API. Also updated the service description on the openAPI document and in the ART server administrator.

Case Issue

Case Name

Description

TM-166550

ConnectedDock terminal endpoint

Created OpenAPI documentation for Terminal resources in ConnectedDock application, including ichild-resource expand options.

TM-166551

ConnectedDock doors endpoint

Updated the ConnectedDock openAPI documentation to include the following endpoints:

GET /doors
GET /doors/:doorId
GET /terminals/:terminalId/doors
GET /terminals/:terminalId/doors/:doorId

TM-166552

ConnectedDock users endpoint

Created openAPI document for the DockUsers of ConnectedDock application, including expand as a parameter.

TM-166553

ConnectedDock trips endpoint

Removed the description for the GET /dock/trips endpoint from the OpenAPI document.

TM-166554

ConnectedDock orders endpoint

Created OpenAPI documentation for DockOrder and added support for expanding child resources in the ConnectedDock API.

TM-166557

ConnectedDock configs endpoint

Amended OpenAPI configuration for the configs endpoint in Connected Dock API. Added pagination parameters, increased theValue field limit size, and 401 will be returned for empty or incorrect authorization values.

TM-166577

ConnectedDock company endpoint

Added the company endpoint to the ConnectedDock openAPI.json.

TM-174075

TruckMate API - Missing count field

Added count field to the response body in the TruckMate REST API for the following endpoints:

GET /reports
GET /webUsers
GET /webAddressBook

TM-177951

Performance: Fix API views - LIMIT key word performance issue

Updated query used to retrieve order and trip records in the TruckMate REST API and client records in the Master Data API to follow DB2 recommendations around the usage of limit and offset for optimal performance.

GET tm/orders
GET tm/trips
GET masterData/clients

TM-178198

Add a GET to pull REFER Settings from TruckMate

Add support to retrieve trip reefer monitoring settings using the TruckMate REST API GET /tm/tripReeferMonitoring.

TM-178390

Documents API - Fix semantic error on openAPI document

Fixed semantic error in the OpenAPI document for the Documents endpoint in TM - TruckMate.

TM-178466

ART - distinction between null, empty string and a field not present

Fixed an issue in the Orders API where pre-populated values from client profile when entering a client ID could not be overridden with a blank string value.

TM-178695

Deprecate FB Import REST API

Added deprecation header and marked endpoints as deprecated in the FB Import REST API. Also updated the service description on the openAPI document and in the ART server administrator.

TM4Web

Case Issue	Case Name	Description
TM-175462	Upgrade PHP to 8.3 and Apache 2.4.62	Updated TruckMate 24.4 installer to install PHP 8.3 and Apache 2.4.62 for the web server and API installation.
TM-178530	TM4Web - Order Entry - Unable to save/hold/complete since the user is getting system error	Fixed an issue where a 500 error was being encountered when submitting a pickup request using the Order Entry page in TM4Web due to missing parameters.
TM-178637	TM4Web Address Book page not loading for certain Access Codes	Fixed an issue where address book records were not loading correctly for some TM4Web access codes.
TM-179615	TM4Web Excel button not exporting page vendor_combined.msw	Fixed an issue where the Excel button was returning a 500 error on the Accepted and Assigned Orders vendors page in TM4Web.
TM-179858	TM4Web Vendor L-Haul Trip Status Zone Lookup error Failed to submit form	Fixed an issue where zone lookup form was returning an error on the vendor linehaul trip status updates page. This is an issue where SSL (https) is handled outside of the Apache instance (https request is forwarded to a http instance).

Case Issue

Case Name

Description

TM-175462

Upgrade PHP to 8.3 and Apache 2.4.62

Updated TruckMate 24.4 installer to install PHP 8.3 and Apache 2.4.62 for the web server and API installation.

TM-178530

TM4Web - Order Entry - Unable to save/hold/complete since the user is getting system error

Fixed an issue where a 500 error was being encountered when submitting a pickup request using the Order Entry page in TM4Web due to missing parameters.

TM-178637

TM4Web Address Book page not loading for certain Access Codes

Fixed an issue where address book records were not loading correctly for some TM4Web access codes.

TM-179615

TM4Web Excel button not exporting page vendor_combined.msw

Fixed an issue where the Excel button was returning a 500 error on the Accepted and Assigned Orders vendors page in TM4Web.

TM-179858

TM4Web Vendor L-Haul Trip Status Zone Lookup error Failed to submit form

Fixed an issue where zone lookup form was returning an error on the vendor linehaul trip status updates page. This is an issue where SSL (https) is handled outside of the Apache instance (https request is forwarded to a http instance).