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

TruckMate versions 2022.1 and 2022.2 have been released as a single upgrade package available for download on the Trimble Transportation Client Center.

TruckMate version 2022.1 is not available as a stand-alone download.

If you are upgrading to TruckMate 2022.2 from an earlier version, review the Release Notes and New Features Guides for this version, along with those for all the versions in between.

For example, if you are currently using TruckMate 2020.3 and you want to upgrade to 2022.2, review the materials available for versions 2020.4 through 2022.2.

If you are interested in using the TruckMate REST APIs, we recommend that you upgrade directly to this version of TruckMate (2022.1) 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:

TruckMate REST API feature changes

Added

To tm/trips:

  • DELETE /trips/{tripNumber}/orders/{orderId}

  • DELETE /trips/{tripNumber}/orders

  • GET /trips/{tripNumber}/drivers

  • GET /trips/{tripNumber}/powerUnits

Removed

From tm/orders:

GET /orders/{orderId}/contacts

From tm/trips:

DELETE tm/trips/{tripNumber}/carriers/{loadSummaryId}/aCharges/\

Several API requests related to /orders were removed from tm/trips in the TruckMate REST API service. This was done to support accessing orders using the existing endpoints in tm/orders instead of tm/trips.

For each of the items listed below, all the URL paths that were removed begin with

tm/trips/{tripNumber}/orders/{orderId}

GET

/aCharges/{aChargeId}

/aCharges

/details/{orderDetailId}/barcodes/{barcodeId}

/details/{orderDetailId}/barcodes

/caller

/careOf

/checklist/{checklistId}

/checklist

/consignee

/contacts

/customDefs/{customDefId}

/customDefs

/dangerousGoods/{dgId}

/dangerousGoods

/details/{orderDetailId}

/details

/interliners

/intermodal

/notes/{noteType}

/notes

/traceNumbers/{traceId}

/traceNumbers

/osds/{osdId}

/osds

/otherContact

/pickupAt

/pods/{podId}

/pods

/shipInstructs/{primId}

/shipInstructs

/shipper

/pods/{podId}/signature

/xrefCode

POST

/aCharges

/details/{orderDetailId}/barcodes

/customDefs

/dangerousGoods

/details

/interliners

/intermodal

/notes

/traceNumbers

/osds

/shipInstructs

PUT

/aCharges/{aChargeId}

/details/{orderDetailId}/barcodes/{barcodeId}

/customDefs/{customDefId}

/dangerousGoods/{dgId}

/details/{orderDetailId}

/intermodal

/notes/{noteType}

/traceNumbers/{traceId}

/traceNumbers

/osds/{osdId}

DELETE

/dangerousGoods

/shipInstructs

/aCharges/{carrierAChargeId}

/customDefs/{customDefId}

/dangerousGoods/{dgId}

/notes/{noteType}

/notes

/traceNumbers/{traceId}

/traceNumbers

/osds/{osdId}

/shipInstructs/{primId}

New Features

Imaging

Imaging interliner payable tolerance limit override (TM-161252)

A new optional parameter in the POST imaging/interlinerpayables/approve endpoint lets you override the tolerance by a dollar amount when using the API to approve an interliner payable record.

TM 161252 221

Trips

Planned departure and scheduled arrival dates (TM-159002)

The TruckMate REST API tm/trips endpoints now include planned departure and scheduled arrival fields.

Improvements

This section describes features that have been improved:

General

Agent service deprecated (TM-156673)

The Agent REST API service has been deprecated and removed from version 2022.1 of the ART Server Administrator.

TM 156673 221a

Endpoints sorted alphabetically in openapi.json (TM-160693)

The internal API documentation in the openapi.json file is now sorted in alphabetical order.

True/False is case insensitive (TM-160343)

The True and False fields in the ART Server services now ignores capitalization or upper and lower case forms for any true and false values.

Retrieve all resources for a trip (TM-161310)

The GET tm/trips and GET tm/trips/{tripNumberId} endpoints in the TruckMate REST API service now use arrays for each resource type. This means it can retrieve all the resources for a trip. This change applies to these resource types:

  • containers

  • chassis

  • drivers

  • powerUnits

  • trailers

  • equipment

