Copyright IBM Corporation and GTD Solution Inc. 2020
Note: The Notifications feature is currently in Beta to better support changes from customer feedback. The current functions and APIs are subject to change.
Modern supply chain organizations must decipher conflicting and complementary data from multiple sources every hour of every day. Determining what is important can make all the difference. You need to identify deviations and exceptions and act quickly. The TradeLens Notifications function can sift through that data and advise you of a variety of conditions, such as carrier release, customs release, terminal release, customs hold, and more. Notifications can be delivered on the Shipment Manager UI, by email, or by webhook.
You can use either the Shipment Manager UI or the APIs to configure Notifications. A user that is part of an organization can set up their user profile with email and/or webhook preferences for delivery of the notifications. The user can then configure their notifications to trigger on certain notification types and locations, and the user can choose the delivery method of Shipment Manager, Login Email, nickname for email in User Profile, or Webhook specified in User Profile. In the example below, we will use the UI to configure and view the notifications. If you are interested in using the APIs, they can be found in the User Preferences API and the Notifications and Alerts API. See the API User Guide for more information on using the TradeLens APIs.
The Shipment Manager (UI) is the default delivery method. If you want to view your notifications on the Shipment Manager only and not use the email or webhook options, then you do not need to set up a User Profile and you can skip to the Notifications Settings section in the example below. Notifications on the Shipment Manager will be available for 60 days.
The Login Email address that is associated with your TradeLens userid is also used as the default email address for the email delivery method. If you want to view your notifications by email and you want to have them delivered to the email address associated with your userid, then you do not need to set up a User Profile and you can skip to the Notifications Settings section in the example below.
In this example, we will use the Shipment Manager UI to set up our User Profile and configure our Notifications Settings. We will then view our notifications using the Shipment Manager, email, and a webhook. As mentioned previously, the equivalent functions are available through the User Preferences API and Notifications and Alerts API.
First we set up our user profile, which is where we specify the email address and/or webhook that we want to use for our userid. From the UI, click Account and then click User Profile.
This will bring up the User Profile section.
We will set up an email preference first. The Name field is prefilled with the first part of the email address that is associated to our signed-in userid; we can change this if desired. We leave English as the Preferred Notification Language (note that English is the only supported language at this time for notifications), fill in an Email address, and fill in a Nickname that will be used later when we set up the Notifications Settings section. Since the nickname will be used later to select the type of notification, we will indicate that this is for email by giving it an appropriate name like name-email (you can use any text for the nickname).
When we click Save, we get a message that our profile has been saved. At this point, TradeLens sends a verification code to the email address we specified in our profile.
When we click OK to close the dialog box, we see an exclamation mark in the Email field. If we hover on the exclamation mark, we see a message that the Email has not been verified yet.
We check our email and find the verification code. Then we click on the exclamation point in the User Profile section and enter our verification code. We then click Verify to complete our email configuration.
We now see that a checkmark has replaced the exclamation mark in the Email field, indicating that the verification code was accepted.
Setting up a webhook in the User Profile is similar, but there is no verification step. We just need to specify a valid webhook URL. See the Event Subscriptions section in the API User Guide for more information on webhooks. After we enter our webhook URL, we click Save.
The User Profile section above is something a user can set up one time. TradeLens stores the user's webhook and/or email information to enable the delivery of the notifications.
Now we will set up the specific notifications that we are interested in receiving. From the UI, click Notifications and then click Notifications Settings.
The Notifications Settings section allows you to select several Notification Types including: Carrier Release, Customs Release, Terminal Release, Customs Hold, Container Ready For Pickup, Booking Confirmation, Verify Copy, Sea Waybill, Bill of Lading, House Bill of Lading, Importers Security Filing, Container Discharged From Vessel At Destination, Container Full Release At Destination. You can also select from multiple Country and Ports (UN/LOCODE) Locations. Once you have selected either Country or Ports, you can enter 2 or more characters into the field which will enable type-ahead and additional selections will appear that match the characters entered. The Delivery Method can be Login Email, Shipment Manager (default), the Nickname specified for the email (if specified in the User Profile), or Webhook (if specified in the User Profile).
In our example, we will select Carrier Release for the Notification Types and USRLH as the Port (UN/LOCODE) for the Locations. For illustration purposes, we will select several options for Delivery Method: Shipment Mananger, our Nickname for our email, and our Webhook.
When we click Add Notification, we see that it has been added to a table of existing notifications and that the Notifications Settings input fields have been reset to allow additional notifications to be specified if desired.
You can add more notifications, delete notifications, or edit notifications. Clicking Edit allows you to also enable/disable a notification. We will close the window by clicking the "x" since we do not want to make any changes.
Receive a Notification
Now we will send a carrierRelease event (from a carrier organization) using the POST .../genericEvents/carrierRelease - Carrier release Event Publish API to an existing consignment with the location USRLH. The user in our example that set up the notification is a member of an organization that has visibility to the consignment, so the user will see the notification on the Shipment Manager UI, receive an email with the notification, and receive the notification on the webhook.
To view the notification on the Shipment Manager, click on Notifications and then click on Notifications Inbox.
When a new notification is received on the Shipment Manager, a message window will appear for a short time indicating there is a new notification. There are several tabs to help organize the notifications. From the All tab, and you can easily mark notifications as read/unread or flagged/unflagged, or you can delete them. Relevant options are available from the other tabs, depending on the state of the notification. If you click on one of the References links, it will take you to the consignment on the Shipment Manager and the notification will be marked as read if you return to the Notifications Inbox.
Here is the email that we received from the TradeLens Notifications feature with additional details for the carrier release event.
Here is the webhook payload that we received from the TradeLens Notifications feature with additional details for the carrier release event.