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

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:

These tables list issues in alphabetical order by case number.

Orders API

Case Issue Case Name Endpoint Description

TM-166178

Issues with parameters

GET /trips/:tripNumber/orders

Added missing offset and limit parameters which are used to determine the offset and how many records can be returned when using the Trips API to return orders on a trip.

TM-170119

Duplicate PO’s trace types can be created in Customer Service but Check PO is true if bills are created through the API

POST /orders

PUT /orders/:orderId

POST /orders/:orderId/traceNumbers

PUT /orders/:orderId/traceNumbers?traceType=P&traceNumber=:traceNumber

PUT /orders/:orderId/traceNumbers/:traceNumber

When the CSERV.EXE - Check PO Application Configurator option is set to True, the POST and PUT orders endpoints are blocked if the traceNumbers.traceNumber in the request is already used by another posted order. A 400 error with the description "Duplicate PO not allowed based on App Config option" is returned instead.

TM-170706

Art add filter for Get /tm/orders/statusHistory to avoid POSITION

GET /orders

GET /orders/:orderId

GET /orders/:orderId/statusHistory

A new query parameter, excludePositions, has been added to the Orders API that controls whether position status updates are included when the statusHistory section is included in the response.

TM-170732

Review TMS_ORDERS_SEARCH_VW

GET /orders

GET /orders/:orderId

An improvement was made to the related stored procedure that is called when retrieving orders by the Orders API. The change prevents a full table scan from being performed on the related orders table.

Trips API

Case Issue Case Name Endpoint Description

TM-169757

Status change date threshold config not being respected in RESTful API

PUT /trips/:tripNumber/status

PUT /trips/:tripNumber/orders/:orderId/status

See below

TM-169980

UPDATE TRIP SET COMMENTS_RTF=BLOB(COMMENTS) - excessive runtimes

POST /trip

See below

TM-171048

GET /trips/:tripNumber/orders add $select

GET /trips/:tripNumber/orders

GET /trips/:tripNumbers/orders/:orderId

The $select query parameter has been added to the trip orders endpoints to allow for the ability to reduce the number of fields returned in the response and allow for more efficiency.

TM-169757

The status update endpoint now takes into account the date tolerances defined for the Application Configurator DISPATCH.EXE - TRIP_STATUS_CHANGE_DATE option into account:

  • Earlier Date Tolerance:

    • -1: Any timestamp earlier than the current time assigned to the 'time' field in the PUT request will be accepted.

    • 0: The timestamp set in the time field must match the current time when the PUT request is saved.

    • Any positive integer (day): the timestamp set in the time field must be within the range of current time-minus-integer and current time.

  • Later Date Tolerance:

    • -1: Any timestamp later than the current time assigned to the time field in the PUT request will be accepted.

    • 0: The timestamp set in the time field must match the current time when the PUT request is saved.

    • Any positive integer (day): the timestamp set in the time field must be within the range of current time and current time-plus-integer.

TM-169980

The SQL efficiency that is used to update the Trip Note Summary has been improved.

It now quickly identifies the trip number (that is newly created by the endpoint) during the process of saving the trip note. As a result, the overall execution time is reduced, especially when the number of trips in DB is large.

The POST trip API remains the same as the change is internal.

To view a trip note in Multi Mode Dispatch, right-click on the trip in the Trips grid and select Trip Notes Summary from the shortcut menu.

A trip note is created when you try to assign an order to a completed or cancelled trip.

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.

Accessorial Charges

Case Issue Case Name Endpoint(s) Description

TM-168305

PUT is not updating related record

PUT /aChargeCodes/:aChargeCodeId/
aChargeDetails/:aChargeDetailId/
extraStopRates/:extraStopId

Setting rangeFrom, rangeTo and rate in PUT request will update the specified accessorial charge 'extra stop' record specified by the 'extraStopId'.

TM-168960

OpenAPI should be marked as required

POST /aChargeCodes/:aChargeCodeId/
aChargeDetails/:aChargeDetailId/multiRateSheets

PUT /aChargeCodes/:aChargeCodeId/
aChargeDetails/:aChargeDetailId/multiRateSheets
/:multiRateSheetId

Updated the rateSheetId field for accessorial charge multi rate sheets to be marked as required in the openAPI document. This improves accuracy of the documentation for this endpoints and ensures proper error message is returned if the rateSheetId field is not included when using these endpoints.

Clients

Case Issue Case Name Endpoint(s) Description

TM-168500

densityMinQuantity and densityMaxQuantity should not be negative values

POST /clients

PUT /clients/:clientId

POST /clients/:clientId/ratingMethodRules

PUT /clients/:clientId/ratingMethodRules/:ruleId

POST /clients/:clientId/cubePolicies

PUT /clients/:clientId/cubePolicies/:cubePolicyId

See below

TM-169405

masterData API allows client profiles to be created with missing mandatory fields

POST /clients

PUT /clients/:clientId

MasterData API blocks POST and PUT endpoints in the following conditions:

  • The currency field is provided in the request but with an empty string

  • The provided currency is not active (maintained in Codes.exe - Countries).

  • The provided currency is not a valid (i.e., not listed in Codes.exe - Countries)

The following conditions are acceptable:

The currency field is not provided in the request as it is not a mandatory field. If it is not provided, the currency of the company profile will be used as default.

TM-170992

$filter error when POST cubePolicies?onlyPostedResults=True

POST /clients/:clientId/cubePolicies

Fixed an error that was being encountered when using the onlyPostedResults parameter when creating cube policy records for clients.

TM-168500