Reason code added to status history (TM-161179)

The response body in the tm/orders statusHistory section now contains reason and reasonDescription fields.

The reason field was removed for trip-based status change requests.

Consistent value formats in tm/trips (TM-161343)

For resources, the type and action fields return consistent value formats in the request and response body for tm/trips.

Five ART Server Administrator logging levels (TM-161046)

The ART Server Administrator application now has new levels to group log files.

  • Error

  • Warning

  • Notice

  • Information

  • Debug

Retrieve trip PUs and drivers (TM-160536)

Now, you can retrieve a list of drivers and power units in tm/trips for their endpoints:

  • drivers

  • powerUnits

TM4WEB WorkOptima imaging (TM-161972)

TM4Web imaging now supports WorkOptima.

To use it, set up Other imaging vendor document types in Codes Maintenance. For each document type, set the URL to:

http://TM4WEB DOMAIN/imaging/workOptima.msw?documentType=%t&searchValue=%i

Remove contacts field (TM-161744)

The contacts endpoint was removed from the TruckMate REST API (/tm) service. This affects:

POST

tm/orders

GET

tm/orders

GET

tm/orders/{orderId}

PUT

tm/orders/{orderId}

GET trips/{tripNumber}/stops field functionality added (TM-160319)

The arrivedActual and departedActual fields in the GET trips/{tripNumber}/stops endpoint now display the correct values.

Validation

Verify entries match OpenAPI spec (TM-161201)

All TruckMate REST API services now verify the request body entries match the OpenAPI spec. An error message appears if there is a mismatch. For example:

{"errorCode":400, "errorText": "orderId is expected to be a valid integer."}

TM 161201 221a

POST tm/trips validation (TM-161407)

The POST tm/trips API request checks for valid entries before creating a trip. For example:

  • The values provided are valid, not null or empty, within the max. length and match the OpenAPI spec.

  • The zone is a valid zone ID.

  • If a route ID is provided, the pickupDeliveryTrip setting must be True.

  • If resources are provided in the stops array, you must also provide a zone.

Web User JWT authorization for documents (TM-160743)

The tm/documents endpoint in the TruckMate REST API service can now use a web user Java web token (JWT) for authorization to retrieve a document.

Responses

Improved error messages (TM-160753)

Some error messages now provide more information about what caused an error and how to fix it.

All error messages now follow a consistent format.

400 exceeds max length

An error message appears if any entry exceeds the maximum number of characters for a field. It lets you know which field and how many characters are allowed. For example:

billNumber exceeds maximum length of 20 character(s)

400 invalid request fields

An error message appears if no fields in the TruckMate REST API orders and webUsers endpoints are flagged as being required, but the PUT or POST request body is empty. For example:

No valid fields sent with the request. Please refer to the OpenAPI Specification for a list of supported fields.

OpenAPI response codes updated (TM-161566)

The API documentation in the OpenAPI specification has been updated. All of the endpoints describe the correct response codes.

The 404 (Not found) error code responses for tm/trips, tm/orders, and related sub endpoints return consistent error text.

Consistent error text (TM-161379)

  • The responses in tm/trips and related sub endpoints have been updated. Now they return consistent error text for the 404 (Not Found) error code.

  • The endpoints for tm/trips and tm/webUsers use proper error text when dealing with a 405 (Method Not Allowed) status code.

Orders

Access orders using tm/orders (TM-159748)

For better workflow and consistency, the orders sub paths have been removed from the tm/trips API path. Access these endpoints through the tm/orders API path.

The only orders sub resources accessible through tm/trips are:

GET

/trips/{tripNumber}/orders

Retrieve all orders assigned to a trip

POST

/trips/{tripNumber}/orders

Assign an order to a trip

GET

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

Retrieve an order assigned to a trip

PUT

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

LTL status change

OData filter for order trace numbers (TM-162222)

Now you can use an OData filter on trace numbers for the GET tm/orders/orderId/traceNumbers endpoint.

Unassign orders from a trip (TM-160547)

You can now unassign orders from a trip using the Trips API and the DELETE methods.

  • DELETE /trips/:tripNumber/orders

  • DELETE /trips/:tripNumber/orders/orderId

Bug fixes

