TruckMate 2023.2 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.

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	Endpoint	Description
TM-150000	Orders API select fields based on API key (web user)	GET /orders	Updated GET /orders when using Web User authentication to only display order fields based on the Web Admin Trace Results grid setup for the related web user.
TM-164860	Update tag descriptions for all sections in openAPI document for TM REST API and masterData	GET /tm/openapi.json GET /masterData/openapi.json	Revise the OpenAPI doc for the following items: Update OpenAPI tags to not be in camelCase format (e.g., cloudEvent = Cloud Events) Add description to all tags This change covers all TruckMate APIs and MasterData APIs.
TM-166894	Prevent mass barcode updates on orders that have been picked up	PUT /orders/{{orderId}}/ details/{{orderDetailId}}	When the 'pickupDone' of an order is 'PICKD' (i.e., the order is picked up), updating the barcode without barcodeId specified in the PUT request will not be allowed. An 'invalidBusinessLogic' error will be returned instead. However, if an order is *not* picked up yet, then updating the barcode without barcodeId specified in the PUT request will replace the existing barcodes with the barcodes in the PUT request.
TM-167777	PUT /orders/:orderId/ details/:orderDetailId with barcodeId	PUT /orders// {orderId}}/details/ {{orderDetailId}}	The orders barcode can be updated by using barcodeId in the PUT request. There are 3 basic scenarios: If all the barcodes in the request have barcodeId specified, the specified barcodes will be updated. If all the barcodes in the request do not have barcodeId specified, the existing barcodes will be replaced by what’s listed in the request. If some barcodes have barcodeId specified and some don’t, then: The original barcode that is referred by the barcodeId in the PUT request will be updated. The original barcode that is not referred by the barcodeId in the PUT request will remain intact. The barcode that is has no barcodeId specified will be inserted as new barcode. Additional notes for scenarios 2 and 3: The items field should not be included. If dimensional related fields (e.g., weight, weightUnit) are included, a dimensional change history record will be created to store the original value. The dimensional change history can be viewed in Customer Service. On the Details tab, double-click the Items column.
TM-168835	Remove hard +7 days when creating a quote via API	POST /orders?type=Q	To allow for better flexibility, the Orders API removed a hard coded requirement that adds 7 days to the pickup date when creating a quote. The quote will be created with the pickup and delivery dates specified in the request body.
TM-168898	REST API not able to handle AND or OR in strings	{{DOMAIN}}/orders?$filter=user1 eq 'fruit or roots' AND user10 eq 'A nor B'	Using AND and OR in the filter string (such as 'A or B', 'fruit and roots') will not be confused with the logical operators as long as they are placed inside single quotation marks. Also, using words that contain "and" or "or" (such as band, nor) in the filter string will retrieve the correct orders.
TM-169031	Review and optimize POST orders performance	POST /orders PUT /orders/orderId	Optimize creating orders (POST /orders) so that validation functions are not invoked when the resource fields are empty string or not provided.
TM-169397	PUT /orders/:orderId/ details/:orderDetailId with barcodeId	PUT /orders/{{orderId}}	Single or multiple barcodes in multiple details blocks can be updated by using barcodeId in the orders PUT request. The combinations of the following scenarios are covered: Single and multiple barcodes in 1 details block Single and multiple barcodes in multiple details blocks Barcodes update with and without barcodeId specified Barcodes update with and without items field If barcodeId is not provided, items field is optional. If barcodeId is provided, the items should be skipped in the corresponding details block. Barcodes update with and without dimensional fields (e.g., weight) If barcodeId is provided, then dimensional change history records will be created. The records can be viewed in Customer Service. On the Details tab, double-click the Items column.
TM-169476	Barcode ID skipped in Orders Update (PUT) endpoints	PUT /orders/{{orderId}}/ details/{{orderDetailId}}	Assume there is only 1 user at the moment, when the user deletes and replaces the barcode of a newly created order via a PUT action, the next barcode id is now incremented by 1. For example, if the original barcode id is 11110, the next barcode id should be 11111.

Case Issue

Case Name

Endpoint

Description

