TruckMate 2020.4 New Features: Web / APIs

New Features

Enhanced and refined TM4Web RESTful 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

  • GET /orders/{orderId}/interliners/{orderInterlinerId}

  • GET /orders/{orderId}/interliners

  • POST /orders/{orderId}/interliners

TM4Web APIs

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.

Requires TruckMate license 61140.

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.

TM4Web OnlineHelp A

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.

TM4Web OnlineHelp B

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

TM4Web OnlineHelp C

ART orderBy (TM-140283)

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

POST/PUT Orders/Intermodal - Container profile validation (TM-152274)

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.

Endpoint Request Authorization

tm4web/orders

POST

Client API Key, TruckMate API Key

tm4web/orders

PUT

TruckMate API Key

tm4web/orders/{orderId}/intermodal

POST

Client API Key, TruckMate API Key

tm4web/orders/{orderId}/intermodal

PUT

Client API Key, TruckMate API Key

POST/PUT Orders/Intermodal - Container code validations (TM-152775)

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

TM 152775 204

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:

  • The length of the entered Container Number is 11 characters.

  • The Container Code and Container Digit fields are enabled, (even if the fields are set as hidden).

TM4Web Intermodal Order creation - Empty disposition (TM-152776)

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.

TM4Web Intermodal Order creation - Intermodal field linkage (TM-152777)

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.

PUR Field (Default labels) Customer Service Intermodal Field (Default layout)

Caller:Code

Caller

Shipper:Code

Pickup

Consignee:Code

Customer

Intermodal Contacts > Empty Disposition > Code

Empty Disp

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

PUR Field (Default labels) Customer Service Intermodal Field (Default layout)

Caller:Code

Caller

Shipper:Code

Pickup

Consignee:Code

Customer

TM4Web Intermodal Order Creation - Create a new container profile record (TM-152802)

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:

  • The Container Code and Container digit fields are defined.

  • A container does not exist

  • The request is automatically created in Customer Service (Web Admin Option: Client Features > Order Entry > PUR > Auto Approve, Post, Update > Auto Update To Customer Service = Always or By Access Group). The determination of the creation or activation of the container code will be based on the CONTAINER_CODE field value.

    TM 152802 204

PUT Orders/Intermodal - validations (TM-152805)

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.

POST /trips/{tripNumber}/carriers - Add field costAllocationRule (TM-152856)

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:

0 = 'oneBill'

1 = 'weight'

2 = 'charges'

3 = 'rateAll'

4 = 'tonMile'

5 = 'cube'

6 = 'consDel'

7 = 'consP/U'

Port Connect Holds (TM-153044)

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.

TM 153044 204a

Improvements

API filter orders (TM-138805)

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:

GET ~/orders?$filter=( billNumber eq 'A000389' or billNumber eq 'A000388') and billDate gt 2020-10-01

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.

Syntax

OData $filters are comprised of:

  • Field name

  • Operator

  • Field value

Field Names

Properties of complex properties can be used via the same syntax as in resource paths, i.e., by specifying the name of a complex property, followed by a forward slash (/) and the name of a property of the complex property. Example:

GET ~/orders?$filter=(traceNumbers/traceType eq 'S' and traceNumbers/traceType ne 'N')

Operators

Operators are used in the query expression to filter the set of resources. Sub-expressions are combined using logical operators such as and, or, and not, comparison operators such as eq, lt, gt, and so on, and collection operators such as any and all.

SQL OData Example Notes

!=

ne

The Parenthesis Operator controls the evaluation order of an expression.

( )

( )

( )

( )

<

lt

le

=

eq

GET ~/orders?$filter=billNumber eq 'A000389'

>

gt

>=

ge

AND

and

GET ~/orders?$filter= billNumber eq 'A000389' and opCode eq 'EAST'

IN

in

GET ~/orders?$filter=orderId in(111,222)

(Work In Progress) The in operator returns true if the left operand is a member of the right operand. The right operand MUST be either a comma-separated list of primitive values, enclosed in parentheses, or a single expression that resolves to a collection.

ne null

eq null

not

or

GET ~/orders?$filter=billNumber eq 'A000389' or billNumber eq 'A000388'

Returns orders with billNumber 'A000389' or 'A000388'.

DateTime Filtering

Filters requiring date-time values must be in the ISO 8601 format.

  • Date and time values are ordered from the largest to smallest unit of time: year, month (or week), day, hour, minute, second

  • Each date and time value has a fixed number of digits that must be padded with leading zeros.

  • Representations must be done in the extended format with separators added to enhance readability

  • ISO 8601 uses the 24-hour clock system.

  • The character [T] must be used as time designator to indicate the start of the representation of the time of day component, as specified in ISO 8601.

  • Either the seconds, or the minutes and seconds, may be omitted from the time format for greater brevity but decreased precision

  • Historically TruckMate does NOT do any timezone handling, the time entered by the user will be the time stored into the database and viewed throughout TruckMate with no timezone specifics or alterations.

