TruckMate 2021.1 - Release Notes

A new Select Current Location From: setting has been added to the TruckMate for Web > Web Admin program > Global Configuration > Base Setup > Mapping tab to allow you to bypass the zone information supplied by mobile comm polling and use the order’s current zone instead.

In TM4Web this new setting determines which location to display on the Current Location map.

Some of the foundational web tools (JQuery and Kendo ), being used by TruckMate and TM4Web have been updated and will be available in 21.1. Upgrading the integrated tools provides quality, security and performance enhancements.

Kendo UI is a comprehensive HTML5 user interface framework for building interactive and high-performance websites and applications.

jQuery is a lightweight, "write less, do more", JavaScript library. jQuery takes a lot of common tasks that require many lines of JavaScript code to accomplish, and wraps them into methods that you can call with a single line of code.

Since the initial introduction in TruckMate 19.4, the TM4Web REST API endpoints and methods continue to be added, revised and streamlined in TruckMate 21.1. More endpoints will continue to be added and refined in future releases.

If you are interested in using these TM4Web REST APIs, it is strongly recommended that you upgrade directly to 21.1 instead of an earlier release to take advantage of the most current, improved and expanded set of API methods and endpoints.

New TM4Web endpoints in 21.1

The TM4Web RESTful API refers to the application program interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data to interact with the TruckMate data and to provide secure access to Freight Bill information, Rate Quotes, Tracing functionality and Status Changes.

The APIs contain standard TruckMate objects and each object is associated with a REST Resource or Resource Collection. Before using TM4Web RESTful web services you must take into account the security requirements for gaining access, along with their corresponding supported methods and expected payload structures. TM4Web 21.1 includes REST APIs for Orders, Trips and Web Users.

If you are in the early stages of implementing TM4Web REST APIs and do not have an ART Server running yet, a snapshot of this same swagger JSON information is available as a reference web site available within the Trimble Transportation Learning Center in the TruckMate > Product Guides > TruckMate REST API Reference Guides > TM4Web > TM4Web API Documentation.

You can also find a getting started document; TM4Web APIs Getting Started Guide and a sample collection of TM4Web API requests to use as reference examples.

The TM4Web API Documentation web site link available on the Learning Center provides the swagger.JSON file information.

A new Documents API has been added to the TruckMate REST API service.

The new Documents API method will enable public viewing of specific documents through a URL, linked with a time sensitive secure token. Synergize by Microdea is currently the only Document Management System supported by the TruckMate Documents API. The Synergize SOAP API is used to retrieve documents from the configured repository.

TruckMate API Credentials are required to generate the security token.

The user configured in ART Admin to run the TruckMate API Service will determine which imaging documents can be accessed for generating the security token.

A POST to the Documents API “token” endpoint, including document type and bill number in the URL path, will generate the unique security token. No payload is required, unless an explicit expiration time is required. The default expiry is one week, when not specified.

The generated token will allow access to only the specific document type and document identifier used to generate the token. A GET method to the Documents API including the correct document type, document identifier (such as bill number) and document format in the URL path, and the security token as a query string parameter will retrieve a document from the imaging system. Documents will be converted and returned in the specified format (only PDF is supported at this time).

The new TruckMate REST API service > DOCUMENTS RESTful API endpoint allows you to request documents scanned into Synergize based on a freight bill number. Once a document is scanned into Synergize, it is available for viewing through a URI with an embedded (URI parameter) token. This enables single-click, hyperlink access from any Internet-capable device.

The getDocument method allows you to retrieve a document from the imaging system, by document type and document identifier. Documents will be converted to the specified format. When called with a specific-use token (generated via this same API), only documents for the specific bill number and document type associated with that token will be viewable.

A new GET ​/tm/transitTimes TruckMate REST API endpoint has been added to allow GET requests to get Service Level Matrix Transit Times based on a start zone, end zone, service level and pickup date.

Uses the Service Level Matrix to calculate estimated delivery dates given a pickup and delivery location, service level(s) and pickup date(s). Some parameters as noted accept arrays so you can perform multiple lookups with a single request.

The Orders and Trips Status Update APIs have both been modified to accept new fields in the API request. The fields latitude, longitude, locationDescription, and zoneIdLookup can now be optionally included in the payload request.

When a lat/long pair is present in the status update, the lat-long will be used to update the GPS coordinates, “Last Poll Location”, “Last Poll Zone” and “Last Poll Date” of the resources on the trip (driver, power, trailer, undelivered freight). The Position History will also be updated.

The locationDescription is a human-readable string provided by the integrating application to describe the current location (e.g., “5 km SW of Brampton, ON”). It will be used to update “network locations” in TruckMate.

The zoneIdLookup field will allow the integrating application to apply status updates without needing to know the specific zone ID to apply.

For the Orders API, zoneIdLookup valid values are:

For the Trips API, zoneIdLookup valid values are:

Trip Position Updates

A new endpoint called "positions" has been added to Trips API, which allows the requestor to provide an array of position updates for resources based on the latitude and longitude provided in the payload.

Sending a POST to the positions endpoint allows the requestor to provide a position update to a trip, when that position update is NOT tied to a corresponding status change. This is used for breadcrumb GPS updates that come independently of driver workflow events. The fields latitude, longitude, locationDescription, locationDateTime, and receivedDateTime can all be optionally included in the payload request.

When a lat/long pair is present in the status update, the lat-long will be used to update the GPS coordinates, “Last Poll Location”, “Last Poll Zone” and “Last Poll Date” of the resources on the trip (driver, power, trailer, undelivered freight). The Position History will also be updated.

