Transition to General Availability (GA)

Copyright IBM Corporation and Maersk GTD Inc. 2018, 2019

With the General Availability (GA) release of TradeLens, the platform has made changes to better align with the UN/CEFACT model and make it easier to integrate by reducing the need to keep state for data publishers. For example, carriers can publish a new version of a transport plan without having to indicate what has changed. Also, TradeLens is now specifically differentiating between planned events and estimated events. Finally, the platform has moved in a more RESTful direction by streamlining the URLs, using event names instead of E-numbers, and changing consignments and transport equipment resources so that they can be updated with /PATCH.

This section provides information for current TradeLens network members who need to take action as a result of these changes. This includes publishers (and members that are in progress of building an integration) and subscribers. The intent of this document is to provide network members with information about the changes so they can start the transition process. At the end of this section, you will find an API Refactoring reference document that shows the events, the old APIs, the new APIs, and what event is sent to subscribers.

Summary of changes

  • Transport Plan (TP) events, new Query APIs, new Subscription APIs deployed
  • Consignment, Transport Equipment, Document events, Generic events deployed
  • Document events will now be sent automatically to the platform for document sharing operations

New TP events deployed

See the API Documentation section for more information on using the APIs. Once you are in the Swagger for your zone (Sandbox or Production), select the Event Publish API in the top right Select a spec section.

New Transport Plan APIs are available:

  • Planned events - These are all called "plannedXxxx".  These replace the current planned and estimated events. These now have "transportPlanIssuanceTime8601" indicating that the planned events belong to the same TP; it is used to group planned events that define the TP.

  • Estimated events - These are all called "estimatedXxxx".  This new category of events allow data publishers to submit updated estimated departure, arrival, gate in/out and load/discharge times. The data contracts are identical to the new actual events.

  • Actual events - These are all called "actualXxxx".  The data contracts are essentially identical to the current actual events aside from the new naming convention (see below).

  • Changes to Query service - Will only return the latest transport plan (the events with the latest transportPlanIssuanceTime. If there are no transport plans with that field, it will return the planned events without the field). 

The following changes apply:

  • New URL structure:

    • "/visibility/{version}/{eventType}" becomes "/api/v1/{eventCategory}/{eventName}"

    • {eventCategory} can be "transportEvents", "genericEvents", "consignment", "transportEquipment"

    • for example, /visibility/v1/events/E246 becomes /api/v1/transportEvents/plannedGateIn

  • New naming convention:

    • "shipment" becomes "consignment"

    • "containerTransport" becomes "transportEquipment"

    • "physicalId" becomes "equipmentNumber"

    • "containerType" becomes "equipmentType"

To aid in understanding the mapping of old to new events, the Swagger documentation for the new events includes the associated old event type. For example, "POST /api/v1/transportEvents/actualBargeArrival Actual Barge Arrival (E414)".

New Subscription deployed

See the API Documentation section for more information on using the APIs. Once you are in the Swagger for your zone (Sandbox or Production), select the Subscription API in the top right Select a spec section.

New Subscription APIs are available:

  • Events sent with the old API (/visibility/v1/) will continue to be sent to subscriptions created with the old Subscription API and be available in the output of the old Query APIs.

  • Events sent with the new API (/api/v1/) that have a matching old API will also be sent to subscriptions created with the old Subscription API and be available in the output of the old Query API. They will be modified to look the same as the old events (shipmentId, containerTransportID, physicalId).

  • Some events are brand new and only available in the new API. They will not be sent to subscriptions created with the old Subscription API and not be available in the output of the old Query APIs.

    • All estimated transport events

    • The transport equipment API used to update locations

  • All events will be sent to subscriptions created with the new Subscription API and be available in the output of the new Query API. Old events (/visibility/v1/) will be transformed to look like new events (shipment -> consignment, container -> transportEquipment, physicalID -> equipmentNumber, etc).

Required actions for data publishers and subscribers

