Skip to content

Actionable Doc Flows

Copyright IBM Corporation and Maersk GTD Inc. 2018, 2019

Note: The actionable doc flows feature is currently in Beta to better support changes from customer feedback. The current functions and APIs are subject to change.

Actionable doc flows in TradeLens will offer the following benefits:

  • Simplified transmission of digitized Shipping Instructions through APIs
  • Managed document states and versioning
  • Guaranteed Blockchain immutability, traceability, and auditability of documents
  • Accelerated submission of Shipping Instructions to creation of Final Bill of Lading
  • Rapid sharing of documents with all permissioned parties

Note: TradeLens will deliver the actionable doc flows function in several stages and the documentation will be updated as additional function is delivered.

In the section below, we will show an example of a Shipping Instructions to Bill of Lading flow. There will be additional flows in the future. Documents for actionable doc flows should only be submitted through the APIs. The Shipment Manager UI can be used to view the documents, but the UI can not be used to upload documents for actionable doc flows. TradeLens sends notification of the events using the subscription function.

Shipping Instructions to Bill Of Lading Example

The Shipper (Requestor) will submit the Shipping Instructions and the Ocean Carrier will submit the Sea Waybill (Bill of Lading). We will also show the Verify Copy document that helps to facilitate the Shipping Instructions to final Bill of Lading.

High-Level Overview

  1. Ocean Carrier sets up organization subscription to be notified of Shipping Instructions and Verify Copy document events. Note that the Carrier (and Requestor) might subscribe to other document events or other non-document events.
  2. Shipper (Requestor) sets up organization subscription to be notified of Verify Copy and Bill of Lading document events.
  3. Shipper submits Shipping Instructions document using PUT ...​/actionableDocFlows​/shippingInstruction - Shipping Instructions actionable doc flow.
  4. TradeLens inspects Shipping Instructions structured document, finds the required fields, and does further processing:
    • Creates the consignment if it does not already exist.
    • Adds the trade parties to the consignment (Carrier as OCEAN_CARRIER, Shipper/Requestor as REQUEST_PARTY).
    • Sends notification to the Carrier and Requestor using the subscriptions.
  5. Carrier retrieves Shipping Instructions document using the document ID received in the subscription and processes the information.
  6. Carrier submits a Verify Copy document for the Requestor to review using PUT ...​/actionableDocFlows​/verifyCopy - Verify Copy actionable doc flow. Notification of the event is sent to the subscriptions.
  7. Requestor can update the Verify Copy document and submit it for the Carrier to review using PUT ...​/actionableDocFlows​/verifyCopy - Verify Copy actionable doc flow. Notification of the event is sent to the subscriptions.
  8. Steps 6 and 7 can repeat until the Verify Copy is accepted by both parties.
  9. Carrier submits Sea Waybill document using PUT ...​/actionableDocFlows​/billOfLading - Bill of Lading actionable doc flow.
  10. TradeLens inspects Sea Waybill structured document, finds the required fields, and does further processing:
    • Updates the consignment with Bill of Lading number, creates the transport equipment using the transport equipment id(s).
    • Sends notification to the Carrier and Requestor using the subscriptions.
  11. Shipper retrieves Sea Waybill document using the document ID received in the subscription and processes the information.
  12. At the end of the flow, the Shipper, Carrier, and any other added parties can view the consignment, any transport equipment, and any documents (according to their specific permissions).

Detailed Flow

Setting up Subscriptions (steps 1 and 2)

The Ocean Carrier and Shipper (Requestor) can use existing subscriptions and look for the document events for Shipping Instructions, Verify Copy, and Bill Of Lading. They could also set up a new subscription that just receives all document events, or specific document events using the docEventsFilter. An organization subscription can be set up through the UI or through the API POST .../subscriptions​/org - Create a subscription for your organization. See the Setting Up Subscriptions section for more information on subscriptions.

We will use the UI to create the organization subscriptions for the Requestor and Carrier. Since the process is the same (except for possibly the document event types we select), we will just show the screen images for the Requestor organization; the Carrier would follow the same process. We click on Subscription Management.

Actionable Flows1a

We click on Create Subscriptions and then choose Organization Subscriptions.

Actionable Flows3a

We fill in the Name, URI, and optional Shared Secret (click on the implementation notes icon in the UI or see the API description for details).

Actionable Flows5a

Then we click within the Org Event Types field so we can select the document events for our subscription.

Actionable Flows7a

For the Requestor, we will select the Verify Copy and Sea Waybill document events. Note: We might also want to select Shipping Instructions (or additional document types) so we can be notified of any document action that is taken on the Shipping Instructions document that we submit. In our simple example, we will not specify document actions (optional) for our document event subscription, so we will be notified of all actions by default.

Actionable Flows9b

We scroll to the bottom of the selection and click on Use Selected Event Types

Actionable Flows11a

We see the documentEvents filter is set for our document types.

Actionable Flows13a

We click on Create Subscription and once the process completes, we see our subscription has been added to the Subscription Management section.

Actionable Flows15a

As discussed at the beginning of this section, the process for setting up the subscription for the Carrier organization is the same, except for possibly the document event types that are selected.

Shipper (Requestor) submits Shipping Instructions (step 3)

