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. This section was updated on 11/15/2019.

The Sea Waybill and Bill of Lading document types are currently supported for the PUT ...​/actionableDocFlows​/billOfLading - Bill of Lading actionable doc flow API.

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 using PUT ...​/actionableDocFlows​/verifyCopy - Verify Copy actionable doc flow for the Requestor to review. Notification of the event is sent to the subscriptions.
  7. The Requestor can use POST ...​/actionableMessageFlows​/docMessages - Performs Document Action to indicate that the Verify Copy is approved or ask for clarification in the Verify Copy document and submit for the Carrier to review using PUT ...​/actionableDocFlows​/verifyCopy - Verify Copy actionable doc flow. Notification of the event is sent to the subscriptions. The Verify Copy document can flow between the Requestor and Carrier until the Requestor approves the document.
  8. Carrier submits Sea Waybill document using PUT ...​/actionableDocFlows​/billOfLading - Bill of Lading actionable doc flow.
  9. 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.
  10. Shipper retrieves Sea Waybill document using the document ID received in the subscription and processes the information.
  11. 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 Account, then click Subscription Management.

Actionable Flows1c Actionable Flows2c

We click on Create Subscriptions and then choose Organization Subscriptions.

Actionable Flows3c

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 Flows19b

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 Flows21b

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 with the GET ...​/flowTransactions​/{flowTransactionId} - Fetch a actionable doc flow transaction API. 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 Flows23b

Actionable Flows25b

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 Flows29b

Actionable Flows31b

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 Flows33b

The Carrier can retrieve the Shipping Instructions document by documentId.

Actionable Flows35b

Actionable Flows37a

The Carrier can also see the document through the UI, and download the document by clicking on the document name and then clicking on the download icon.

Actionable Flows39b

Actionable Flows41b

Carrier submits Verify Copy (step 6)

The Verify Copy document is a draft copy of the Sea Waybill. The Carrier submits the Verify Copy.

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 Flows43b

Actionable Flows45b

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

Requestor and Carrier agree on the Verify Copy (step 7)

The Shipper (Requestor) can review the Verify Copy document from the Carrier and use the POST ...​/actionableMessageFlows​/docMessages - Performs Document Action API to indicate that the Verify Copy is approved. Once the Verify Copy is approved, no other Verify Copy can be submitted by the Carrier or the Shipper (Requestor). Also, once a Verify Copy is approved, then the final Bill of Lading can be issued by the Carrier (as we will see in step 8 of our example). If the Shipper (Requestor) does not approve the Verify Copy, they can update the Verify Copy document and ask for clarification in the Comments section and then submit the Verify Copy using the PUT ...​/actionableDocFlows​/verifyCopy API.

In our example, the Shipper (Requestor) will ask for clarification on the Verify Copy and update the Comments section of the Verify Copy and then use the PUT ...​/actionableDocFlows​/verifyCopy API to submit the document for the Carrier to review. The Carrier will review the document and submit the Verify Copy with the PUT ...​/actionableDocFlows​/verifyCopy API. Then the Shipper (Requestor) will approve the Verify Copy. Since we have already seen how the PUT ...​/actionableDocFlows​/verifyCopy API is used, we will not show these steps again and we will skip to the approval process by the Shipper (Requestor).

The Shipper (Requestor) will now approve the Verify Copy from the Carrier. The POST ...​/actionableMessageFlows​/docMessages API requires several pieces of information. One of them is the document hash that can be obtained from the response header for the docSharing GET ...​/documents​/{documentId}​/content - Fetch document content API. The Shipper can find the docVersion and documentId from their subscription for the Verify Copy document event, or from the UI if they look within the Documents tab for the consignment. We see that the Verify Copy is currently at version 3.

Actionable Flows45b3

We will use the docSharing GET ...​/documents​/{documentId}​/content API to get the document hash from the response header.

Actionable Flows46a1

Actionable Flows46a3

Once the Shipper has the document hash (7A4D1BE4EC0019676C784DF757DE0B9546DB7D80583CEB1E663CDB1B5FFFEB90), the document ID (7cf6f1d0-9d9e-43e7-8ec9-295273e74ee3), the document version (3), and the consignment identifier (in our case the carrierBookingNumber CBNTestAcDocFlowsB7), the Shipper can call the POST ...​/actionableMessageFlows​/docMessages API to approve the Verify Copy document.

Notes:

  • The caller of the Actionable Flows API should check the flowTransactionId with the GET ...​/flowTransactions​/{flowTransactionId} - Fetch a actionable doc flow transaction API to check the status.

  • The caller of the Document Sharing API should check the transactionId with the GET ​/api​/v1​/transactions​/{transactionId} - Fetch a transaction API to check the status.

  • The POST ...​/actionableMessageFlows​/docMessages API has many possible input fields. We have used a very small subset for our example. Review the Swagger description for more details on the API.

Actionable Flows46a5

If we look at all of the events (or all of the document events), we can see that the Verify Copy has been approved. We can also see the first Verify Copy that was submitted by the Carrier, the clarification Verify Copy submitted by the Shipper (Requestor), and the third version of the Verify Copy submitted by the Carrier that the Shipper (Requestor) then approved.

Actionable Flows47b

Carrier submits Sea Waybill (step 8)

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 Flows53b

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

TradeLens processes Sea Waybill (step 9)

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 Flows55b

Shipper retrieves Sea Waybill (step 10)

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 11)

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 Flows57c

Actionable Flows59b

Actionable Flows61b

The example above covered a basic Shipping Instructions to Bill of Lading (Sea Waybill) flow where the Shipping Instructions initiated the process. There are other possible scenarios that we will mention here. If there is an existing consignment for a given booking, a Verify Copy can start the process. The creator of the consignment would have to add the Shipper (Requestor) to the consignment using the partyAdded API. A Bill of Lading (Sea Waybill) can also start the process and the consignment does not need to already exist in TradeLens. The Sea Waybill document can contain information for a few parties and the actionable doc flows API for the Bill of Lading will add the parties to the new consignment.

Additional notes:

  • If a Shipping Instructions is submitted then a Verify Copy is required, and a Bill of Lading cannot be submitted until a Verify Copy is approved.
  • As mentioned in step 7, once a Verify Copy is approved, no other Verify Copy can be submitted by the Carrier or the Requestor.
  • As mentioned in step 7, once a Verify Copy is approved, then the final Bill of Lading can be issued by the Carrier.
  • Once a Bill of Lading is issued, it can not be amended, unless a new Shipping Instructions is submitted (and that would then require the Verify Copy flow before a new Bill of Lading).
  • Once the Carrier submits a Verify Copy, the Shipper (Requestor) will usually approve the document or ask for clarification in the Verify Copy. The Carrier can submit additional Verify Copy documents until the Shipper takes action.
  • Once the Shipper requests clarification, the next action must be by the Carrier, the Shipper can not amend the Verify Copy.