Add the optional minimum property to the following number fields used in clients POST and PUT requests:

  • client ratingMethodRules

    • densityMinQuantity, densityMaxQuantity

  • client cubePolicies

    • maximumHeight, minimumHeight

    • maximumLength, minimumLength

    • minimumWeight, maximumWeight

    • minimumWidth, maximumWidth

    • overrideHeight, overrideLength, overrideWidth

If the value is lower than the minimum, then the following error will be returned.

  • code: belowMinValue,

  • description: <fieldname> cannot be less than the minimum value of <minimum>

Commodities

Case Issue Case Name Endpoint Description

TM-165334

Add oData filter to commodities

GET /commodities

Added oData filtering ($filter) parameter to the GET commodities endpoint that allows for filtering of result data

TM-168087

Add support /POST to commodities

POST /commodities

Add a new Commodities API to create new commodity code

TM-168089

Allow a /PUT for commodities

PUT /commodities/:commodityId

Add a new Commodities API to update an existing commodity code by commodity ID (commodityCode)

TM-168090

Add a /DEL for commodities

DELETE /commodities/:commodityId

Add a new Commodities API to delete a commodity by commodity ID (commodityCode)

TM-168669

Update GET /commodities to add more fields needed to support the POST request

GET /commodities

GET /commodities/:commodityId

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

  • palletOwner

  • conversionType

  • conversionPieceUnits

  • conversionWeight

  • conversionWeightUnits

  • conversionCube

  • conversionCubeUnits

  • conversionPallet

  • conversionPalletUnits

TM-170309

Commodities API conversionType enum values

GET /commodities

GET /commodities/:commodityId

POST /commodities

PUT /commodities/:commodityId

Update the conversionType enum values to pieces and pallets to follow the API Enumeration Values standard

TM-170404

Commodity STCC pattern

POST /commodities

PUT /commodities/:commodityId

Enhance the Commodities POST and PUT endpoints with string formats that are accepted in the STCC field on the Codes Maintenance Commodity Code Definition tab:

  • Empty string

  • A string between 1-7 digits in length

Vendors

Case Issue Case Name Endpoint Description

TM-165007

masterData /vendors - vendorType palletCompany

GET /vendors

POST /vendors

GET /vendors/:vendorId

PUT /vendors/:vendorId

When the vendorType is set to 'Pallet Company' for a vendor profile in Profiles.exe, the vendorType field in the vendor responses will display 'palletCompany'.

TM-168952

OpenAPI Vendors rateSheetLinks rateSheetID should be marked as required

POST /vendors

POST /vendors/:vendorId/rateSheetLinks

The rateSheetId of the RefVendorsRatesheetlinkPostRequest is now marked as a required field. If it is not provided in the POST request, the following error will be returned:

  • Error code: missingRequiredField

  • Error description: rateSheetId is a required field.

TM-169845

GET /vendors add Federal EIN and DOT fields

GET /vendors
GET /vendors/:vendorId

The Vendors API has been enhanced to now retrieve the following additional fields from the Carrier Insurance and Types and Payroll tabs:

  • federalId

  • dotNumber

TM-169846

POST /vendors add Federal EIN and DOT fields

POST /vendors

The Vendors API has been enhanced to now update the following additional fields from the Carrier Insurance and Types and Payroll tabs during the creation of a vendor profile using the API:

  • federalId

  • dotNumber

TM-170002

PUT /vendors add Federal EIN and DOT fields

PUT /vendors/:vendorId

The Vendors API has been enhanced to now update the following additional fields from the Carrier Insurance and Types and Payroll tabs for existing vendor records using the API:

  • federalId

  • dotNumber

ARTAdmin

Case Issue Case Name Description

TM-165589

TM-165589

Remove TM4Web REST APIs from ART Admin

The TM4WEB REST API option has been removed from the list of available APIs that can be configured in ARTAdmin. This is related to the deprecation of the TM4WEB REST API. The TruckMate REST API service provides the same functionality that was previously available in the TM4Web REST API.

TM-168952

Archive log option in ARTAdmin does not pick up log files with .log.1 (rotated files) filename

When file rotation is invoked, the extension of the rotated files will be kept as *.log with the rotation # attached before the file extension. For example, xxx.1.log, xxx.2.log instead of xxx.log.1, xxx.log.2.

The file archive action will move all the files with *.log extension to the archive folder. Because of the new file extension, all the files created by the file rotation will be moved.

ART

Case Issue Case Name Description

TM-168071

Correct error code if $select or $filter is invalid - invalidQueryParameter

Corrected the error code returned if the $select or $filter query parameters contains invalid properties or operators.

TM-169965

ART - token cache expired JWT token

Fixed an issue where an expired JWT TID token could still be used to authenticate successfully. Using an expired token in an API call will return a 401 error code.

Security Configuration

Case Issue Case Name Description

TM-169618

TruckMateConnect (Security.exe) - add a tab to view all TID enabled users

Added a new tab in the Security Configuration application related to the Trimble ID setup for internal TruckMate and external web users.

TM-169622

TruckMateConnect (Security.exe) - add a new column to user table

A column (TID Link) was added to the Email Address grid under the User tab used for linking a Trimble ID to an internal TruckMate user. The TID Link field can be toggled between True and False. If set to True, the email address cannot be identical to another TruckMate user’s email address that is already TID enabled. Also, a given TruckMate user cannot have more than one email address that is TID enabled.

TM4Web

Case Issue Case Name Description

TM-169547

Customer Profiles is looking at the vendor access group when checking if the client is part of an access group

Fixed an issue where an error was being encountered if a client profile was being created in Customer and Vendor Profiles and the client ID had the same value as a vendor ID for a web-enabled vendor profile.

TM-170122

Remove SOAP web services from TM4Web

Because the TM4Web API is being deprecated, TM4Web SOAP web services have been completely removed.