TM-150000

Orders API select fields based on API key (web user)

GET /orders

Updated GET /orders when using Web User authentication to only display order fields based on the Web Admin Trace Results grid setup for the related web user.

TM-164860

Update tag descriptions for all sections in openAPI document for TM REST API and masterData

GET /tm/openapi.json

GET /masterData/openapi.json

Revise the OpenAPI doc for the following items:

Update OpenAPI tags to not be in camelCase format (e.g., cloudEvent = Cloud Events)
Add description to all tags

This change covers all TruckMate APIs and MasterData APIs.

TM-166894

Prevent mass barcode updates on orders that have been picked up

PUT /orders/{{orderId}}/
details/{{orderDetailId}}

When the 'pickupDone' of an order is 'PICKD' (i.e., the order is picked up), updating the barcode without barcodeId specified in the PUT request will not be allowed. An 'invalidBusinessLogic' error will be returned instead.

However, if an order is not picked up yet, then updating the barcode without barcodeId specified in the PUT request will replace the existing barcodes with the barcodes in the PUT request.

TM-167777

PUT /orders/:orderId/
details/:orderDetailId with barcodeId

PUT /orders//
{orderId}}/details/
{{orderDetailId}}

The orders barcode can be updated by using barcodeId in the PUT request. There are 3 basic scenarios:

If all the barcodes in the request have barcodeId specified, the specified barcodes will be updated.
If all the barcodes in the request do not have barcodeId specified, the existing barcodes will be replaced by what’s listed in the request.
If some barcodes have barcodeId specified and some don’t, then:
- The original barcode that is referred by the barcodeId in the PUT request will be updated.
- The original barcode that is not referred by the barcodeId in the PUT request will remain intact.
- The barcode that is has no barcodeId specified will be inserted as new barcode.

Additional notes for scenarios 2 and 3:

The items field should not be included.
If dimensional related fields (e.g., weight, weightUnit) are included, a dimensional change history record will be created to store the original value. The dimensional change history can be viewed in Customer Service. On the Details tab, double-click the Items column.

TM-168835

Remove hard +7 days when creating a quote via API

POST /orders?type=Q

To allow for better flexibility, the Orders API removed a hard coded requirement that adds 7 days to the pickup date when creating a quote. The quote will be created with the pickup and delivery dates specified in the request body.

TM-168898

REST API not able to handle AND or OR in strings

{{DOMAIN}}/orders?$filter=user1 eq 'fruit or roots' AND user10 eq 'A nor B'

Using AND and OR in the filter string (such as 'A or B', 'fruit and roots') will not be confused with the logical operators as long as they are placed inside single quotation marks. Also, using words that contain "and" or "or" (such as band, nor) in the filter string will retrieve the correct orders.

TM-169031

Review and optimize POST orders performance

POST /orders

PUT /orders/orderId

Optimize creating orders (POST /orders) so that validation functions are not invoked when the resource fields are empty string or not provided.

TM-169397

PUT /orders/:orderId/
details/:orderDetailId
with barcodeId

PUT /orders/{{orderId}}

Single or multiple barcodes in multiple details blocks can be updated by using barcodeId in the orders PUT request.

The combinations of the following scenarios are covered:

Single and multiple barcodes in 1 details block
Single and multiple barcodes in multiple details blocks
Barcodes update with and without barcodeId specified
Barcodes update with and without items field
- If barcodeId is not provided, items field is optional.
- If barcodeId is provided, the items should be skipped in the corresponding details block.
Barcodes update with and without dimensional fields (e.g., weight)
If barcodeId is provided, then dimensional change history records will be created. The records can be viewed in Customer Service. On the Details tab, double-click the Items column.

TM-169476

Barcode ID skipped in Orders Update (PUT) endpoints

PUT /orders/{{orderId}}/
details/{{orderDetailId}}

Assume there is only 1 user at the moment, when the user deletes and replaces the barcode of a newly created order via a PUT action, the next barcode id is now incremented by 1. For example, if the original barcode id is 11110, the next barcode id should be 11111.

Trips API

