TruckMate 2020.4 New Features: Web / APIs

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

If you are interested in using the REST APIs for TM4Web, it is strongly recommended that you upgrade directly to 20.4 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 20.4

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 20.3 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.

The new $orderby system query option allows you to request resources in either ascending (default) or descending order using asc or desc.

Example: GET ~/trips?$orderby=tripNumber desc

This example request orders trips on property tripNumber in descending order.

You can use a maximum of two criteria, e.g., tripnumber AND status.

Example: GET ~/trips?$orderby=tripNumber desc, status

The TM4Web API will allow a container profile to be created if the submitted container does not already exist in TruckMate. This logic will apply to the tm4web/orders and tm4web/orders/\{orderId/intermodal} endpoints and to the POST and PUT requests.

On the Order Entry page in TM4Web, the Container Code and Check Digit will populate based on the 11 character Container Number.

Any previous values in the Container Code and Check Digit fields will be overwritten. This will occur only Any previous values in the Container Code and Check Digit fields will be overwritten. This only occurs if all of the following are satisfied:

Previously, empty disposition client codes would only be displayed if the client code was designated as Steamship Line or Rail Yard (Profiles > Client > Intermodal tab). This has been extended to also include the Port and Container Pool options.

When a PUR (Pick Up Request) for an Import, Export, Domestic Inbound, Domestic Outbound, or IMC (Intermodal Market Company) order is created, the following fields will be mapped to the Intermodal record of the order.

For an intermodal of movement type Empty Repo or Other, the following fields will be mapped as follows

TM4Web will create a new container profile record on completing a Pickup Request with all required container fields added by the user.

The TM4Web Order Entry page was modified to create a proper container profile as well as link Intermodal elements to Customer Service when the order is auto posted.

When an pick up request (PUR) is completed (i.e, the Complete button is clicked), a container profile will be created if all of the the following are met:

Updates to an order will trigger the creation of a container as well as the activation of a container code.

PUT Orders/Intermodal

The PUT request will determine if a container profile will need to be created or activated based on the JSON containerCode field. If the containerCode is different than what is on the current order the PUT request will follow the same logic as the POST request to determine if a container needs to be created or activated.

If the container code on the order is the same as the JSON continerCode no updates will be made on the order. This will be the equivalent of updating the attributes on the order.

The ability to define the Cost Allocation Rule when adding a carrier to a trip through the Trips API has been added.

A field costAllocationRule string has been added which maps to VENDOR_LOAD_SUMMARY.IP_OPTION art\Services\Base\Controllers\TripCarrierController.pas

valid values are:

Added the "IN_BOND" field to the Container Bill Details in WebAdmin > Client Features > Standard / External Trace > Bill Details > Container to display the Container IQ > Port Connect IN_BOND hold status.

Filtering has been added as a query parameter to the orders API endpoint using subset of the OData v4.0 expression syntax for $filter and $orderBy expressions. For example:

The $filter query option allows the requestor to filter the set of resources that are addressed by a request URL. $filter specifies conditions that MUST be met by a resource for it to be returned in the set of matching resources.

A total count value has been added to GET tm4web/orders and GET tm4web/trips.

When called using the JWT (JSON Web Token) from Web User login, the Reports API will only have access to the reports setup for the Web User in WebAdmin.

The username and password used to run the Crystal Report will be the same username/password as configured to run the ART Reports Service.

Further to this, when running a Crystal Report, the API will allow for certain System Set Report Parameters which will not be returned by the API and instead automatically set based on the Web User login.

The TruckMate REST API ART Service (/tm base URL), available in the TruckMate ART Server Administrator program (ARTAdmin.exe) was enhanced with the addition of Reporting functions in the TruckMate 20.3 release.

The /tm/reports API endpoints have the ability to access all available reports, retrieve the Crystal Report parameters and use the system set parameters to allow for the data returned to be restricted based on the Web User.

The GET method to the reports endpoint specifying a reportId corresponding to a Crystal Report can generate a report file as a PDF using the parameters supplied.

If all of the required parameters are not provided the API will return a 400 error and returns reportId, reportType, reportname, reportDescription, and reportParameters[] in the response body.

IF no parameters are necessary, the status code returns a 200 and returns reportId, reportType, reportname, reportDescription, reportSize, and reportData.I

When authenticated through the Web User JWT, the Crystal Report may contain certain parameters which will be populated by the API based on the Web User’s login. System set report parameters allows reports to be written which will filter the data returned to be based on the specified web user. (These parameters will not be returned by the API GET method as they will always be populated by the API and cannot be written to by the requestor.)

The following system parameters will be supported and automatically populated by the API:

The Reports API GET method can be used to print Zebra Labels. For example:

When specifying a reportId, the Reports API GET method will first check that the report exists and that the requestor has access to the report. If the reportId corresponds to a Zebra Label the API will require that a single parameter has been sent in the querystring of the request with the key set to orderId.

The orderId is used to both select the data for the label as well as determine authorization to the order.

On success the API will return the completed ZPL binary data stream directly in the response body, along with metadata about the file.

If the order cannot be found, due to either not being in the TruckMate system, or the requestor does not have access to the order, an error response code of 404 will be returned.

Now the TM4Web UI will filter out configured Zebra labels from the Crystal Reports offered.

You are now unable to see Zebra Print Labels in TM4Web Reports, even when they are configured in WebAdmin. Verified you can still run a GET for a ZPL in Postman Updated Confluence.

Report restrictions have been added to the TM/Reports API endpoint to prevent users from accessing certain reports and obtaining confidential information that they should not be able to access.

The Report Access Manager populates the "User_Reports_Access" table and this information is now being used by the GET method on the TM/Reports/ and TM/Reports/[reportId] endpoints.

The TruckMate Report Selection window provides the Report Access Manager window to set report restrictions for TruckMate users.

The NO_CHARGE field has been added to the GET/POST/PUT methods for TM4Web Orders

The ability to assign an interliner to an order through the ART Server has been added to the TM4Web API.

The ability to GET interliner records that are on an order via the ART Server has been added to the TM4Web API.

Added the ability to Approve an order through the TM4Web API.

When updating the status of a Posted Bill with "APPRVD" , it will set TLORDER.APPROVED = 'True', as well as update TLORDER.CURRENT_STATUS = 'APPRVD' if the CSERV.EXE  Approve Updt Status app. config. is set to True_.

There were a handful of memory leaks associated with the Art Server (ReportController.pas) when retrieving report data. Any related to TMCrystalNetPlugin.dll have been resolved in the TruckMate 20.4 release.

The possible Note Types have been added to the API Spec.

Added subTotal, extraCharges, tax1, tax2, and totalCharges to the GET/POST/PUT orders/orderId/interliner response body.

The Accessorial charge short description is now returned within the aCharge resource.

This update remedies some scenarios where special characters (like "&" and "%") were not supported in filtering based on text strings. Some enhancements include:

For APIs dealing with Orders and Trips, the record limit has been increased to 2500 records.

ART services can run within a multi-company environment. Each company must have its own ART Server API service configured and running and each service must identify the Company Id in the Database connection details set up using the ART Admin program. This ability to support multi company has been back merged to TruckMate 19.4.

The "billing" section has been added to the Client Import (Create & Update) and "accountspayable" sections for the Vendor Import (Create & Update) in the Profile Import REST API service.

The online swagger document has been updated to include these new sections.