Publishing and Verifying Events

Copyright IBM Corporation and Maersk GTD Inc. 2018, 2019

Note: See the Data Sharing Specification section for details on the TradeLens data sharing model. It describes the data that various participants provide to the platform, how that data is shared with others, and the data access for the participants.

Introduction

This section describes how you, as a technical representative for a Shipping Line, Freight Forwarder, Customs Broker, or other logistics industry partner, can use the TradeLens platform APIs to publish events. Platform is one application that runs on top of the TradeLens solution and integrates trade data from industry partners onto a common, secure business network.

Swagger APIs enable you to integrate your systems with TradeLens. Review the API Documentation topic if necessary. The platform Event Publish API accepts shipping event data from publishers. The events can be distributed by the platform to subscribers through the platform Subscription API that enables subscribers to receive notification of events that occur across the shipping lifecycle. See section Setting Up Subscriptions for more details on subscriptions.

Authorization Prerequisites

To work with the TradeLens platform, you will need an ID and a system ID (if you want to use your systems to call the APIs). The ID is the one that was used as part of the TradeLens onboarding and provisioning process. A bearer token is required when calling the APIs from a system user (program code). See section Authentication and Token Generation for API usage for details on the authorization and configuration needed to use the APIs from your system code. For more information on the APIs and using Swagger, see the API Documentation section.

Publishing Events – Event Publish API

Use the following steps to start publishing events to the TradeLens platform.

  1. Review the API Documentation topic if necessary: Become familiar with Swagger, authentication, and how to use the APIs.

  2. Publish an event: Call the APIs from Swagger or your client code (using your system user and token) to publish events to the platform.

  3. View your published event: You can view your events, published from either Swagger or your client code, in the Shipment Manager UI. You will be asked to log in with your ID and password. Once authenticated, you will be able to view your consignments and consignments that have been shared with your organization.

In this example, we will publish 3 events using the Event Publish API and then use the Shipment Manager UI to verify the events. We will publish a POST .../consignments - Start consignment tracking (E468), a POST .../transportEquipment - Start transport equipment tracking (E278), and a POST .../cargoSurveyDone - Cargo Survey done (E328). Typically your system code would make the API calls to the platform (passing the bearer token), but we will show the calls using Swagger to illustrate the flow. Note that the images might differ slightly from what you see, based on your level of TradeLens. Also note that the Carrier will normally be the organization that issues the start for the consignment and the transport equipment, but we will be submitting these events for illustration purposes.

Submit the Events

Start consignment tracking

We use a unique carrierBookingNumber for the consignment.

Publishing and Verifying Events1c

Check for a "success" Response:

Publishing and Verifying Events2c

Start transport equipment tracking

We use the carrierBookingNumber from the consignment to associate the transport equipment with the consignment.

Publishing and Verifying Events3c

Check for a "success" Response:

Publishing and Verifying Events4c

Cargo Survey Done

Notice for the Cargo Survey Done event, we use the equipmentNumber (the identifier on the actual outside of the container) as the unique identifier. This is the equipmentNumber that we used on the start transport equipment tracking event.

Publishing and Verifying Events5c

Check for a "success" Response:

Publishing and Verifying Events6c

Verifying events using Shipment Manager

There are different ways to verify that your events have been sent to the TradeLens platform. You can set up a subscription and receive the event notifications to your webhook, see Setting Up Subscriptions. You can use the Query API, see API Documentation. You can also use the Shipment Manager UI to view your event details. We will use the Shipment Manager UI in this example.

View the consignment

We will use the filter to find our consignment by Carrier Booking Number. Publishing and Verifying Events7f

View the transport equipment

We can view the transport equipment information by clicking on the consignment card (click in the box area for the consignment, or click on Full Details). Publishing and Verifying Events8f

View the events

Click on the transport equipment card (click in the box area for the transport equipment). With the All Event Types filter, we can see the events for the transport equipment.

Publishing and Verifying Events9f