Case Issue	Case Name	Endpoint	Description
TM-169785	Update tm//trips to return cancelled trips (all trips)	GET /trips GET /trips/:tripNumber	Update the trips API to return all trips including cancelled trips which had previously returned a 404. The $filter parameter can be used to narrow down results returned.

Case Issue

Case Name

Endpoint

Description

TM-169785

Update tm//trips to return cancelled trips (all trips)

GET /trips

GET /trips/:tripNumber

Update the trips API to return all trips including cancelled trips which had previously returned a 404. The $filter parameter can be used to narrow down results returned.

Reports API

Case Issue	Case Name	Endpoint	Description
TM-158373	Update reports summary and descriptions	GET /openapi.json	Update the endpoint description for the following two endpoints in TruckMate REST API OpenAPI documentation: GET /reports GET /reports/{reportId}

Case Issue

Case Name

Endpoint

Description

TM-158373

Update reports summary and descriptions

GET /openapi.json

Update the endpoint description for the following two endpoints in TruckMate REST API OpenAPI documentation:

GET /reports
GET /reports/{reportId}

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.

These tables list issues in alphabetical order by case number.

Clients

Case Issue	Case Name	Endpoint(s)	Description
TM-166215	Master Data - POST /clients - add customDefs	POST masterData/clients	Enable the POST/clients endpoint to add customDefs child resource. Client custom-defined fields can be viewed in Customer & Vendor Profiles, on the Customer > Custom Defined Fields tab. Custom-defined fields are configured on the Custom Defined Fields tab in Codes Maintenance.
TM-166216	Master Data - Post /clients/:clientId/customDefs	POST masterData/clients/:clientId/customDefs	Enable the POST/clients/:clientId/customDefs endpoint to add customDefs child resource. Client custom-defined fields can be viewed in Customer & Vendor Profiles, on the Customer > Custom Defined Fields tab. Custom-defined fields are configured on the Custom Defined Fields tab in Codes Maintenance.
TM-166221	Master Data - POST /clients - add contacts	POST masterData/clients	Enable the POST/clients endpoint to create a new client with his/her contacts included in the request.
TM-166222	Master Data - POST /clients/:clientId/contacts	POST masterData/clients/:clientId/contacts	Enable the POST/clients/:clientId/contacts endpoint to add contacts to the specified client profile.
TM-166232	Master Data - POST /vendors - add customDefs	POST masterData/vendors	Enable the POST/vendors endpoint to add customDefs child resource. Client custom-defined fields can be viewed in Customer & Vendor Profiles, on the Customer > Custom Defined Fields tab. Custom-defined fields are configured on the Custom Defined Fields tab in Codes Maintenance.
TM-166233	Master Data - POST /vendors/:vendorId/customDefs	POST masterData/vendors/:vendorId/customDefs	Enable the POST/vendors/:vendorId/customDefs endpoint to add customDefs child resource. Client custom-defined fields can be viewed in Customer & Vendor Profiles, on the Customer > Custom Defined Fields tab. Custom-defined fields are configured on the Custom Defined Fields tab in Codes Maintenance.

Case Issue

Case Name

Endpoint(s)

Description

TM-166215

Master Data - POST /clients - add customDefs

POST masterData/clients

Enable the POST/clients endpoint to add customDefs child resource.

Client custom-defined fields can be viewed in Customer & Vendor Profiles, on the Customer > Custom Defined Fields tab.

Custom-defined fields are configured on the Custom Defined Fields tab in Codes Maintenance.

TM-166216

Master Data - Post /clients/:clientId/customDefs

POST masterData/clients/:clientId/customDefs

Enable the POST/clients/:clientId/customDefs endpoint to add customDefs child resource.

Client custom-defined fields can be viewed in Customer & Vendor Profiles, on the Customer > Custom Defined Fields tab.

Custom-defined fields are configured on the Custom Defined Fields tab in Codes Maintenance.

TM-166221

Master Data - POST /clients - add contacts

POST masterData/clients

Enable the POST/clients endpoint to create a new client with his/her contacts included in the request.

TM-166222

Master Data - POST /clients/:clientId/contacts