This section describes important bug fixes. The complete summary list of improvements and fixes is available on the Learning Center in the TruckMate 2022.1 Release Notes.

General

OpenAPI webUpdate options (TM-161388)

The webUpdate field for the tm/orders endpoint displays a list of valid options.

  • False

  • Done

  • WIP

  • ''

The TruckMate REST API service OpenAPI specification now reflects the correct list.

TM 161388 221a

Empty request body returns 400 code (TM-161585)

When sending a request to an endpoint that has no required fields but at least one field that needs to be sent, changes were made to how it handles the request body being empty. Instead of returning a 200 (Success) code, it now returns a 400 (Client Error) code.

Document types with spaces (TM-161815)

Now, you can generate and retrieve a document even if the document type contains a space.

Terminal stop resources (TM-161750)

The tm/trips API requests now display resources for a delivery and terminal stop that has resources and actions.

Creating stops logic (TM-161539)

Now, the tm/trips API consistently creates stops for non-terminal zones when creating P&D trips.

Memory leaks fixed (TM-162215)

A memory leak no longer occurs when you:

  • Use tm/orders to create new orders

  • Use tm/trip to create trips with stops and resources

  • Use the GET openapi.json query

POST /notes error fixed (TM-162458)

POST /orders/{orderId}/notes no longer returns an error when creating notes for an order.

TM4Web external trace (TM-162363)

The TM4Web external trace results now load correctly with no PHP error.

Using special characters (TM-161836)

Special characters (such as â, ê, î, ô) are now saved correctly when using the /tm POST or PUT methods.

Locating TMCrystalNetPlugin DLL (TM-163409)

When launched as a Windows service, the TruckMate API was unable to find the TMCrystalNetPlugin DLL when accessing the /reports endpoint. This has been resolved for version 2022.1.

Orders

Unassign orders from a trip (TM-161329)

Now, tm/trips can unassign orders already assigned to a trip without an SQL error.

tm/orders phoneNumber (TM-141879)

Because you cannot write to it, the phoneNumber field has been removed from the tm/orders request body schema. It combines the phone and phoneExt fields and can be returned in the response body for all contact types.

Order currency populated (TM-162094)

The POST tm/orders API now populates the currency when you enter a COD amount.

Unexpected error when creating orders (TM-162335)

The TM4Web REST API no longer return a 500 (Internal Server Error) error when using POST tm4web/orders to create orders.

Error message with phone values over 13 characters (TM-162146)

The TruckMate REST API no longer returns an error when using POST or PUT tm/orders with a phone number value that contains more than 13 characters. It now accepts phone numbers up to 20 characters.

Trips

Partial trip creation (TM-161344)

The tm/trips API now displays a 202 (received but not completed yet) response code for partial trip creation. These are scenarios in which one or more orders cannot be matched due to business logic.

Error message when changing an LTL status (TM-162783)

The PUT /trips/tripNumber/orderId/status endpoint no longer returns a 301 (Moved permanently) error when changing an LTL status.

Parking P&D trips at a door (TM-162853)

The /tm/trips API was creating P&D trips that were already parked at Door 0. This prevented them from being parked at a real door later.

Fixed 404 error for tm/trips/{tripNumber}/assign (TM-163006)

The /assign and /deassign endpoints for /tm/trips were generating a 404 (Not Found) error. This has been fixed for:

  • POST tm/trips/{tripNumber}/assign

  • POST tm/trips/{tripNumber}/deassign

Unassign orders with matching zones (TM-163123)

The TruckMate REST API’s TripControls schema now contains a deassignOrdersFromMatchingTrips control function. It allows you to unassign orders that are already assigned to a trip.

New logic has been added to ensure that when you create a new P&D trip and this control function is set to True, only orders from trips with matching start and end zone are unassigned. Previously, inactive trips with different start and end zones were being matched.

When the order is already assigned to another uncompleted trip with matching start and end zones (for example, coming out of the same terminal), the following logic applies:

  • If the control flag is True and the other matching trip is not active, the order is removed from the previous trip and added to the new one.

  • If the control flag is True and the other matching trip is active, a 202 (Partially Created) response is returned.

  • If the control flag is False, the order is added to the new trip without removing the order from the previous trip.