Skip to content

eBL

Copyright IBM Corporation and GTD Solution Inc. 2020

Overview

TradeLens eBL (electronic Bill of Lading) scenarios will be delivered in a phased approach. TradeLens currently supports the Non-negotiable, Straight Bill of Lading, where the Consignee is named and the transfer of title goes from the Consignor to the named Consignee. A TradeLens eBL is a receipt of the goods by the Carrier. This digital asset provides evidence of the contract of carriage between the Shipper and Carrier, and the holder of the eBL has title to the goods listed.

Digitizing the end-to-end process of a Bill of Lading delivers substantial value in terms of direct and indirect cost reduction as well as process improvements. All the parties involved in the transfer save courier fees and avoid delays in the movement of the cargo. The ability to programmatically ingest the information contained in the Bill of Lading also creates opportunities to automate downstream processes.

The eBL flow requires that the three parties involved (Carrier, Shipper/Consignor, and Buyer/Consignee), must be on the TradeLens platform, have an established business partnership (see Supply Chain Partner Relationships), and be entitled to TradeLens eBL capability (entitlement is done by the onboarding team). The Shipper first requests an eBL through shipping instructions sent to the Carrier. This could be a Shipping Instructions (SI) document submitted through Actionable Doc Flows on the platform. The Carrier accepts the SI and generates a Bill of Lading (BoL) as an eBL ("eBL" :true in the BoL JSON file) and submits it through Actionable Doc Flows to the platform and the eBL flow starts.

The following diagram shows the typical steps involved once the eBL flow begins.

ebol_flow1b

  1. The eBL is internally issued by the platform once the Carrier submits the Bill of Lading using Actionable Flows. The eBL is assigned to the Shipper/Consignor as the title holder.

  2. The Shipper/Consignor can transfer the eBL to the Buyer/Consignee or choose switchtopaper to transfer the eBL back to the Carrier and change the Bill of Lading from digital to paper.

  3. The Buyer/Consignee can surrender the eBL to the Carrier or choose switchtopaper to transfer the eBL back to the Carrier and change the Bill of Lading from digital to paper.

The Carrier is always considered the issuer of an eBL. When you transfer an eBL, you are not the holder anymore. When you surrender an eBL, the platform registers the last holder so that the Carrier can start the delivery process. This allows the Buyer/Consignee to receive the goods from the Carrier upon delivery. The eBL operations are recorded on the blockchain ledger as part of the smart contract.

The switchtopaper action can happen when the eBL is in the issue state or the transfer state and can be used in situations where not all of the participants on the eBL flow are using an electronic (digital) bill and they instead need a paper bill. The current holder can request that the electronic bill be switched to a paper bill, and the flow passes back to the Carrier to create a paper bill. Once an eBL is either surrendered to the Carrier or switched to paper, the Carrier will retrieve the Bill of Lading and this marks the terminal state of the eBL flow.

As mentioned above, the issue action is done by the platform as part of the first step in the eBL flow. The transfer, surrender, and switchtopaper actions can be performed through the POST ...​/actionableMessageFlows​/docMessages - Performs Document Action Actionable Flows API (using the actionIdentifiers: eBLTransfer, eBLSurrender, and eBLSwitchToPaper). See the API User Guide for more information on using the TradeLens APIs. The actions can also be performed through the UI.

We will discuss 3 scenarios below, with each showing an example using the UI and the APIs. We will look at the Shipper/Consignor, Buyer/Consignee, and Carrier to see the actions that each can perform.


UI Example

In general, the UI section for eBL is a way for you to view eBLs so that you can take action. It is not a historical view, meaning that if you are not the holder of the eBL, the eBL will be removed from your view in the eBL section of the UI. If (based on your role and the state of the document) you cannot perform any action, there will be no action buttons on the UI.

In each of the scenarios below for the UI, you might also choose to set up a subscription or a notification so that you will know when there is a possible action for you to take on the UI. We discuss specific subscription parameters in the API sections below, so we will not repeat the information here. See the Setting Up Subscriptions section for more general information on subscriptions and see the Notifications and Alerts section for more information on the Notifications and Alerts feature.


Shipper/Consignor

Check for Issued eBLs

Navigate to Flows > E-BILL OF LADING and find any eBLs that show a Current Status of ISSUED. You can search on an E-Bill of Lading Number and use the Current Status filter to help narrow the results on the UI. You will see any Actions that you can currently take on the eBL.

ebol3a

Take Action

In our example, we see 2 Actions currently available: Transfer and Switch to Paper. In our example, we will choose to transfer the eBL to the Consignee. Our Consignee (from the BoL) is preselected and we can click Transfer to confirm the transfer. We could select a different business partner on the Transfer to a Business Partner dialog box if needed; those shown are entitled for eBL and have an established business partnership with our org.

