Copyright IBM Corporation and GTD Solution Inc. 2018, 2021
The Shipment Manager UI is the main end user UI for TradeLens and allows you to visualize your shipments, consignments, and transport equipment (TE). You can also work with documents associated with each trade object (shipment, consignment, TE). You can search and filter using different criteria. You can drill down into each shipment or consignment for which you have permission, and visualize all the transport equipment (containers) involved. You can also view the list of events for a consignment or a TE, and for TE you can filter by Current Progress, Transport Plan, Admin, and Document events.
Shipment Manager UI URLs
The Shipment Manager UI URLs for the Sandbox and Production zones are shown below.
Note: If you have been onboarded onto a different stack than "platform", replace "platform" with your stack name, for example "maersk", in the URLs.
Using the Shipment Manager
In this section, we will go through some of the features of the Shipment Manager UI. We will discuss:
- Viewing Shipments, Consignments, and Transport Equipment
- Filtering to limit the search results
- User Management
- Subscription Management
Viewing Shipments, Consignments, and Transport Equipment
The Shipment Manager UI allows you to view information about shipments and consignments that you have started, or shipments and consignments that have been shared with you. The shipments and consignments that are visible from the Shipment Manager UI, or by the consignment queries in the Trade Object API (API User Guide), are based on the organization ID of the user.
You will see consignments if at least one of the following is true:
The sender of the Start Consignment Tracking (POST .../consignments) was from your org
A Consignment Visibility Added (POST .../consignments/partyAdded) event was submitted to share visibility of a consignment with your org
Your org is a port, country, or terminal that was derived from the transport plan (planned events only) for the transport equipment, or from the transport plan for the consignment once it has associated transport equipment.
Note: A Consignment Visibility Added (POST .../consignments/partyAdded) also provides access to documents for the consignment based on the partyRole. See the TradeLens Data Sharing Specification topic, and the Permissions section in the Document Sharing section for details on document permissions.
You will see shipments if at least one of the following is true:
The sender of the Shipment Created (POST .../shipments) was from your org
A Shipment Party Added (POST .../shipments/partyAdded) event was submitted to share visibility of a shipment with your org
Note: A Shipment Party Added (POST .../shipments/partyAdded) also provides access to documents for the shipment based on the partyRole. See the TradeLens Data Sharing Specification topic, and the Permissions section in the Document Sharing section for details on document permissions.
First log into the Shipment Manager UI. You can find the URL information in the Shipment Manager UI URLs section above.
If your id is an Org Admin, you will see a choice to "Continue as an Organization Admin of organization" for the organizations where you are an Admin. As an Org Admin, you will have access to several Management sections from the Account menu.
When you first log in, you will see a home page that shows the 5 most recently added shipments and consignments. Depending on your organization's participation type, the very top of the home page will show some boxes (quick search filters) with summary information and the number of items for each category. For example, the following image shows what an organization might see. You can click on the shipments box or the consignments box to see the trade objects represented by the filter. If you click on a filter box, you can expand the Search area to see how the results were filtered and add additional search filters if desired.
If your organization's participant type is Cargo Interest or 3PL Agent, your home page will look like the next image. You can click on any box to display the filtered search results. Most of the boxes are self explanatory from their descriptions, but we will discuss a few in more detail:
- On the Water: All the transport equipment (TE) for this consignment are on the vessel. Every TE associated with this consignment has received an actualLoadedOnVessel event, and none have received an actualDischargeFromVessel event. This indicator is only for the ocean journey and does not apply to barges.
- Transshipment: Shows consignments where the TE are being moved between vessels mid-journey. There is more than one vehicleId among all vesselArrival and vesselDeparture events in the latest transport plan sent to the consignment and the estimated and actual events sent to the TE.
- Change in Vessel Arrival n Days: Shows consignments where the vessel arrival has changed by n days from the transport plan at the time of the “Gate In” event at the origin. The plannedVesselArrival (at the entry port) is updated when a new plannedVesselArrival or estimatedVesselArrival event is submitted. The new value is calculated using the transport plan at the time of the “Gate In” event at the origin. Once the vessel actually arrives, the consignment will no longer appear in the box.
- Transport Plan Update (<72 Hours): Shows consignments where the transport plan has changed within the last 72 hours.
You can also scroll to the bottom of the page, below the 5 most recently added shipments and consignments, and click the View All button to see all of the consignments.
The Account menu on the left side will show you the logged-in ID (email and organization name). The Sign Out option is located below the Account menu item.
You will see all of the consignments that you are authorized to view. Notice there is a cards view and a list ivew icon that allows you to toggle from the card view to a more condensed list view. If you have done a search, or clicked on Consignments on the left menu, and the list of consignments returned is within limits, you will also have the option to Export Results To CSV that saves the search results with additional detail (including Transport Equipment) as a comma separated value file.
We will cover the Search options in the Search section below. For now, we will take a look at one of the consignments to see what information is available.
You will see some summary information for the consignment from the main display.
You can see any additional data by clicking on the consignment. We will go into more detail in later sections below, but for now we will click on the consignment and then click on Full Details to see an expanded section with more information for the consignment.
Shipments are viewed in the same way as consignments and transport equipment. For more information on shipments, see the Shipments section in the Platform Event Model section. Here is an example of a shipment.
If the shipment has been associated with a consignment(s), you can view the consignment(s) and any transport equipment associated with the consignment(s) by clicking the Consignments button.
Consignment level events can be seen by clicking on the Events button, or by clicking within the consignment card and then selecting the Events tab. Here is an example that shows a partial display for the Latest Events for All Event Types. Note that with the All Event Types view, the events are sorted by eventSubmissionTime.
Note that additional details for each event can be displayed by clicking on the event. A slide-out will appear with more information. The event details are available for all events, but we will not show it for all images below.
The Transport Plan button will show the Planned events for the consignment. Only Planned events are shown in the Transport Plan, there are no Estimated or Actual events shown. If there is more than one Transport Plan, you will see the Current Version (the most recent one) followed by any other versions. You can expand the section to view the Planned events. Note that with the Transport Plan view, the events are sorted by eventOccurrenceTime. Here is a partial display of the Current Version of the Transport Plan.
The Admin button will show the Admin events for the consignment.
The Document button will show the Document events for the consignment.
Transport Equipment Details
If there is transport equipment information available, you can click on the Containers button, or you can click within the consignment card and then select the Containers tab to see more details about the transport equipment. You will notice the Shipment Manager indicates the progress events for the transport equipment on the transport equipment card. The example below is for a completed consignment, so the progress shows that the transport equipment has arrived at the destination. Notice that you can select several different tabs: Events, Containers, and Documents. Each of these will give you more information about the consignment. In the example below, the transport equipment each have a Dangerous Goods Request document that was uploaded to the TE. This is visually indicated by the triangle warning icon. If you hover over the icon in the UI, it displays a message regarding dangerous cargo.
Event Priority Matrix
An Event Priority (eventPriority) is applied by TradeLens to Transport Events (Estimated and Actual) and to Generic Events. This allows TradeLens to group events of the same type that are happening at the same location and display (or return) the highest priority event that is available at that time. This ensures that the most reliable data for milestone events is provided, based on who the provider of the data is and the availability of the events at the time when the events are sent to subscription webhooks or when they are queried through the Trade Object APIs or displayed on the Current Progress view of the UI.
For example, assuming the same location is used and the fullStatus is the same (Full or Empty): If an Ocean Carrier publishes an Actual Gate In, the event would have the Event Priority set to 5. If a Terminal Operator publishes an Actual Gate In, the Event Priority would be set to 1. If a Truck Operator publishes an Actual Gate In, the Event Priority would be set to 3. The highest priority event from the Ocean Carrier will be displayed in the Current Progress view of the UI for the Transport Equipment. The additional sources for the events from the Terminal Operator and Truck Operator are hidden, but are available by clicking the Additional Sources link in the Current Progress view.
To view the priority matrix, you can download the Event_Priority_Matrix.xlsx spreadsheet. The spreadsheet has two tabs: The first one has the events broken down by the same event type/category and the second tab is the consolidated list for all events.
In the example image below, we click on the transport equipment card (click in the box for a specific transport equipment), it will show additional information about the transport equipment, including the events submitted for the transport equipment. Depending on what type of events are present, the Shipment Manager UI will preselect a filter. In the following image, there are actual transport events so the Current Progress filter is preselected. The most current event is at the top, so scroll to the bottom if you want to follow the cargo from start (bottom) to finish (top). The next image is a partial display of the Current Progress for a transport equipment. The Current Progress view will also group the same type of events, in a left to right order, with Actual events taking precedence, followed by Estimated events, followed by Planned events.
The Event Priority for an event can be found by clicking on the event and the UI will provide additional information in the slide-out.
The filter within the transport equipment view allows you to filter by: Current Progress, Transport Plan, Admin, Document, and All Event Types. See the Platform Event Model section for more details on the three types of transport events (Planned, Estimated, and Actual). The table below shows a summary of the filter combinations and the event types that will be displayed.
Note: Since Planned events can be directed at a consignment or specifically to a transport equipment, you can see Planned events sent to the consignment at the consignment Transport Plan level. The consignment level planned events are also visible on the transport equipment Transport Plan unless the transport equipment has had Planned events (as part of a transport plan) sent to the specific transport equipment (using a transport equipment identifier), in which case, the Transport Plan(s) for the transport equipment will be the Plan(s) sent to the transport equipment. Any later Plan(s) sent at the consignment level will be visible on the consignment level but will not overwrite the Plan(s) that were sent to the transport equipment.
Table 1 - Current Progress/Transport Plan/Admin/Document/All Event Types with Latest Events/All Events
|Current Progress||grouped by location - highest priority Actual and/or Estimated, latest Planned||n/a|
|Transport Plan||only Planned events (no Estimated or Actuals), grouped by Current Version of transport plan and any previous versions (Version 1, Version 2, etc.) of transport plan||n/a|
|Admin||latest Transport Equipment and Consignment events||all Transport Equipment and Consignment events|
|Document||latest version of each Document event||all versions of each Document event|
|All Event Types||latest Planned, latest Estimated, all Actuals, latest other non-tp events||all events submitted|
Shipments, consignments, and transport equipment can have documents. We will take a look at documents for a consignment. The process is very similar for shipments and transport equipment. If you have authority to view a document and want to see an image of the document, one method is to click on the document event and then click on the link for the document in the event details. The image might be displayed in a browser pop-up (for example if it is a pdf document), so make sure that your browser is allowing pop-ups. For example, here is a sample Booking Confirmation for a consignment. If you click the Booking Confirmation submitted event, you could then click on the BOOKING_CONFIRMATION document in the slide-out to view the document.
You can click the Documents button from the consignment card on the main page of the Shipment Manager UI, or click within the consignment card and then select the Documents tab to see the documents. If you are authorized to view a document, you can click on the document link to see a preview or to download the document.
For more information about documents, see the topic Document Sharing.
Search is available to help you narrow down your consignment view, or to look for specific consignments or transport equipment. The basic Search option can be used for several different types of identifiers. You can click the drop down to select an identifier type, enter data in the search box, and click the Search button.
Some search fields (basic and advanced) will add a wildcard automatically at the end of the field. These six fields allow you to enter the first part of a value and then search will add a wildcard to the end: Booking Number (Carrier Booking Number), Bill of Lading Number, Origin, Destination, Consignment Reference Number, and Transport Equipment Reference.
If you click on Consignment Search or Shipment Search, you will see additional search filters. Here are a few examples using some of the advanced search fields. Destination can be used to search for consignments for a specific destination port.
If you want to search for all ports within a country, you can use the 2 character country code (as noted previously, Origin and Destination are two fields that a wildcard will automatically be added to the end for search). For example:
The Created By filter on the UI will display a list of organization names that have created consignments that your organization has visibility to see. You can use the filter to select specific organization names and view only those consignments.
Consignment Hierarchy view
If your consignment is part of a consignment hierarchy (see the Consignment Hierarchy section for more details), there will be a Linked Consignments tab in the details view of the consignment when you click within the consignment card. Any linked consignments will be relative to the level of your consignment in the hierarchy. For example, there might be child consignments if your consignment is a parent, or parent consignments if your consignment is a child. If the owner of the linked consignment has granted visibility to the consignment to your organization, then you will be able to view the consignment; otherwise you will know that it exists, but it will be grayed out and the details will not be visible.
Here is an example where a freight forwarder organization has created two parent consignments with carrier booking numbers (CBN) CBN1TestFFWD and CBN2TestFFWD. An ocean carrier has created a consignment with CBN3TestCarrier. Then the freight forwarder organization has subcontracted the ocean carrier's consignment to each of the freight forwarder consignments. So we have two parent consignments (freight forwarder) that are connected (subcontracted) to a child consignment (ocean carrier).
Since the owners of the consignments have not granted visibility yet to their consignment(s), the details for the linked consignment(s) will not be visible to the other organizations in the hierarchy. Here is the view from the freight forwarder.
When we click within the consignment card to see the details for one of the consignments, we will see the Linked Consignments tab.
Since the freight forwarder organization has not been granted visibility yet, the child consignment of the ocean carrier will be grayed out.
In our example, the ocean carrier adds the freight forwarder to the ocean carrier's consignment with the roles of ORIGIN_3PL_AGENT and DESTINATION_3PL_AGENT. This now gives the freight forwarder visibility to the subcontracted (child) consignment CBN3TestCarrier. The consignment will be visible from the main view for the freight forwarder.
The subcontracted consignment will also be visible from the Linked Consignments tab.
If you are an Organization Admin and have signed in as an admin, you can click Account, then select User Management. As an Org Admin, you can add, edit, or delete users for your organization. These users can be human users or system users. Human users can be granted Admin authority or left as a regular user. System users are used for "code" that will interact with the TradeLens APIs. See section Authentication and Token Generation for API usage for more details.
Notice in the screen images below, you can Edit or Delete users. For human users, an Edit will let you change the Description and change the Administrator setting for the user. If you have added a user as a non-admin, and later want to make them an admin, you should use the Edit button for that user, check the Administrator box and save. To remove Administrator authority from a user, use the Edit button and uncheck the Administrator box and save. For system users, an Edit will let you change the Description. To add a new human or system user, click Add New User.
You can select whether the new user is a System User, or by default it will be created as a Human User. If the user is a Human User, you can check the Administrator box if you want the user to have Org Admin privileges, like the ability to manage (add, edit, delete) users for your organization.
If you are adding a System User, you must enter the entire serviceid, including the "serviceid-" portion, for example "serviceid-4807b3fb-11d9-4304-b3da-8205a77d6f8a". See section Authentication and Token Generation for API usage for more details on ServiceIDs.
Click Add New User to complete the process.
The Subscription Management function is available by clicking on Account, then Subscriptions. From the Subscriptions area, you can view and manage the subscriptions available for your organization.
See section Setting Up Subscriptions for details on how to set up and test subscriptions.
If you are an Organization Admin and have signed in as an admin, you can click Account, then Organization Management. From the Organization Management area, you can view and manage some of the organization's settings.
The Organization Management function is described in section Supply Chain Partner Relationships.
If you are an Organization Admin and have signed in as an admin, you can click Account, then Business Partners. From the Business Partners area, you can search for and manage business parter relationships.
The Business Partners function is described in section Supply Chain Partner Relationships.