YYYY

four-digit year

MM

two-digit month (eg 03=March)

DD

two-digit day of the month (01 through 31)

T

a set character indicating the start of the time element

hh

two digits of an hour (00 through 23, AM/PM not included)

mm

two digits of a minute (00 through 59)

ss

two digits of a second (00 through 59)

mmm

three digits of a millisecond (000 through 999)

DateTime Examples

GET ~/orders?$filter=year(createdTime) eq 2019
GET ~/orders?$filter=( billNumber eq 'A000389' or billNumber eq 'A000388') and billDate gt 2020-10-01
GET ~/orders?$filter=createdTime ge 2020-01-15T14:28:00

Math Expressions

Current ART API filter syntax does not support the ability to do math expressions.

Field Values - Quotes

Field values may or may not be wrapped in single quotes - and should behave the same. eg: these two calls should return the same results:

GET ~/orders?$filter=billNumber eq 'A000389'
GET ~/orders?$filter=billNumber eq A000389

'

%27

/

%2F

?

%3F

%

%25

#

%23

&

%26

Additional Information

OData services should not require any query options to be specified in a request, and should fail any request that contains query options that it does not understand.

The SQL WHERE clause that is built by the $filter call will be logged by the ART server (or displayed if running in console). This will make it easier to test and debug different combinations.

ART totalCount (TM-139147)

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

GET tm4web/orders

TM 139147 204a

GET tm4web/trips

TM 139147 204b

ART Reports API Crystal - Web User authorization (TM-151379)

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.

TM 151379 204

Client JWT is not able to access Reports set-up for Vendors, and vice versa.

GET method /reports/{reportId} - Crystal Reports (TM-151382)

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

GET method /reports/{reportId} - Crystal Reports - System set report parameters (TM-151383)

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:

Parameter Name Notes

_AccessCode

Web User’s Access Code

_ClientID

The first Client Id from the Web Users Access Group

_VendorID

The Vendor Id associated with the Web Users Access Group

_UserName

The Web Users username

GET method /reports/{reportId} - Zebra labels (TM-151385)

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

DOMAIN/reports/2345?orderId=3370

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.

Store Zebra Templates - filtered out from TM4Web UI (TM-151386)

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.

ART Reports API Crystal - TruckMate API key report restrictions (TM-152376)

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.

TM 152376 204

Allow setting a no charge order (TM-152541)

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

  • If a POST/PUT method sets the field to noCharge, it will clear billing fields and repopulate billing fields.

  • You are not able to update noCharge on "TLORDER.APPROVED = 'True'" and TLORDER.INTERFACE_STATUS_F  0 orders.

Allow assigning an Interliner to an order (TM-152612)

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

POST /tm4web/orders/\{orderId}/interliners
  • The Interliner must be valid TruckMate Vendor.

  • Adding an Interliner is not allowed when the bill has been interfaced to billing (TLORDER.INTERFACE_STATUS_F > 0).

  • Adding Interliner not allowed when the bill has been approved (TLORDER.APPROVED = 'True').

API - Add Interliners resource to orders (TM-152635)

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

GET /tm4web/orders/\{orderId}/interliners/\{orderInterlinerId}

Freight Bill based status change modified to allow approving bill (TM-152652)

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

PUT /tm4web/orders/\{orderId}/status

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

Report API performance improvement (remedy memory leaks in ReportController.pas) (TM-153108)

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.

Add possible Note Types to the API Spec (TM-153135)

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

B

Billing

C

Container

D

Driver

I

Import

O

Other

S

OSD

W

Write-off

1

User 1

2

User 2

3

User 3

TM 153135 204

Add charges fields to POST orders/orderId/interliner (TM-153313)

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

aCharge description added (TM-153480)

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

TM 153480 204

API filter - validations - bug fixes (TM-153485)

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

  • Better handling of IN operands (with or without spaces)

  • Allows using startwith() and endswith()

  • Better error handling (return 400 if invalid fieldname or operand)

  • Better handling of spacing and brackets

API record limit increased to 2000+ (TM-153573)

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

TM 153573 204

Add multi-company support for TM4Web REST API to 19.4 (TM-153575)

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.

TM 153575 204a

Non-Schema Owner

The ART Admin database connection must use a non-schema owner that has access to the company that is defined to connect to.

Multi-Company access is configured in: Company Profiles > Window > Organization Setup > Company Access.

Never use DB2ADMIN or any schema owner when trying to use TruckMate in a multi-company environment.

Company Profiles

ART services do NOT utilize the Company Profiles > Organizational Setup allowing multiple Company access per user.

To view and setup Company access per user go to the Company Profiles program > Window menu > Organizational Setup window.

TM 153575 204b

Custom definitions added to the Profile Import API for client imports (TM-152659)

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.

TM 152659 204

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