Old APIs will remain in Swagger until the end of January 2019. They can be used until the end of February 2019, at which time they will be removed.

In order to receive events with the new naming convention as well as the new event types (estimated events, updates to transportEquipment locations), a new subscription must be set up using the new end points.

Subscriptions created with the new API will have very similar looking event payloads published to them with a few exceptions. - Naming changes per the section above. For example, "shipmentId" will appear as "consignmentId".

Subscriptions created with the new API using a shared secret are slightly different from the old API. The Swagger documentation clarifies this in detail, but the hashing algorithm used to create the signature is being updated from SHA1 to SHA256. This means a change is needed to an existing webhook application, to also use SHA256.

Remaining event types deployed

See the API Documentation section for more information on using the APIs. Once you are in the Swagger for your zone (Sandbox or Production), select the Event Publish API in the top right Select a spec section.

The following new end points are deployed:

Generic events get new URLs and naming convention:

  • New URL structure:

    • "/visibility/{version}/{eventType}" becomes "/api/v1/genericEvents/{eventName}"

    • for example, /visibility/v1/events/E265 becomes /api/v1/genericEvents/vgmSubmitted

  • New naming convention:

    • "shipment" becomes "consignment"

    • "containerTransport" becomes "transportEquipment"

    • "physicalId" becomes "equipmentNumber"

    • "containerType" becomes "equipmentType"

New consignment end point supporting operations with new URL structure and naming convention.

New URL structure: /api/v1/consignments

  • POST /api/v1/consignments replaces E468 (Start Shipment Tracking)

  • PATCH /api/v1/consignments/referenceAdded replaces E422 (Add a Shipment Ref)

  • PATCH /api/v1/consignments/partyAdded replaces E001 (Associated Org Id)

  • PATCH /api/v1/consignments/transportEquipmentAdded replaces E470 (Add container to a shipment) - not used today

You should use the new end point, adhering to the changes above. The PATCH consignments events should be used if information for the consignment is updated.

New transportEquipment end point with new URL structure and naming convention.

New URL structure: /api/v1/transportEquipment

  • POST /api/v1/transportEquipment replaces E278 (Start Container Tracking)

  • PATCH /api/v1/transportEquipment/referenceAdded replaces E469 (Add Container Tracking Reference)

  • PATCH /api/v1/transportEquipment/cargoTypeUpdated replaces E314 (Cargo Type Updated)

  • PATCH /api/v1/transportEquipment/equipmentNumberUpdated replaces E417 (Update Physical Container ID)

  • PATCH /api/v1/transportEquipment/locationsUpdated is new (updates miscellaneous countries/ports)

You should use the new end point adhering to the changes above. The PATCH transportEquipment events should be used if information for the transport equipment is updated.

New partyAdded end point (formerly E001) which is the first step towards the new Permissions Framework 

  • New partyRole field identifying the role (and thus the access level) of the organization that will be associated. This replaces the former visibilityScope which is no longer in the data contract.

  • New partyRef field identifying the carrier's internal representation of the customer. The former orgId field is still available, but represents the customer's organization ID which may not be known by the sender. The partyRef is more flexible as it represents how the sender already refers to the customer. However, the use of partyRef will only work if the sender has uploaded their customer related information which includes partyRef values using the Accounts API.

New Document End Points

The old document events are not present in the new APIs. There is a new Document Sharing API that should be used instead, as documents are uploaded and accessed. The platform will generate events for document actions that were formerly sent as separate events by the user or system code. See the API Documentation section for more information on using the APIs. Once you are in the Swagger for your zone (Sandbox or Production), select the Document Sharing API in the top right Select a spec section.

API Refactoring

You can zoom and scroll to see the full content in the window below. There is also a download link at the bottom of the page for the PDF.
Note: Before downloading and opening documents, ensure that you have antivirus protection per your company policy with the latest virus definitions.

This browser does not support viewing the PDF. Please download the Excel file to view it.

Download the TradeLens_API_Refactoring_mapping.pdf document.