The locationDescription is a human-readable string provided by the integrating application to describe the current location (e.g., “5 km SW of Brampton, ON”). It will be used to update “network locations” in TruckMate.

locationDateTime is the date-time the location was originally recorded. If omitted, it will default to the current date-time.

receivedDateTime is the date-time the location was received by the network from the remote device. If omitted, it will default to the value of locationDateTime.

The ability to Post or Update oblHold, inBond, and agricultureHold has been added to the orders and intermodal endpoints. If these fields are not specified in the request, they default to the shipper’s default holds.

For the TM4Web REST API, agricultureHold, oblHold, and inBond, are defined by a True or False in the intermodal object of the following endpoints:

If these fields are not defined in the request, the fields will be set with the shippers defaults found in: CLIENT.DEFAULT_IN_BOND, CLIENT.DEFAULT_OBL_HOLD, CLIENT.DEFAULT_AGRICULTURE_HOLD

The TM4Web REST API agricultureHold, oblHold, and inBond fields are now defined in the intermodal object of the following endpoints:

The TM4Web API ability to request a given trip manifest through a RESTful API has been enhanced in order to share trip loading actuals and loaded trip manifests with other software vendors.

Now you can compare the barcodes which were manifested to the trip to the barcodes that were originally expected to provide item-level continuity between the plan and actual use for trip execution.

The imaging REST API /arprintjobdetails endpoint has been enhanced with a new dynamic query ability to search by any column within the AR_PRINT_LOG_DETAIL table. This new feature is available for the Tier 1 Imaging REST API License (63000) only.

For both single and multi company environments, TruckMate has changed the parameter glAccountId to be an optional field for Imaging REST API endpoint /apbills/create. When glAccountId is entered, it will continue to validate against the provided company ID as is the current functionality today.

Refer to the TruckMate Tier1 Imaging Rest API Documentation available on the Trimble Transportation Learning Center for details about the openAPI spec and the GET APBill endpoint.

A new apAgingDate optional parameter has been added to the imaging REST API /interlinerpayables/approve endpoint to allow updates to the AP_AGING_DATE.

Refer to the TruckMate Tier1 Imaging Rest API Documentation available on the Trimble Transportation Learning Center for details about the openAPI spec. and this endpoint.

All TLDTL user fields have been added to the POST and PUT /orders and /orders/orderId/details endpoints.

OpenAPI uses the term security scheme for authentication and authorization schemes. OpenAPI 3.0 lets you describe APIs protected using specific security schemes:

For example: GET /tm4web/login requires the Bearer Token Authorization of the current/active JWT.

Report Restrictions have been added to the TM/Reports endpoint when using a TruckMate API Key to prevent users from viewing reports they are not permitted to use or obtaining confidential information they should not be able to access.

Report permissions for users are set using the TruckMate Report Access Manager which populates the "User_Reports_Access" table used to apply the restrictions to the GET method on the TM/Reports/ and TM/Reports/[reportId] endpoints.

The API filters and data validation has been improved. This does not affect any of the underlying logic other than the structure of the JSON that is returned. Changes include:

For Orders and Trips APIs, the maximum allowed record limit has been increased to 2500, and validation has been added regarding the limit.

The TM4Web APIs will now only see orders for the company from which the ART service is run.

Note: Do NOT use TMWIN (schema owner) as the ART service login name, as this bypasses the Multi Company views by default since it is the schema owner.

The Multi-Company access is configured in Profiles > Company Profiles program > Window menu > Organization Setup > Company Access tab.

With the previous release of TruckMate 20.3, the TruckMate REST APIs have all been updated to use OpenAPI 3.0 (2017) from Swagger 2.0 (2014).

In this release of TruckMate 21.1, the API documentation endpoint has been renamed from /swagger.json to /openapi.json.

For example, use

GET …​../tm/openapi.json

instead of

GET …​../tm/swagger.json

“Swagger” was the original name of the OpenAPI specification, but the specification was later changed to “OpenAPI” to reinforce the open, non-proprietary nature of this standard. Now, “Swagger” refers to API tooling that supports the OpenAPI spec, not the spec itself.

Many of us may still refer to both names interchangeably, but “OpenAPI” is how the spec should be referred to going forward. The “OpenAPI specification document” or “OpenAPI document” is the .json file created to describe APIs.

The externalDocs links for the TruckMate REST APIs provide a link the Trimble Transportation Learning Center web site where you can search or drill down to find the TruckMate section and the Trimble Transportation Learning Center in the TruckMate > Product Guides > TruckMate REST API Reference Guides.

You can also find the openapi.json (formerly called swagger.json) information in you do not have a TruckMate ART Server setup.

New methods and endpoints and their associated capabilities have been added to the TruckMate REST API service.

Refer to the TruckMate Rest API Documentation available on the Trimble Transportation Learning Center.

All APIs will now require session id Bearer Token authorization at a minimum with respect to authorization.

The following APIs have been updated and supporting Bearer Token authentication using API Key or Session ID token, including all GET calls and POST calls except login/logout.

For POST calls in the future, TruckMate will only continue to support payload validation through "sessionId" until the release of TruckMate 2022.1.

After 22.1, all APIs will only support and require Bearer Token authentication.

Refer to the ART Server Administrator Guide > "Generating API TruckMate Credentials for Login" section with instructions on how to create a Bearer Token and work with Bearer Token authentication for those APIs which use this form of authorization.

OpenAPI document updated for FB Import API. (The lock icon on the right indicating Authorization is required.)

OpenAPI document updated for Profile API. (The lock icon on the right indicating Authorization is required.)