ebol5a

Once it has been transferred, the eBL is removed from our view. If we search on the BoL number, it will not show up in our E-BILL OF LADING view on the UI.

ebol7a

If we look at the consignment, we can see the Bill of Lading transferred event.

ebol9a

The event details for the Bill of Lading transferred event shows the Action as Transferred and the Destination Organization Name.

ebol11a


Buyer/Consignee

Check for Transferred eBLs

Navigate to Flows > E-BILL OF LADING and find any eBLs that show a Current Status of TRANSFERRED. You can search on an E-Bill of Lading Number and also select TRANSFERRED for the Current Status to help narrow the results on the UI. You will see any Actions that you can currently take on the eBL.

ebol23a

Take Action

Depending on the information in the eBL, you can: Transfer eBL to the next party, Surrender back to the Carrier, or Switch To Paper. In our example, we see 3 Actions currently available: Transfer, Switch to Paper, and Surrender. We will choose to surrender the eBL to the Carrier. Our Carrier (from the BoL) is displayed, and since this action is final, we confirm by clicking Surrender.

ebol25a

Once it has been surrendered, there will be no further actions on the UI for the Buyer/Consignee, but the eBL will still be displayed on the UI because the platform leaves the holder as the last org. This allows the Buyer/Consignee to receive the goods from the Carrier upon delivery.

ebol27a


Carrier

Check for Surrendered or Switched to Paper eBLs

Navigate to Flows > E-BILL OF LADING and find any eBLs that show a Current Status of SURRENDERED or SWITCHEDTOPAPER. You can search on an E-Bill of Lading Number and also select SURRENDERED or SWITCHEDTOPAPER for the Current Status to help narrow the results on the UI. There will be no actions to take on the UI since this is terminal state for the eBL flow, but you would perform any appropriate operations on your system. The eBL will still be displayed on the UI, it is not removed from the Carrier's view.

ebol33a



API Example

Similar to the UI, the APIs allow you to perform actions on the eBL, depending on the current state of the eBL flow.


Shipper/Consignor

Here is a basic outline of the process that we will follow to illustrate how you can use the APIs for eBL processing:

  • Create a subscription to receive doc events
    • Optionally, specify docType BILL_OF_LADING and actions for issued, transferred, surrendered, and switchedtopaper as part of the subscription
    • For each docType of BILL_OF_LADING (eventType of documentEvents) received on the subscription
      • If destinationOrgName is your orgName, you have the next action for the eBL
        • If issued - you can transfer or switchtopaper
        • If transferred - you can transfer, switchtopaper, or surrender
        • Take the appropriate action using Actionable Flows API: POST​ ...​/actionableMessageFlows​/docMessages
      • If senderOrgName is your orgName, this is just a notification of an action you performed
      • Otherwise (you are not the sender nor the destination of the action)
        • This is just a notification that the eBL, for a consignment that you participate on, is “flowing”. You might choose to record that for your purposes depending on your requirements

Create Subscription

We will start by creating a subscription for the Shipper/Consignor organization to receive documentation events so that we can take action when certain events occur. See the Setting Up Subscriptions section for more information on subscriptions. We will create an organization subscription and specify docType BILL_OF_LADING and actions for issued, transferred, surrendered, and switchedtopaper as part of the subscription. Subscriptions can be set up through the UI, but we will use the Event Subscription API POST ...​/subscriptions​/org - Create a subscription for your organization in this case. We use the Swagger to create the subscription.

ebol53a

Here is the entire body.

{
  "name": "subscriptionBoLConsignor",
  "orgEventTypes": [
    "documentEvents"
  ],
  "docEventFilters": [
    {
      "action": "issued",
      "docType": "BILL_OF_LADING"
    },
    {
      "action": "transferred",
      "docType": "BILL_OF_LADING"
    },
    {
      "action": "surrendered",
      "docType": "BILL_OF_LADING"
    },
    {
      "action": "switchedtopaper",
      "docType": "BILL_OF_LADING"
    }
  ],

  "webhook": {
    "sharedSecret": "********",
    "uri": "https://mywebhook.com/subscriptionBoLConsignor"
  }
}

Check for BoL Events

When the Carrier submits the BoL through Actionable Doc Flows, the platform will issue the eBL and the event will be sent to our subscription. The following image represents the payload that is sent to our subscription. It has been altered to mask the specific test ids, but the destinationOrgName is what you would check to determine if your org has the next action for the eBL. In this case, we see it is our org, the Shipper/Consignor.

ebol55a

Take Action