POST masterData/clients/:clientId/contacts

Enable the POST/clients/:clientId/contacts endpoint to add contacts to the specified client profile.

TM-166232

Master Data - POST /vendors - add customDefs

POST masterData/vendors

Enable the POST/vendors endpoint to add customDefs child resource.

Client custom-defined fields can be viewed in Customer & Vendor Profiles, on the Customer > Custom Defined Fields tab.

Custom-defined fields are configured on the Custom Defined Fields tab in Codes Maintenance.

TM-166233

Master Data - POST /vendors/:vendorId/customDefs

POST masterData/vendors/:vendorId/customDefs

Enable the POST/vendors/:vendorId/customDefs endpoint to add customDefs child resource.

Client custom-defined fields can be viewed in Customer & Vendor Profiles, on the Customer > Custom Defined Fields tab.

Custom-defined fields are configured on the Custom Defined Fields tab in Codes Maintenance.

Vendors

Case Issue	Case Name	Endpoint	Description
TM-159925	Webadmin.exe - Vendor and client profiles are deleted in error when deleting a web access code	n/a	Deleting the access code in WebAdmin.exe should not delete the client and vendor profiles, which use that deleted access code as their 'Default Access Code', in Profiles.exe. After the access code is successfully deleted from WebAdmin.exe, instead of deleting the client/vendor profile, only the profile 'Default Access Code' is reset back to blank.
TM-166227	Header	GET masterData/vendors GET masterData/vendors/:vendorId	The Vendors API has been enhanced to now retrieve the following additional fields: Accounts Payable tab: applyTax1 applyTax2 Address tab: faxNotify email terminalZone Notes tab allowPopupNotes comments In addition, external systems can now retrieve vendor user-defined fields. These can be viewed in Customer & Vendor Profiles on the Vendor > User Defined Fields tab.
TM-166229	Child "contacts"	GET masterData/vendors GET masterData/vendors/:vendorId GET masterData/vendors/:vendorId/contacts GET masterData/vendors/:vendorId/contacts/:contactId	The Vendors API has been enhanced to now retrieve vendor contact records, allowing external systems to access contact information, such as names and addresses, phone numbers and email addresses. Vendor contacts can be viewed in the Customer & Vendor Profiles application > Vendor > Contacts tab.
TM-169846		POST masterData/vendors	Expose two fields called 'ein' and 'dot' to RefVendorPostRequest, so now the user can include 'Dot Number' and 'Federal ID' in creating a new vendor. The 'dot' field is displayed in Profiles.exe ⇒ Insurance Monitoring Services ⇒ Dot Number The 'ein' field is displayed in Profiles.exe ⇒ Types and Payroll ⇒ Federal ID

Case Issue

Case Name

Endpoint

Description

TM-159925

Webadmin.exe - Vendor and client profiles are deleted in error when deleting a web access code

n/a

Deleting the access code in WebAdmin.exe should not delete the client and vendor profiles, which use that deleted access code as their 'Default Access Code', in Profiles.exe.

After the access code is successfully deleted from WebAdmin.exe, instead of deleting the client/vendor profile, only the profile 'Default Access Code' is reset back to blank.

TM-166227

Header

GET masterData/vendors

GET masterData/vendors/:vendorId

The Vendors API has been enhanced to now retrieve the following additional fields:

Accounts Payable tab:
- applyTax1
- applyTax2
Address tab:
- faxNotify
- email
- terminalZone
Notes tab
- allowPopupNotes
- comments

In addition, external systems can now retrieve vendor user-defined fields. These can be viewed in Customer & Vendor Profiles on the Vendor > User Defined Fields tab.

TM-166229

Child "contacts"

GET masterData/vendors

GET masterData/vendors/:vendorId

GET masterData/vendors/:vendorId/contacts

GET masterData/vendors/:vendorId/contacts/:contactId

The Vendors API has been enhanced to now retrieve vendor contact records, allowing external systems to access contact information, such as names and addresses, phone numbers and email addresses.

Vendor contacts can be viewed in the Customer & Vendor Profiles application > Vendor > Contacts tab.

