Copyright IBM Corporation and GTD Solution Inc. 2018, 2020
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 Documentation), 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 a Carrier 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 Logout 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.
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 the arrow near the bottom center to expand the consignment card. You can see booking data (if available) displayed on the consignment card.
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.
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.
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.
If you click on a 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. Notice that there are links at the top to return to the consignment list or the transport equipment list. Depending on what type of events are present, the Shipment Manager UI will preselect a filter. In this example, there are actual transport events so the Current Progress filter is preselected. We will discuss these filters in more detail later. When we look at the events for the transport equipment, it can have many events that show the movement for the transport equipment and consignment. 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). Here is a partial display of the Current Progress for a transport equipment.
You can click on any of the events to see more details about that specific event. For example, here are the details for an "Actual Gate In" event that shows on the UI as "Gated In" and the fullStatus is set to Full:
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||latest Planned, up to latest Actual or latest Estimated without an Actual for current progress leg - associated events are grouped by their planned, estimated, and actual events if available. Note that Planned events for a transportation leg will not appear until at least an Estimated or an Actual event is available for that leg||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 Sea Waybill for a consignment.
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.
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.
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 and DESTINATION_3PL. 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 Subscription Management. From the Subscription Management 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.