TruckMate 2022.3 New Features: Web/APIs

Required upgrade (TM-162557)

TruckMate 2022.x and later requires DB2 version 11.5.6.

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

Support for DB2 version 11.1.3 ended as of TruckMate 2021.4.

You may experience slightly longer upgrade times with this version of TruckMate. This is because extra processing is being done on the back end to ensure that everything works successfully. Contact TruckMate Support with any concerns.

This guide covers changes made to all TruckMate public APIs.

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

This table lists issues in alphabetical order by case number.

Case Number Case Name Release Notes

Case Number	Case Name	Release Notes
TM-139500	allow DELETE /orders/:orderId/details/:orderDetailId	Add a new function to delete an order-details by detail id and order id
TM-141881	Add contacts unit field to request	Added unit field to request and response bodies of caller, shipper, consignee, careOf, pickupAt and otherContact [#TM-151987]
TM-151987	New masterData ratingMethodRules endpoint added to the /masterData/clients/{clientId} query methods	Two new fields, minFBCube and maxFBCube, have been added to the POST PUT and GET methods for: `/masterData/clients/\{clientId/tariffClasses}` `/masterData/clients/\{clientId/tariffClasses}/{tariffClassId}` These fields hold the values for the lower and higher ranges of the cube condition of the tariff class rule.
TM-159561	Move commodities endpoint from /tm to new service	Moved commodities endpoint from ART TruckMate service to MasterData service
TM-160915	Implement remote log server on ART	Added support for remote ART logging to an external server address.
TM-163043	Adding SQL meta data to logs - ARTController	Added the following fields to the ART log files: SQL string parameter result execution time
TM-163044	Adding SQL meta data to logs - Orders - GET and DELETE endpoints	Added the following fields to the ART log files that are related to Orders GET and DELETE endpoints: SQL string parameter result execution time
TM-163045	Adding SQL meta data to logs - Trips - GET and DELETE endpoints	Added the following fields to the ART log files that are related to Trips GET and DELETE endpoints: SQL string parameter result execution time
TM-163129	New companyId query parameter	A new `companyId` query parameter was added to the Imaging `POST /carrierassignments/acceptcontract` API endpoint. This allows you to get the value of an app configuration option based on the company ID.
TM-164194	PUT /orders/:orderId/interliners/:orderInterlinerId	Added the ability to update an orderInterlinerId record in the TruckMate API service
TM-164204	Update the OpenAPI specification to add 400 response code to GET which support query parameters	Added 400 response codes to the API document which support query parameters
TM-164279	TTC Fa�ade: GET Eligible Carriers	Added GET eligibleCarriers to TTC Facade
TM-164316	Update ART log retention (archive) workflow	Updated the log retention workflow to use an Archive after days option that moves log files from the log path to the archive path as configured in ARTAdmin.
TM-164444	GET masterData/eligibleCarriers	Added the eligibleCarriers endpoint to the masterData service. This endpoint will retrieve all eligible carriers. Further, you are able to specify a specific carrierId with the eligibleCarriers/:carrierId endpoint.
TM-164468	OpenAPI - add download link	Added a download link to the TruckMate and Master Data API services.
TM-164478	New TruckMate API endpoint /cloudEvents	CloudEvents APIs in <TTC - Facade> and <TM - Cloud Events> for Waterfall Tendering
TM-164532	Add TTC Configs	Added application configs that are necessary to set-up TTC integrations
TM-164548	Codes - add simple mode changed for advanced and beyond	Added options in Codes Maintenance > Interliner zone setup for allowing waterfall tendering for advance and beyond movements.
TM-164549	Codes - by service level, add column to beyond and advanced	Added options for allowing waterfall tendering on Interliner Zone Setup. Hid Allow Waterfall column in grid for now.
TM-164561	Imaging API /invoices exact match for freight bill number	The Imaging GET /invoices API endpoint now does an "exact match" for the 'BillNumber' query parameter.
TM-164668	Create Waterfall Tendering Interliner	Add INTLNR_TBD as a default vendor profiles for Waterfall Tendering. The INTLNR_TBD can be assigned to orders via CServ.exe and APIs. This new INTLNR_TBD profile cannot be deleted via Profile.exe.
TM-164673	See TM-164468 (add link here)
TM-164687	Assigning Carriers to a trip	Added the ability to assign Vendors of type "L", and "G", to a trip through the /trips/tripNumber/carriers endpoint on the TruckMate service
TM-164838	Remove vague description text from tag in REST API and masterData openAPI documentation	Removed vague descriptions: masterData drivers - Used to read 'Drivers Information' trailers - Used to read 'Trailers Information' whoami - Used to read 'Your Identity' Truckmate REST API appointments - single quote trips - Used to read 'Trips Information'
TM-164872	Update openAPI doc description for new currency rate endpoints in Orders API	Revise the description for the following 2 endpoints on TruckMate openapi doc: /orders/{orderId}/details/{orderDetailId}/ratesheetCurrencyRates /orders/{orderId}/aCharges/{aChargeId}/aChargeCurrencyRates
TM-164901	Security attribute is missing for masterData child endpoints in openAPI doc	Fixed the issue with security attributes are missing on the child endpoints on Master Data
TM-164930	Allow WFT Interliner assignment through ART.exe	Enabled the ability to initiate WFT through ART.exe when assigning an interliner
TM-164986	PUT tm/orders does not update the order if shipping instruction section includes a value already on original order	Fixed the issue with updating an order with existing shipping instruction
TM-165032	/orders API: missing TLORDER fields	Added the following TLORDER fields to the /orders responseBody TLORDER.DISTANCE TLORDER.DISTANCE_UNITS TLORDER.REQUESTED_EQUIPMEN TLORDER.TEMPERATURE TLORDER.VOLUME
TM-165090	OpenAPI - EAbstractError thrown for endpoint openapi.json	Implement the function GetSwaggerXTmRelease() in ALL doc controllers that inherited from DocController. Related to TM-164468
TM-165107	Update the Legal Statement for the API Services	Updated legal statement, added download links and corrected version for TruckMate, Master Data, Imaging, FB Import and Profile
TM-165181	API PUT orders command with notes causing DB2 "DECFLOAT" error	Add conversion logic to explicitly convert integer to string for notes.noteType (notes.id_key) in the PUT orderid request body.
TM-165261	TTC Facade /assetQuotes	A function to create a new quote based on an order that is referred by the 'tmsLoadId' (i.e., the orderInterlinerId of an order). In the new quote, new interliner(s) can be added.
TM-165379	Add Allow header to 405 response	Added Allow header that contains the correct methods in the Response Headers in all 405 responses
TM-165388	GET requests without the expand parameter	Removed inconsistent child resources behavior in GET requests, only return child resources when provided in the expand parameter
TM-165426	POST /orders - oData $select	Add support for the $select parameter when creating an order through the POST APIs.
TM-165432	Dev 1: Add pickupLocation dropLocation to orders.interliners resource response only	Added pickupLocation and dropLocation sections to the orders to display related zone and client information for the pickup and drop locations.
TM-165432	Dev 1: Add pickupLocation dropLocation to orders.interliners resource response only	Added pickupLocation and dropLocation child resources to the orders interliners endpoint.
TM-165453	Codes Maintenance add generic cross-referencing table	In codes.exe, a new tab "External Xref" was added and it can be accessed thru toolbar or main menu. Users can create new entries in table TM_SYSTEM_XREFS for mapping purpose in waterfall tendering and routing.
TM-165456	Dev 2: Define UoM fields at the Order Level resource response only	Orders API was updated to included base units for summary fields in the response.
TM-165457	Dev 4: orders add billToCustomer object resource response only	When the POST order call has the billTo specified with the caller/shipper/consignee/otherContact info, the response body of the newly created order will have the 'billToCustomer' child resource populated with the bill-to-client info. The 'billToCustomer' child resource is returned only when it is specified by the expand url parameters.
TM-165459	Dev 6: orders.xref add new xref fields resource response only	Orders API xref section was updated to include mapped values for service level and shipping instruction ID as defined in the External Reference section in Codes Maintenance.
TM-165475	Dev 3: orders.interliners add aCharges resource response only	Add the aCharges child resource under interliners. It will be returned in GET interliners API call if it is specified in the expand url parameter as 'expand=aCharges'; i.e., it won’t be returned in the GET API call by default.
TM-165647	TM API order request crash’s with CUSTOMDEF or TRACE filed value containing "SELECT" wording	Resolved an issue with the REST API Order request crashing when CUSTOMDEF or TRACE were being filled with the text "SELECT".
TM-165692	Add RATE fields when creating/updating Manually Rated Orders	Allow POST or PUT on rates related fields only when manuallRate field is set to True. The fields are: ratePer, rate, rateUnits, asRate and asBreak.
TM-165698	Add extra disclaimer regarding documentation on openAPI document for Profile, FB Import and Imaging	Added extra disclaimer regarding latest released version of TruckMate on Open API Document for MasterData, Imaging, FB Import and Profile.
TM-165711	Unable to add records to advance/crossdock/beyond grids in Interliner Zone Setup screen	Fixed an issue where an error was being encountered when attempting to add records to the advance, crossdock or beyond grids in the Interliner Zone Setup screen.
TM-165732	Add to masterData GET /commodities endpoint to return more CMODTY data	Retrieve more info from the GET commodities APIs
TM-165847	Trip API incorrectly instantiates LTLDispFunc	Fixed an issue where message prompts were not being suppressed for LTL related workflows in the Trips API
TM-166029	500 error raised from barcodes EArtControllerException	Fixed an issue where 500 server error returns sending POST details barcode request.
TM-166065	Back Merge Changes for Allowing Copying Existing Quotes or Orders	Copy existing Quotes/Orders to a new quote/order with correct handling on the unit fields (e.g., pallets, pieces & etc), isManual + Auto-Assign + Accessorial Charges fields, manuallyRated & Rate releated fields, and areaUnits & timeUnits fields.

TM-139500

allow DELETE /orders/:orderId/details/:orderDetailId

Add a new function to delete an order-details by detail id and order id

TM-141881

Add contacts unit field to request

Added unit field to request and response bodies of caller, shipper, consignee, careOf, pickupAt and otherContact [#TM-151987]

TM-151987

New masterData ratingMethodRules endpoint added to the /masterData/clients/{clientId} query methods

Two new fields, minFBCube and maxFBCube, have been added to the POST PUT and GET methods for:

/masterData/clients/\{clientId/tariffClasses}
/masterData/clients/\{clientId/tariffClasses}/{tariffClassId}

These fields hold the values for the lower and higher ranges of the cube condition of the tariff class rule.

TM-159561

Move commodities endpoint from /tm to new service

Moved commodities endpoint from ART TruckMate service to MasterData service

TM-160915

Implement remote log server on ART

Added support for remote ART logging to an external server address.

TM-163043

Adding SQL meta data to logs - ARTController

Added the following fields to the ART log files:

SQL string
parameter
result
execution time

TM-163044

Adding SQL meta data to logs - Orders - GET and DELETE endpoints

Added the following fields to the ART log files that are related to Orders GET and DELETE endpoints:

SQL string
parameter
result
execution time

TM-163045

Adding SQL meta data to logs - Trips - GET and DELETE endpoints

Added the following fields to the ART log files that are related to Trips GET and DELETE endpoints:

SQL string
parameter
result
execution time

TM-163129

New companyId query parameter

A new companyId query parameter was added to the Imaging POST /carrierassignments/acceptcontract API endpoint. This allows you to get the value of an app configuration option based on the company ID.

TM-164194

PUT /orders/:orderId/interliners/:orderInterlinerId

Added the ability to update an orderInterlinerId record in the TruckMate API service

TM-164204

Update the OpenAPI specification to add 400 response code to GET which support query parameters

Added 400 response codes to the API document which support query parameters

TM-164279

TTC Fa�ade: GET Eligible Carriers

Added GET eligibleCarriers to TTC Facade

TM-164316

Update ART log retention (archive) workflow

Updated the log retention workflow to use an Archive after days option that moves log files from the log path to the archive path as configured in ARTAdmin.

TM-164444

GET masterData/eligibleCarriers

Added the eligibleCarriers endpoint to the masterData service. This endpoint will retrieve all eligible carriers. Further, you are able to specify a specific carrierId with the eligibleCarriers/:carrierId endpoint.

TM-164468

OpenAPI - add download link

Added a download link to the TruckMate and Master Data API services.

TM-164478

New TruckMate API endpoint /cloudEvents

CloudEvents APIs in <TTC - Facade> and <TM - Cloud Events> for Waterfall Tendering

TM-164532

Add TTC Configs

Added application configs that are necessary to set-up TTC integrations

TM-164548

Codes - add simple mode changed for advanced and beyond

Added options in Codes Maintenance > Interliner zone setup for allowing waterfall tendering for advance and beyond movements.

TM-164549

Codes - by service level, add column to beyond and advanced

Added options for allowing waterfall tendering on Interliner Zone Setup. Hid Allow Waterfall column in grid for now.

TM-164561

Imaging API /invoices exact match for freight bill number

The Imaging GET /invoices API endpoint now does an "exact match" for the 'BillNumber' query parameter.

TM-164668

Create Waterfall Tendering Interliner

Add INTLNR_TBD as a default vendor profiles for Waterfall Tendering. The INTLNR_TBD can be assigned to orders via CServ.exe and APIs. This new INTLNR_TBD profile cannot be deleted via Profile.exe.

TM-164673

See TM-164468 (add link here)

TM-164687

Assigning Carriers to a trip

Added the ability to assign Vendors of type "L", and "G", to a trip through the /trips/tripNumber/carriers endpoint on the TruckMate service

TM-164838

Remove vague description text from tag in REST API and masterData openAPI documentation

Removed vague descriptions:

masterData
drivers - Used to read 'Drivers Information'
trailers - Used to read 'Trailers Information'
whoami - Used to read 'Your Identity'
Truckmate REST API
appointments - single quote
trips - Used to read 'Trips Information'

TM-164872

Update openAPI doc description for new currency rate endpoints in Orders API

Revise the description for the following 2 endpoints on TruckMate openapi doc:

/orders/{orderId}/details/{orderDetailId}/ratesheetCurrencyRates
/orders/{orderId}/aCharges/{aChargeId}/aChargeCurrencyRates

TM-164901

Security attribute is missing for masterData child endpoints in openAPI doc

Fixed the issue with security attributes are missing on the child endpoints on Master Data

TM-164930

Allow WFT Interliner assignment through ART.exe

Enabled the ability to initiate WFT through ART.exe when assigning an interliner

TM-164986

PUT tm/orders does not update the order if shipping instruction section includes a value already on original order

Fixed the issue with updating an order with existing shipping instruction

TM-165032

/orders API: missing TLORDER fields

Added the following TLORDER fields to the /orders responseBody

TLORDER.DISTANCE
TLORDER.DISTANCE_UNITS
TLORDER.REQUESTED_EQUIPMEN
TLORDER.TEMPERATURE
TLORDER.VOLUME

TM-165090

OpenAPI - EAbstractError thrown for endpoint openapi.json

Implement the function GetSwaggerXTmRelease() in ALL doc controllers that inherited from DocController. Related to TM-164468

TM-165107

Update the Legal Statement for the API Services

Updated legal statement, added download links and corrected version for TruckMate, Master Data, Imaging, FB Import and Profile

TM-165181

API PUT orders command with notes causing DB2 "DECFLOAT" error

Add conversion logic to explicitly convert integer to string for notes.noteType (notes.id_key) in the PUT orderid request body.

TM-165261

TTC Facade /assetQuotes

A function to create a new quote based on an order that is referred by the 'tmsLoadId' (i.e., the orderInterlinerId of an order). In the new quote, new interliner(s) can be added.

TM-165379

Add Allow header to 405 response

Added Allow header that contains the correct methods in the Response Headers in all 405 responses

TM-165388

GET requests without the expand parameter

Removed inconsistent child resources behavior in GET requests, only return child resources when provided in the expand parameter

TM-165426

POST /orders - oData $select

Add support for the $select parameter when creating an order through the POST APIs.

TM-165432

Dev 1: Add pickupLocation dropLocation to orders.interliners resource response only

Added pickupLocation and dropLocation sections to the orders to display related zone and client information for the pickup and drop locations.

TM-165432

Dev 1: Add pickupLocation dropLocation to orders.interliners resource response only

Added pickupLocation and dropLocation child resources to the orders interliners endpoint.

TM-165453

Codes Maintenance add generic cross-referencing table

In codes.exe, a new tab "External Xref" was added and it can be accessed thru toolbar or main menu. Users can create new entries in table TM_SYSTEM_XREFS for mapping purpose in waterfall tendering and routing.

TM-165456

Dev 2: Define UoM fields at the Order Level resource response only

Orders API was updated to included base units for summary fields in the response.

TM-165457

Dev 4: orders add billToCustomer object resource response only

When the POST order call has the billTo specified with the caller/shipper/consignee/otherContact info, the response body of the newly created order will have the 'billToCustomer' child resource populated with the bill-to-client info. The 'billToCustomer' child resource is returned only when it is specified by the expand url parameters.

TM-165459

Dev 6: orders.xref add new xref fields resource response only

Orders API xref section was updated to include mapped values for service level and shipping instruction ID as defined in the External Reference section in Codes Maintenance.

TM-165475

Dev 3: orders.interliners add aCharges resource response only

Add the aCharges child resource under interliners. It will be returned in GET interliners API call if it is specified in the expand url parameter as 'expand=aCharges'; i.e., it won’t be returned in the GET API call by default.

TM-165647

TM API order request crash’s with CUSTOMDEF or TRACE filed value containing "SELECT" wording

Resolved an issue with the REST API Order request crashing when CUSTOMDEF or TRACE were being filled with the text "SELECT".

TM-165692

Add RATE fields when creating/updating Manually Rated Orders

Allow POST or PUT on rates related fields only when manuallRate field is set to True. The fields are: ratePer, rate, rateUnits, asRate and asBreak.

TM-165698

Add extra disclaimer regarding documentation on openAPI document for Profile, FB Import and Imaging

Added extra disclaimer regarding latest released version of TruckMate on Open API Document for MasterData, Imaging, FB Import and Profile.

TM-165711

Unable to add records to advance/crossdock/beyond grids in Interliner Zone Setup screen

Fixed an issue where an error was being encountered when attempting to add records to the advance, crossdock or beyond grids in the Interliner Zone Setup screen.

TM-165732

Add to masterData GET /commodities endpoint to return more CMODTY data

Retrieve more info from the GET commodities APIs

TM-165847

Trip API incorrectly instantiates LTLDispFunc

Fixed an issue where message prompts were not being suppressed for LTL related workflows in the Trips API

TM-166029

500 error raised from barcodes EArtControllerException

Fixed an issue where 500 server error returns sending POST details barcode request.

TM-166065

Back Merge Changes for Allowing Copying Existing Quotes or Orders

Copy existing Quotes/Orders to a new quote/order with correct handling on the unit fields (e.g., pallets, pieces & etc), isManual + Auto-Assign + Accessorial Charges fields, manuallyRated & Rate releated fields, and areaUnits & timeUnits fields.