As mentioned in the basic outline above, since the destinationOrgName is our orgName, we have the next action for the eBL. Since the current status is issued, we can transfer or switchtopaper. In our example, we will transfer to the Buyer/Consignee (like we did in our UI example). This will allow us to continue our example with the Buyer/Consignee in the next section. We use the POST​ ...​/actionableMessageFlows​/docMessages - Performs Document Action (that can be found in the Actionable Message Flows section of the Actionable Flows API). Review the Swagger description for the API to become familiar with it. The API can be used for different document actions on different types of documents. For our case, there are several pieces of required information that we need to provide in the payload to identify our consignment, document, action, and party. We need a consignment identifier (we could use the consignmentId, or the combination of carrierBookingNumber and billOfLadingNumber), the action identifier eBLTransfer, the documentId, and the partyRef for the Buyer/Consignee. Our subscription payload for the BoL Issued event contains the consignmentId, carrierBookingNumber, billOfLadingNumber, and documentId. The partyRef is from our established business partnership with the Buyer/Consignee. See the Supply Chain Partner Relationships topic for more details.

ebol65a

The response contains the flowTransactionId dcbd6973-3b55-4d51-9f4b-ce559d297dd4.

ebol67a

You should always check the flowTransactionId using the GET ...​/flowTransactions​/{flowTransactionId} - Fetch a actionable doc flow transaction (that can be found in the Transactions section of the Actionable Flows API) to ensure that every part of the process has completed. See the Document Sharing and Actionable Flows APIs section of the API User Guide for more details.

ebol69a

Our subscription receives the payload for the transfer and shows the destinationOrgName for our Buyer/Consignee.

ebol71a


Buyer/Consignee

Here is a basic outline of the process that we will follow to illustrate how you can use the APIs for eBL processing. The steps are very similar to what we have shown in the Shipper/Consignor section above. We are going to continue with the example that we started in the Shipper/Consignor section. So we will assume that the Shipper/Consignor has transferred the eBL to our Buyer/Consignee.

  • Create a subscription to receive doc events
    • Optionally, specify docType BILL_OF_LADING and actions for issued, transferred, surrendered, and switchedtopaper as part of the subscription
    • For each docType of BILL_OF_LADING (eventType of documentEvents) received on the subscription
      • If destinationOrgName is your orgName, you have the next action for the eBL
        • If issued - you can transfer or switchtopaper
        • If transferred - you can transfer, switchtopaper, or surrender
        • Take the appropriate action using Actionable Flows API: POST​ ...​/actionableMessageFlows​/docMessages
      • If senderOrgName is your orgName, this is just a notification of an action you performed
      • Otherwise (you are not the sender nor the destination of the action)
        • This is just a notification that the eBL, for a consignment that you participate on, is “flowing”. You might choose to record that for your purposes depending on your requirements

Create Subscription

We will start by creating a subscription for the Buyer/Consignee organization to receive documentation events so that we can take action when certain events occur. See the Setting Up Subscriptions section for more information on subscriptions. We will create an organization subscription and specify docType BILL_OF_LADING and actions for issued, transferred, surrendered, and switchedtopaper as part of the subscription. Subscriptions can be set up through the UI, but we will use the Event Subscription API POST ...​/subscriptions​/org - Create a subscription for your organization in this case. We use the Swagger to create the subscription.

ebol83a

Here is the entire body.

{
  "name": "subscriptionBoLConsignee",
  "orgEventTypes": [
    "documentEvents"
  ],
  "docEventFilters": [
    {
      "action": "issued",
      "docType": "BILL_OF_LADING"
    },
    {
      "action": "transferred",
      "docType": "BILL_OF_LADING"
    },
    {
      "action": "surrendered",
      "docType": "BILL_OF_LADING"
    },
    {
      "action": "switchedtopaper",
      "docType": "BILL_OF_LADING"
    }
  ],

  "webhook": {
    "sharedSecret": "********",
    "uri": "https://mywebhook.com/subscriptionBoLConsignee"
  }
}

Check for BoL Events

As mentioned earlier, when the Carrier submits the BoL through Actionable Doc Flows, the platform will issue the eBL and the event will be sent to our subscription. Since we are continuing with our example, the Shipper/Consignor has transferred the eBL to our Buyer/Consignee org and the event was sent to our subscription. The following image represents the payload that is sent to our subscription for the transfer. It has been altered to mask the specific test ids, but the destinationOrgName is what you would check to determine if your org has the next action for the eBL. In this case, we see it is our org, the Buyer/Consignee is using our demo-sunny org in this example.

ebol85a

Take Action