TM-169846

POST masterData/vendors

Expose two fields called 'ein' and 'dot' to RefVendorPostRequest, so now the user can include 'Dot Number' and 'Federal ID' in creating a new vendor.

The 'dot' field is displayed in Profiles.exe ⇒ Insurance Monitoring Services ⇒ Dot Number
The 'ein' field is displayed in Profiles.exe ⇒ Types and Payroll ⇒ Federal ID

TM4Web

Case Issue	Case Name	Description
TM-141773	Clear all related tables when deleting an Access Group	When deleting a client or vendor web access code, a warning prompt has been added when there is at least one associated web user indicating that the web users will be set to inactive and associated web access code data will be deleted. Also, the process of deleting a web access code has been improved to remove any associated data in other tables relating to the web access code being deleted.
TM-153717	Export to Excel shows HTML code for TM4Web Trace results	Fixed an issue where HTML code was being incorrectly shown when trace results were being exported to Excel for the OSD and POD TX type fields.
TM-167494	TM4Web Order Entry Details popup warnings overlap	An issue where required field pop up warnings were overlapping in the Order Entry details grid was fixed.
TM-168836	Remove hardcoded +7 days when creating a rate quote via web	To allow for better flexibility during the creation of a rate quote in TM4Web, a hard coded requirement that adds 7 days to the pickup date when creating a quote was removed. The quote will be created with the pickup and delivery dates as specified during the rate quote creation. A default of 7 days will be applied for pickup and delivery dates that are not defined during the rate quote creation process.
TM-168900	TM4Web - Column Visible Despite Being Set as Non-Visible	An issue was fixed where the display of pickup and delivery end dates on the Order Entry result page was not following the related configuration setting in the WebAdmin application.
TM-169370	Update minimum version of Apache to 2.4.57 due to security issues	Apache version included with the TM4Web installation and TruckMate API was upgraded to 2.4.57 in order to provide most recent security benefits. It also addresses potential vulnerabilities that exist in previous versions of Apache.
TM-169547	TM4Web/Webadmin: Customer Profiles is looking at the Vendor Access Group when checking if the Client is part of an Access Group	Fixed an issue where Customer and Vendor Profiles was not allowing the creation of a customer profile if a web enabled vendor profile of the same name already exists.

Case Issue

Case Name

Description

TM-141773

Clear all related tables when deleting an Access Group

When deleting a client or vendor web access code, a warning prompt has been added when there is at least one associated web user indicating that the web users will be set to inactive and associated web access code data will be deleted. Also, the process of deleting a web access code has been improved to remove any associated data in other tables relating to the web access code being deleted.

TM-153717

Export to Excel shows HTML code for TM4Web Trace results

Fixed an issue where HTML code was being incorrectly shown when trace results were being exported to Excel for the OSD and POD TX type fields.

TM-167494

TM4Web Order Entry Details popup warnings overlap

An issue where required field pop up warnings were overlapping in the Order Entry details grid was fixed.

TM-168836

Remove hardcoded +7 days when creating a rate quote via web

To allow for better flexibility during the creation of a rate quote in TM4Web, a hard coded requirement that adds 7 days to the pickup date when creating a quote was removed. The quote will be created with the pickup and delivery dates as specified during the rate quote creation. A default of 7 days will be applied for pickup and delivery dates that are not defined during the rate quote creation process.

TM-168900

TM4Web - Column Visible Despite Being Set as Non-Visible

An issue was fixed where the display of pickup and delivery end dates on the Order Entry result page was not following the related configuration setting in the WebAdmin application.

TM-169370

Update minimum version of Apache to 2.4.57 due to security issues

Apache version included with the TM4Web installation and TruckMate API was upgraded to 2.4.57 in order to provide most recent security benefits. It also addresses potential vulnerabilities that exist in previous versions of Apache.

TM-169547

TM4Web/Webadmin: Customer Profiles is looking at the Vendor Access Group when checking if the Client is part of an Access Group

Fixed an issue where Customer and Vendor Profiles was not allowing the creation of a customer profile if a web enabled vendor profile of the same name already exists.