TruckMate 2021.4 New Features: Web / APIs

Enhanced and refined TruckMate REST APIs

Since the initial introduction in TruckMate 2019, the TruckMate REST API endpoints and methods continue to be added, refined and streamlined in TruckMate 21.4. More endpoints will continue to be added and refined in future releases.

If you are interested in using the TruckMate REST APIs, it is strongly recommended that you upgrade directly to the latest version of TruckMate (i.e., 21.4) instead of an earlier release to take advantage of the most current, improved and expanded set of API methods and endpoints.

If you are in the early stages of implementing REST APIs and do not have an ART Server running yet, a snapshot of the 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.

For example:

RESTAPI OnlineHelp

You can also find a TruckMate REST APIs - Introduction getting started document and the ART Server Administrator Guide. Each REST API service will provide it’s own openapi.json specification information and getting started information.

RESTAPI OnlineHelpTM

The API Documentation web site links available on the Learning Center provides an interactive interface for the openapi.json file information.

TM4Web OnlineHelp C

New Features

The following methods and endpoints were either revised or added to the TruckMate REST API service in the TruckMate 2021.4 release.

TruckMate REST API service > Orders

The following API requests were added to the orders path endpoint in TruckMate 2021.4

GET

/orders/{orderId}/checklist

GET

/orders/{orderId}/checklist/{checklistId}

---------

POST

/orders/{orderId}/notes

DELETE

/orders/{orderId}/notes

GET

/orders/{orderId}/notes/{noteType}

PUT

/orders/{orderId}/notes/{noteType}

DELETE

/orders/{orderId}/notes/{noteType}

---------

POST

/orders/{orderId}/shipInstructs

DELETE

/orders/{orderId}/shipInstructs

DELETE

/orders/{orderId}/shipInstructs/{primId}

---------

POST

/orders/{orderId}/traceNumbers

PUT

/orders/{orderId}/traceNumbers

PUT

/orders/{orderId}/traceNumbers/{traceId}

DELETE

/orders/{orderId}/traceNumbers

DELETE

/orders/{orderId}/traceNumbers/{traceId}

TruckMate REST API service > Trips

The following API requests were removed from the trips path endpoint in TruckMate 2021.4. The assign and deassign endpoints are removed temporarily and will be included in a future update when they can accommodate all of the latest TruckMate enhancements.

POST

/trips/{tripNumber}/assign

POST

/trips/{tripNumber}/deassign

GET

/trips/{tripNumber}/tripHistory/{tripHistoryId}

The following API requests were added to the trips path endpoint in TruckMate 2021.4.

DELETE

/trips/{tripNumber}

---------

GET

/trips/{tripNumber}/orders/{orderId}/checklist

GET

/trips/{tripNumber}/orders/{orderId}/checklist/{checklistId}

---------

POST

/trips/{tripNumber}/orders/{orderId}/notes

DELETE

/trips/{tripNumber}/orders/{orderId}/notes

GET

/trips/{tripNumber}/orders/{orderId}/notes/{noteType}

PUT

/trips/{tripNumber}/orders/{orderId}/notes/{noteType}

DELETE

/trips/{tripNumber}/orders/{orderId}/notes/{noteType}

---------

POST

/trips/{tripNumber}/orders/{orderId}/shipInstructs

DELETE

/trips/{tripNumber}/orders/{orderId}/shipInstructs

DELETE

/trips/{tripNumber}/orders/{orderId}/shipInstructs/{primId}

---------

POST

/trips/{tripNumber}/orders/{orderId}/traceNumbers

PUT

/trips/{tripNumber}/orders/{orderId}/traceNumbers

DELETE

/trips/{tripNumber}/orders/{orderId}/traceNumbers

PUT

/trips/{tripNumber}/orders/{orderId}/traceNumbers/{traceId}

DELETE

/trips/{tripNumber}/orders/{orderId}/traceNumbers/{traceId}

Detailed information is available within the Trimble Transportation Learning Center web site in the TruckMate > Product Guides > TruckMate REST API Reference Guides.

TM4Web GET Orders filter supports web users

Now you can use a Web User JWT to access the $filter and $orderby orders query parameters for the GET /tm4web/orders endpoint.

Improvements

This section describes these new features:

Filter trips by orders/orderId

A new filter feature allows you to select trips using '/trips?$filter=orders/orderId' in (range of OrderId values)

For example:

  • GET /trips?$filter=orders/orderId in (20874,20999)

  • GET /trips?$filter=orders/orderId in (20874,20999)?expand=orders

  • GET /trips?$filter=orders/orderId in (20874,20999)&limit=4&offset=1&expand=orders: value

Trips API: Removed Orders sub endpoints

The orders sub endpoints previously replicated under the TruckMate REST API service > Trips endpoints have been deprecated and removed.

