Notifications and Alerts
Copyright IBM Corporation and GTD Solution Inc. 2020
Note: The Notifications and Alerts 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 and Alerts 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 through a webhook or email.
The Notifications and Alerts function is made up of two parts: User Preferences/Profile and Notifications and Alerts. A user that is part of an organization can set up their user profile with webhook and/or email preferences for delivery of the notifications. The user can then configure their notifications to trigger on certain notification types and locations. The user can choose the delivery method (either webhook or email) for the notifications.
You can use either the UI or APIs to configure the User Preferences/Profile and the Notifications and Alerts. In this example, we will use the UI. 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.
First we set up our user profile, which is where we specify the email address (or webhook) that we want to use for our userid. From the UI, click Accounts and then click User Profile.
This will bring up the User Profile section.
We will set up an email preference first. We fill in a Name, select English as the Preferred National Language (note that English is the only supported language at this time for the notification), fill in an Email address, and fill in a Nickname that will be used later when we set up the Notification and Alert 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, but 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.
We click on the exclamation point in the User Profile section and enter our verification code, and 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 and alerts.
Alerts & Notifications
Now we will set up the specific notifications and alerts that we are interested in receiving. From the UI, click Accounts and then click Alerts and Notifications.
The Alerts & Notifications 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 will be either Webhook or the Nickname specified in the User Profile.
In our example, we will select Carrier Release for the Notification Types, USRLH as the Port (UN/LOCODE) for the Locations, and our email Nickname as the Delivery Method.
When we click Add Notification, we see that it has been added to a table of existing notifications.
You can add more notifications, delete notifications, or edit notifications. Clicking Edit allows you to also enable/disable a notification.
We will edit our existing notification and add the webhook as well so we can see how the notification will look when it is sent to a webhook. After we have added the webhook, we click Save Settings.
Receive a Notification/Alert
Now we will send a carrierRelease event using the POST .../genericEvents/carrierRelease - Carrier release Event Publish API to an existing consignment with the location USRLH. Our organization (which our user is a member of) has visibility to the consignment, so the user will receive an email notification to alert them about the carrier release for location USRHL.
Here is the email that we received from the TradeLens Notifications and Alerts feature with additional details for the carrier release event. Currently, the link included in the email will bring you to the UI for your organization if you are already logged onto TradeLens.
Here is the webhook payload that we received from the TradeLens Notifications and Alerts feature with additional details for the carrier release event. Currently, the link included in the email will bring you to the UI for your organization if you are already logged onto TradeLens.