As mentioned in the basic outline, since the destinationOrgName is our orgName, we have the next action for the eBL. Since the current status is transferred, we can transfer or switchtopaper. In our example, we will surrender to the Carrier (like we did in our UI example). This will allow us to continue our example with the Carrier in the next section. We use the POST​ ...​/actionableMessageFlows​/docMessages - Performs Document Action (that can be found in the Actionable Message Flows section of the Actionable Flows API). Review the Swagger description for the API to become familiar with it. The API can be used for different document actions on different types of documents. For our case, there are several pieces of required information that we need to provide in the payload to identify our consignment, document, and action. We need a consignment identifier (we could use the consignmentId, or the combination of carrierBookingNumber and billOfLadingNumber), the action identifier eBLSurrender, and the documentId. Our subscription payload for the BoL Transferred event contains the consignmentId, carrierBookingNumber, billOfLadingNumber, and documentId.

ebol95a

The response contains the flowTransactionId af65b100-2c2d-4aa9-9e5f-fa401325cceb.

ebol97a

You should always check the flowTransactionId using the GET ...​/flowTransactions​/{flowTransactionId} - Fetch a actionable doc flow transaction (that can be found in the Transactions section of the Actionable Flows API) to ensure that every part of the process has completed. See the Document Sharing and Actionable Flows APIs section of the API User Guide for more details.

ebol99a

Our subscription receives the payload for the surrender and shows the destinationOrgName for our Carrier.

ebol101a


Carrier

Here is a basic outline of the process that we will follow to illustrate how you can use the APIs for eBL processing. The steps are very similar to what we have shown in the Shipper/Consignor and Buyer/Consignee sections above. We are going to continue with the example that we started in the previous section. So we will assume that the Buyer/Consignee has surrendered the eBL to our Carrier.

  • Publish eBLs using Actionable Flows API: PUT ...​/actionableDocFlows​/billOfLading
  • Create a subscription to receive doc events
    • Optionally, specify docType BILL_OF_LADING and actions for issued, transferred, surrendered, and switchedtopaper as part of the subscription
    • For each docType of BILL_OF_LADING (eventType of documentEvents) received on the subscription
      • If destinationOrgName is your orgName, you have the next action for the eBL
        • If surrendered or switchtopaper - perform appropriate operations on your system
      • If senderOrgName is your orgName, this is just a notification of an action you performed
      • Otherwise (you are not the sender nor the destination of the action)
        • This is just a notification that the eBL, for a consignment that you participate on, is “flowing”. You might choose to record that for your purposes depending on your requirements

Submit eBL

Note: This step would be done at the very start of the eBL flow, but it is mentioned here in the Carrier section since it is a function that the Carrier performs.

The Carrier starts the eBL flow when a Bill of Lading (BoL) document is submitted using the PUT ...​/actionableDocFlows​/billOfLading - Bill of Lading actionable doc flow Actionable Doc Flows API and the BoL JSON file contains "eBL" :true. See the Actionable Doc Flows section for more details on a typical SI (Shipping Instructions) to BoL flow.

Create Subscription

We will start by creating a subscription for the Carrier organization to receive documentation events so that we can take action when certain events occur. See the Setting Up Subscriptions section for more information on subscriptions. We will create an organization subscription and specify docType BILL_OF_LADING and actions for issued, transferred, surrendered, and switchedtopaper as part of the subscription. Subscriptions can be set up through the UI, but we will use the Event Subscription API POST ...​/subscriptions​/org - Create a subscription for your organization in this case. We use the Swagger to create the subscription.

ebol123a

Here is the entire body.

{
  "name": "subscriptionBoLCarrier",
  "orgEventTypes": [
    "documentEvents"
  ],
  "docEventFilters": [
    {
      "action": "issued",
      "docType": "BILL_OF_LADING"
    },
    {
      "action": "transferred",
      "docType": "BILL_OF_LADING"
    },
    {
      "action": "surrendered",
      "docType": "BILL_OF_LADING"
    },
    {
      "action": "switchedtopaper",
      "docType": "BILL_OF_LADING"
    }
  ],

  "webhook": {
    "sharedSecret": "********",
    "uri": "https://mywebhook.com/subscriptionBoLCarrier"
  }
}

Check for BoL Events & Perform Operations

As mentioned earlier, when the Carrier submits the BoL through Actionable Doc Flows, the platform will issue the eBL and the event will be sent to our subscription. In our example, the Shipper/Consignor has transferred the eBL to our Buyer/Consignee org and the event was sent to our subscription. Once the Buyer/Consignee surrendered the eBL to the Carrier, the surrendered event is sent to our subscription and the Carrier would perform any appropriate operations. The following image represents the payload that is sent to our subscription for the surrender. It has been altered to mask the specific test ids, but the destinationOrgName is what you would check to determine if your org has the next action for the eBL. In this case, we see it is our Carrier org. If the Carrier receives switchedtopaper on the subscription, the Carrier would perform any appropriate operations, including changing the BoL from the digital eBL form to a paper form.

ebol125a