Now any requests made to any of the Trips API > Orders sub endpoints will return a 301 error:

Moved Permanently "The Trips API does not support this endpoint. Access to orders must be made via the Orders API".

These trips > orders endpoints will remain:

  • GET /trips/{tripNumber}/orders

  • POST /trips/{tripNumber}/orders

  • PUT /trips/{tripNumber}/orders/{orderId}/status

GET tm4web/orders - allow all types

The type parameter for the GET tm4web/orders/ endpoint now allows you to specify which type of orders to return (T = TruckLoad, P = Pickup, Q = Quote). For example, GET tm4web/orders?type=Q.

Update summary and descriptions

The text in the openapi.json API document for the summary and description for the /tm > traceNumber, barcode, caller and customDefs endpoints has been updated and expanded.

Update sealedTrip Field

Updated the sealedTrip field in the /seals API to correctly display the trip where the seal was applied.

PHP 8, Apache Upgrades

PHP 8 Upgrade The TM4Web installer has been updated to include PHP 8.0.12 for increased speed and security. For more information please read the release notes documentation available on php.net. (https://secure.php.net/)

Apache 2.4.29 Upgrade The Apache version included with TM4Web has been updated to 2.4.51 with added features for greater stability, security, and resource efficiency. For more information please read the documentation available on the Apache web site https://httpd.apache.org/.

jQuery and Kendo Upgrades

Some of the foundational web tools (JQuery and Kendo), being used by TruckMate and TM4Web have been updated. Kendo UI to 2021.3.1109 and jQuery to 3.6.0. Upgrading these 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.

Bug Fixes

This section describes these new features:

Apply filter with traceNumber and traceType applied together

A new filter feature allows you to apply a filter to orders where the traceNumber and the traceType are applied together.

For example:

  • GET orders?$filter=(traceNumbers/traceType eq B and traceNumbers/traceNumber eq 676575)&expand=traceNumbers

  • GET orders?$filter=(traceNumbers/traceNumber eq 'abc' and traceNumbers/traceType eq 'B')&expand=traceNumbers

Trip history response codes corrected

The GET /trips/tripNumber/tripHistory/tripHistoryId endpoint was removed.

OSD createdBy set to API key of user who submitted request

Previously, in Over Short and Damaged (OSD) entries, the createdBy field value was the user running the ART server.

Now, the value is the API key of the user who sent the request through the TruckMate REST API service.

400, 401 and 403 response codes added

  • The 403 (Forbidden access) response code was added to the API documentation for the following TruckMate REST API service endpoints:

    • GET ​/orders​/{orderId}​/aCharges/{aChargeId}

    • GET ​/trips/{tripNumber}/orders

    • GET /trips/tripNumber/tripHistory

    • GET ​​shipInstructs endpoints

  • The 404 (Resource not found) response code was added to the API documentation for:

    • POST /orders/{orderId}/aCharges

  • The 400 (API does not serve endpoint), 401 (Unauthorized), and 403 (Forbidden access) responseCodes were added to the API document for:

    • GET ​/orders​/{orderId}​/caller

    • GET ​/orders​/{orderId}​/shipper

    • GET ​/orders​/{orderId}​/careof

    • GET ​/orders​/{orderId}​/otherContact

    • GET /orders​/{orderId}​/pickupAt

    • GET ​/orders​/{orderId}​/consignee

TM4Web Quote - Add New Record saves previous entry

When creating a quote using TM4Web and entering the details, clicking Add New Record will save the line just entered and then let you enter a new line. There is no need to manually save the current line entry before adding a new one.

TM4Web contacts fields

The TM4Web Order Summary page will now display the Contacts fields (for the Caller, Shipper, and Consignee) on the trace page. Previously, there were some situations where the fields for the Contacts sections would not be displayed.

ART Server security improvement

The ART Server API services have been changed to prevent a potential security issue.

PHP 8 compatibility

The upgrade to PHP 8 for TM4Web introduced some issues that have been resolved.

Previously, you might have received errors like:

  • MicrodeaWS→SoapFault creating MaddSoapClient: Error finding "uri" property

  • MicrodeaWS→Error creating MaddSoapClient:

Properties > Logging tab archive fields

The Archive After Days, Rotate File Count and Rotate File Size fields in the ART Admin Service > Properties > Logging tab have been updated. These fields will no longer accept negative integers, and there is a maximum value limit of 2147483647.

TM 157603 214a

A previous issue with setting the ART Log Filters has also been resolved.

Improved 'Type' parameter description

The 'Type' parameter description in the /tm > openapi.json API documentation has been updated to include more information about the order types.

Count query parameter added to /orders

The Count query parameter has been added to the response body when a Web User runs a GET request to /orders through the API to describe the number of records returned.