The Shipper (Requestor) submits their Shipping Instructions structured (JSON) document using the PUT ...​/actionableDocFlows​/shippingInstruction - Shipping Instructions actionable doc flow API. But first, the Shipper must know the current schema (template) id and version for the Shipping Instructions document type so it can be provided as input to the API, along with the actual Shipping Instructions document. The current platform schema can be determined by using the GET ...​/documentSchema API. To get the current platform version of the Shipping Instructions document, we specify "gtd-ibm-authority" as the organizationId and filter by name and type. For example, "SHIPPING_INSTRUCTIONS" is a platform defined document type. Then we can find the "ACTIVE" schema in the response and make note of the version and id. We could then call the GET ...​/documentSchema​/{documentSchemaId} API using the ID and Version to retrieve just that schema so we could use it to build the Shipping Instructions document.

We will show how to get the Active platform schema for the Shipping Instructions document and how we submit the Shipping Instructions structured document to the actionableDocFlows API. The process is the same for the other document types in our example (Verify Copy and Sea Waybill).

First we use GET .../documentSchema to find the latest Active platform schema and make note of the ID and the Version.

Actionable Flows17a

In our example, the ID is 0082a0d42674410d9d74f5c532e927fe and the Version is 18.

Actionable Flows18a

Next, we use PUT ...​/actionableDocFlows​/shippingInstruction to submit the Shipping Instructions document using the schema information for validation.

Actionable Flows19a

The response contains a flowTransactionId that we can use to check the status of the operation to ensure that it completed all of the functions.

Actionable Flows21a

TradeLens processes Shipping Instructions (step 4)

The Shipping Instructions document is inspected by TradeLens and automated processing occurs, based on some of the information in the document. The consignment is created if it does not already exist. The trade parties are added to the consignment (Carrier as OCEAN_CARRIER, Shipper/Requestor as REQUEST_PARTY). Notification is sent to the Carrier and Requestor using the TradeLens subscriptions.

We use the flowTransactionId in the previous step to check the status. We can see that the consignment has been created and the document has been uploaded. TradeLens also adds the Ocean Carrier party, identified by the SCAC code (OceanCarrierCode in the Shipping Instructions document), to the consignment.

Actionable Flows23a

Actionable Flows25a

From the Requestor's view on the UI, we can see the events for the creation of the consignment and the submission of the document. We can also see the document is available in the Documents tab.

Actionable Flows29a

Actionable Flows31a

Carrier retrieves Shipping Instructions (step 5)

The Carrier can retrieve the Shipping Instructions document using the document ID from their subscription. The Carrier can also see the document using the UI.

Here is an example showing what the Carrier receives on their subscription.

Actionable Flows33a

The Carrier can retrieve the Shipping Instructions document by documentId.

Actionable Flows35a

Actionable Flows37a

The Carrier can also see the document through the UI, and download the document by clicking the download icon next to the document.

Actionable Flows39a

Actionable Flows41a

Carrier submits Verify Copy (step 6)

The Verify Copy document is a draft copy of the Sea Waybill. The Carrier submits the Verify Copy and the Shipper (Requestor) can add comments to the document and submit it back to the Carrier so that any additional changes can be made. This process continues until the parties are done editing the document details and then the Carrier will submit the actual Sea Waybill document.

The Carrier follows the same process we have discussed before to get the schema ID and version for the Active platform schema for the Verify Copy document type. Then the Carrier submits the Verify Copy document using the PUT ...​/actionableDocFlows​/verifyCopy API.

Actionable Flows43a

Actionable Flows45a

The Carrier can check the flowTransactionId like we have discussed before to ensure that the upload is complete.

Requestor updates Verify Copy (step 7)

The Shipper (Requestor) can update the Verify Copy document if needed and submit the document. The document can be retrieved using the documentId on the Requestor's subscription. The Requestor could then use the PUT ...​/actionableDocFlows​/verifyCopy API to resubmit the document for the Carrier to review. The UI can be used to view the documents, but the UI can not be used to upload documents for actionable doc flows. After the Requestor submits the updated document through the API, we can see on the UI that the version number has been updated.

Actionable Flows49a

Verify Copy process continues (step 8)

The Verify Copy can be submitted multiple times by the Carrier and Requestor until all updates are complete.

Carrier submits Sea Waybill (step 9)

After the Verify Copy process is complete, the Carrier follows the same process we have discussed before to get the schema ID and version for the Active platform schema for the Sea Waybill document type. Then the Carrier submits the Sea Waybill document using the PUT ...​/actionableDocFlows​/billOfLading API.

Actionable Flows51a

Actionable Flows53a

The Carrier can check the flowTransactionId like we have discussed before to ensure that the upload is complete.

TradeLens processes Sea Waybill (step 10)

The Sea Waybill document is inspected by TradeLens and automated processing occurs, based on some of the information in the document. The consignment is updated with the Bill of Lading number, and the transport equipment is created and added to the consignment. Notification is sent to the Requestor using the subscription service.

The Carrier can use the flowTransactionId in the previous step to check the status. We can see that the consignment has been updated with the Bill of Lading and the document has been uploaded.

Actionable Flows55a

Shipper retrieves Sea Waybill (step 11)

The Shipper (Requestor) retrieves the Sea Waybill document using the documentId received in the subscription and processes the information. The Requestor can also see the document using the UI.

Conclusion - Shipper and Carrier can view results (step 12)

At the end of the flow, the Shipper, Carrier, and any other added parties can view the consignment, any transport equipment, and any documents (according to their specific permissions). We will show some views from the UI for the Requestor.

Actionable Flows57b

Actionable Flows59a

Actionable Flows61a