Bill of Lading 3.0 Beta 2

Standard documentation

3.1 Overview

In line with the techniques used in software development, DCSA has incorporated user stories and use cases into the standards development process to support the digitalization efforts of the shipping industry. Both user stories and use cases serve the purpose of capturing and documenting requirements, but they differ in granularity, level of detail, and the stages of the development process in which they are most prominently used. They are complementary (a user story may be supported by one or more use cases and vice versa) and can be used together to provide a comprehensive understanding of software requirements. In this section we will focus on use cases.Use cases are typically a description of how a system will respond to a specific request or interact with a user and are a valuable technique for capturing and defining functional requirements in a way that is easily understandable by both technical and non-technical stakeholders. The use cases defined in this standard include the following components:Actors: Actors are external entities, which could be users or other systems, interacting with the software. They initiate the use case and are the ones for whom the system provides value.Description: A brief explanation that summarizes the purpose of the use case.Preconditions: Prerequisites that need to be fulfilled or tasks that must be finished prior to the execution of the use case.Postconditions: The state of the system after the successful completion of the use case.Flow: The primary steps of the use case, outlining the expected sequence of interactions between the actors and the system.The exception flow describing how the system should handle unexpected or exceptional situations is described in the Carrier exception handling section.

Use cases

The following use cases have been defined by DCSA to submit Shipping Instructions, publish, and approve a Draft Transport Document and the issuance, amendment and surrender of a Transport Document. The complete list of use cases supporting the Bill of Lading process is shown below. The user stories are defined in the dedicated Bill of Lading user stories page.

1	Submit Shipping Instructions	Shipper to Carrier
2	Request to update Shipping Instructions	Carrier to Shipper
3	Submit updated Shipping Instructions	Shipper to Carrier
4	Process updated Shipping Instructions	Carrier to Shipper
5	Cancel update to Shipping Instructions	Shipper to Carrier
6	Publish Draft Transport Document	Carrier to Shipper
7	Approve Draft Transport Document	Shipper to Carrier
8	Issue Transport Document	Carrier to Shipper
9	Request surrender Transport Document (amendment)	Shipper or Consignee to Carrier
10	Process Transport Document surrender request (amendment)	Carrier to Shipper
11	Void original Transport Document and issue amended Transport Document	Carrier to Shipper
12	Request surrender Transport Document (delivery)	Consignee to Carrier
13	Process Transport Document surrender request (delivery)	Carrier to Consignee
14	Confirm Shipping Instructions completed	Carrier to Shipper

3.1 General use case considerations

Lightweight notifications

In technical terms, lightweight notifications in APIs (Application Programming Interfaces) refer to a messaging pattern where the API sends concise and focused messages to notify clients or subscribers about specific events or changes. These notifications are designed to be minimalistic in terms of data payload and typically contain only essential information such as identifiers or key data elements relevant to the event, allowing the recipient to understand the context and take appropriate action without the need for extensive data transfer.Lightweight notifications have been applied across DCSA standard-based APIs, replacing shipment events as a push mechanism for real-time updates. All parties can independently and optionally subscribe to lightweight notifications supporting the Bill of Lading process defined in this standard. If subscribed, the API consumer (e.g. Shipper, Consignee) is notified whenever the state or content of a Shipping Instructions or Transport Document changes, eliminating their need to proactively poll the GET endpoints for updates. With the transition from polling to lightweight notifications, Carriers benefit from reduced load on their systems, and all parties benefit from reduced network traffic and improved business process latency, facilitating efficient interaction between different systems.The following applies whenever the Carrier sends a lightweight notification:The Carrier independently sends the notification to each relevant counterpart who has registered to receive API notifications for the use cases of this standard. The registration mechanism, life cycle and any filtering are out of scope for this standard.The Carrier sends the lightweight notifications asynchronously, after updating the state and/or content of the document in its own systems. If sending the lightweight notification fails, that does not constitute a use case exception and the Carrier must not revert any of the changes already performed in its own system: the relevant counterpart can be notified out of channel or will receive the update upon a subsequent GET request called to the same API for the same document.

Carrier exception handling

If the Carrier cannot or does not want to accept the API request (e.g. when the Shipper requests to cancel a Shipping Instructions update which is already being processed), it responds with the appropriate error message and HTTP status code. The Carrier does not change the state or content of the document, and it does not send a lightweight notification about the rejected API request.

3.2 Use cases

A complete overview of the use cases below is illustrated in the DCSA Booking and BL State Transition Diagrams. The full list of data attributes that are relevant input for each use case is provided in the DCSA Bill of Lading 3.0 Beta 2 Data overview.

UC1: Submit Shipping Instructions

Actors: Shipper to CarrierDescription: The Shipper submits the Shipping Instructions (SI).Preconditions: The empty equipment has been released to the Shipper. The Booking is in state CONFIRMED. If the Shipping Instructions refer to multiple bookings, all of them must be in state CONFIRMED.Postconditions: The Shipping Instructions are in state RECEIVED.Flow:

The Shipper submits the Shipping Instructions.
The Carrier responds synchronously with a successful HTTP status code.
The Carrier sends asynchronously a lightweight notification to the relevant registered counterparts containing the Shipping Instructions reference and the state of the Shipping Instructions.

UC2: Request to update Shipping Instructions

Actors: Carrier to ShipperDescription: The Carrier requests that the Shipper submits an update to the Shipping Instructions.Preconditions:The Shipping Instructions are in one of the following states:

RECEIVED
PENDING UPDATE (if the Carrier has already requested that updated Shipping Instructions be submitted but is requesting additional updates) If an updated copy of the Shipping Instructions exists, it is in state UPDATE RECEIVED (if the Carrier has already received a Shipping Instructions update from the Shipper but is requesting additional updates)

Postconditions: The Shipping Instructions are in state PENDING UPDATE.Flow:

The Carrier decides to request an update to the Shipping Instructions and updates their state to PENDING UPDATE.
The Carrier sends a lightweight notification to the relevant registered counterparts, containing the Shipping Instructions reference and/or the Transport Document reference, the state of the Shipping Instructions and indicating the reason for requesting the update.

UC3: Submit updated Shipping Instructions

Actors: Shipper to CarrierDescription: The Shipper submits updated Shipping Instructions.Preconditions:The Shipping Instructions are in one of the following states:

RECEIVED
PENDING UPDATE (if the Carrier has requested that updated Shipping Instructions be submitted)

If a (Draft/) Transport Document has already been issued, it is in one of the following states:

DRAFT
ISSUED

Postconditions

The original Shipping Instructions are in the same state as in the preconditions.
The updated copy of the Shipping Instructions is in state UPDATE RECEIVED. If a (Draft/) Transport Document has already been issued, it is in the same state as in the preconditions.

Flow

Whether or not requested by the Carrier, the Shipper submits an updated version of the Shipping Instructions.
The Carrier keeps the original Shipping Instructions unchanged (including their state) and creates a copy of the Shipping Instructions with the changes requested by the Shipper, setting its state to UPDATE RECEIVED.
The Carrier responds synchronously with a successful HTTP status code.
The Carrier sends asynchronously a lightweight notification to the relevant registered counterparts containing the Shipping Instructions reference and/or the Transport Document reference, the state of the original and of the updated copy of the Shipping Instructions.

UC3 supports the following user stories:

As a Shipper I want to update the Shipping Instructions
As a Shipper I want to request an amendment to the Draft Transport Document As a Shipper I want to request an amendment to the Transport Document
Note: The Shipper may reference the Shipping Instructions using either the Shipping Instructions reference or the Transport Document reference.

Note: The Shipper cannot update Reefer or Dangerous Goods details in the Shipping Instructions. In this case, a Booking amendment must be requested via UC7 Request amendment to confirmed Booking (see Booking use cases).

UC4: Process updated Shipping Instructions

Actors: Carrier to ShipperDescription: The Carrier reviews the updated copy of the Shipping Instructions and decides whether the proposed changes can be confirmed.Preconditions: The original Shipping Instructions are in one of the following states:

RECEIVED
PENDING UPDATE (if the Carrier has requested that updated Shipping Instructions be submitted) The updated copy of the Shipping Instructions is in state UPDATE RECEIVED.

Postconditions: There are 2 possible scenarios:If the update is confirmed:

The original Shipping Instructions are in state RECEIVED.
The updated copy of the Shipping Instructions is in state UPDATE CONFIRMED.

If the update is declined:

The original Shipping Instructions are in the same state as in the preconditions.
The updated copy of the Shipping Instructions is in state UPDATE DECLINED.

Flow: The Carrier performs an initial synchronous processing of the request to update the Shipping Instructions. Whether or not the Carrier will accept the proposed changes, and whether or not it will request additional changes via UC2 Request to update Shipping Instructions, the Carrier can accept or reject the request itself following the exception flow described in the section Carrier exception handling. There are 2 possible scenarios:Confirm

The Carrier confirms the updated copy of the Shipping Instructions and fully and permanently replaces the original Shipping Instructions with it.
The Carrier updates the state of the Shipping Instructions to RECEIVED and the state of the updated copy of the Shipping Instructions to UPDATE CONFIRMED.
The Carrier sends a lightweight notification to the relevant registered counterparts, containing the Shipping Instructions reference and/or the Transport Document reference, the state of the original and of the updated copy of the Shipping Instructions.

Decline

The Carrier declines the updated copy of the Shipping Instructions and updates their state to UPDATE DECLINED. The original Shipping Instructions remain in place with their state and content unchanged.

The Carrier sends a lightweight notification to the relevant registered counterparts, containing the Shipping Instructions reference and/or the Transport Document reference, the state of the original and of the updated copy of the Shipping Instructions, indicating the reason for declining the update.

UC5: Cancel update to Shipping Instructions

Actors: Shipper to CarrierDescription: The Shipper cancels the update to the Shipping Instructions.Preconditions:The original Shipping Instructions are in one of the following states:

RECEIVED
PENDING UPDATE (if the Carrier has requested that updated Shipping Instructions be submitted)
The updated copy of the Shipping Instructions is in state UPDATE RECEIVED.

Postconditions:

The original Shipping Instructions are in the same state as in the preconditions.
The updated copy of the Shipping Instructions is in state UPDATE CANCELLED.

Flow: The Shipper cancels the updated version of the Shipping Instructions.

The Carrier performs an initial synchronous processing of the request to cancel the updated copy of the Shipping Instructions. The Carrier can accept or reject the request itself following the exception flow described in the section Carrier exception handling.
The Carrier keeps the original Shipping Instructions unchanged (including their state) and cancels the updated copy of the Shipping Instructions with the changes requested by the Shipper, setting its state to UPDATE CANCELLED.
The Carrier responds synchronously with a successful HTTP status code.
The Carrier sends asynchronously a lightweight notification to the relevant registered counterparts containing the Shipping Instructions reference and/or the Transport
Document reference, the state of the original and of the updated copy of the Shipping Instructions.

Note: The Shipper may reference the Shipping Instructions using either the Shipping Instructions reference or the Transport Document reference.

UC6: Publish Draft Transport Document

Actors: Carrier to ShipperDescription: The Carrier publishes the Draft Transport Document based on the input provided by the Shipper in the Shipping Instructions and the Booking request/amendment.Preconditions:

The following conditions must apply:
The Shipping Instructions are in state RECEIVED.
The Booking is in state CONFIRMED. If the Draft Transport Document refers to multiple bookings, all of them must be in state CONFIRMED. In addition, the following condition may apply: The Transport Document is in state DRAFT.

Postconditions: The Transport Document is in state DRAFT.Flow

The Carrier publishes the Draft Transport Document and updates the state of the Transport Document to DRAFT.
The Carrier sends a lightweight notification to the relevant registered counterparts, containing the Transport Document reference and the state of the Transport Document.
If the Shipper has requested an amendment to the Draft Transport Document via UC3 Submit updated Shipping Instructions or via UC7 Request amendment to confirmed Booking (see Booking use cases) while the Transport Document is in state DRAFT, the Carrier may publish a new Draft Transport Document for Shipper approval following the steps described above, based on the last Booking amendment or update to the Shipping Instructions that was confirmed.

UC7: Approve Draft Transport Document

Actors: Shipper to CarrierDescription: The Shipper approves the Draft Transport Document.Preconditions: The Transport Document is in state DRAFT.Postconditions:The Transport Document is in state APPROVED.Flow

The Shipper approves the Draft Transport Document.
The Carrier responds synchronously with a successful HTTP status code.
The Carrier sends asynchronously a lightweight notification to the relevant registered counterparts containing the Transport Document reference and the state of the Transport Document.

UC8: Issue Transport Document

Actors: Carrier to ShipperDescription: The Carrier issues the Transport Document to the ShipperPreconditions:The Transport Document is in one of the following states:

DRAFT
APPROVED

Postconditions: The Transport Document is in state ISSUED.Flow:

Whether or not the Carrier has received approval of the Draft Transport Document from the Shipper via UC7 Approve Draft Transport Document, the Carrier issues the Transport Document and updates the state of the document to ISSUED.
The Carrier sends a lightweight notification to the relevant registered counterparts, containing the Transport Document reference and the state of the Transport Document.
In the normal process, the Carrier issues the Transport Document after the Shipper has approved the Draft. However, if no approval has been received within the deadline (i.e. when the goods are loaded onto the vessel), the Carrier auto-approves the Draft and issues the Transport Document following the steps described above.

UC9: Request surrender Transport Document (amendment)

Actors: Shipper or Consignee to CarrierDescription: The Shipper or Consignee requests the Carrier to surrender the Transport Document for an amendment.Preconditions: The Transport Document is in state ISSUED.Postconditions: The Transport Document is in state PENDING SURRENDER FOR AMENDMENT.Flow:

The Shipper or Consignee requests the Carrier to surrender the Transport Document for an amendment.
The Carrier responds synchronously with a successful HTTP status code.
The Carrier sends asynchronously a lightweight notification to the relevant registered counterparts containing the Transport Document reference and the state of the Transport Document.

UC10: Process Transport Document surrender request (amendment)

Actors: Carrier to Shipper or ConsigneeDescription: The Carrier processes the surrender request for amendment of the Transport Document to ensure that it complies with the terms and conditions specified in the Transport Document and any associated trade documents or trade finance instruments, such as a Letter of Credit (LC). The Carrier verifies the authenticity of the request and the identity of the requesting party and decides whether the surrender request can be accommodated.Preconditions: The Transport Document is in state PENDING SURRENDER FOR AMENDMENT.Postconditions:There are 2 possible scenarios:

If the request is approved: The Transport Document is in state SURRENDERED FOR AMENDMENT.
If the request is rejected: The Transport Document is in state ISSUED.

Flow: There are 2 possible scenarios:Approve

The Carrier approves the request to surrender the Transport Document for amendment and updates the state of the Transport Document to SURRENDERED FOR AMENDMENT.
The Carrier sends a lightweight notification to the relevant registered counterparts, containing the Transport Document reference and the state of the Transport Document.

Reject

The Carrier rejects the request to surrender the Transport Document for amendment and changes the state of the Transport Document back to ISSUED.
The Carrier sends a lightweight notification to the relevant registered counterparts, containing the Transport Document reference and the state of the Transport Document, indicating the reason for rejecting the surrender request.

UC11: Void original Transport Document and issue amended Transport Document

Actors: Carrier to Shipper or ConsigneeDescription: The Carrier voids the original Transport Document that was surrendered for amendment by the Shipper or Consignee and issues a new Transport Document, including the requested amendment.Preconditions: The Transport Document is in state SURRENDERED FOR AMENDMENT.Postconditions:

The original (surrendered) Transport Document is in state VOIDED.
The new (amended) Transport Document is in state ISSUED.

Flow:

The Carrier voids the original Transport Document that was surrendered by the Shipper or Consignee via UC9 Request surrender Transport Document (amendment) and updates the state of the document to VOIDED.
The Carrier sends a lightweight notification to the relevant registered counterparts, containing the Transport Document reference and the state of the Transport Document. In parallel, the Carrier issues a new (amended) Transport Document and sets the document state to ISSUED.
The Carrier sends a lightweight notification to the relevant registered counterparts, containing the Transport Document reference and the state of the Transport Document.

UC12: Request surrender Transport Document (delivery)

Actors: Consignee to CarrierDescription: The Consignee requests the Carrier to surrender the Transport Document to take delivery of the cargo at destination.Preconditions: The Transport Document is in state ISSUED.Postconditions: The Transport Document is in state PENDING SURRENDER FOR DELIVERY.Flow:

The Consignee requests the Carrier to surrender the Transport Document for delivery.
The Carrier responds synchronously with a successful HTTP status code.
The Carrier sends asynchronously a lightweight notification to the relevant registered counterparts containing the Transport Document reference and the state of the Transport Document.

UC13: Process Transport Document surrender request (delivery)

Actors: Carrier to ConsigneeDescription: The Carrier processes the surrender request of the Transport Document for delivery to ensure that it complies with the terms and conditions specified in the Transport Document and any associated trade documents or trade finance instruments, such as a Letter of Credit (LC). The Carrier verifies the authenticity of the request and the identity of the requesting party and decides whether the surrender request can be accommodated. This use case marks the end of the Bill of Lading process as defined by DCSA.Preconditions: The Transport Document is in state PENDING SURRENDER FOR DELIVERY.PostconditionsThere are 2 possible scenarios:

If the request is approved: The Transport Document is in state SURRENDERED FOR DELIVERY.
If the request is rejected: The Transport Document is in state ISSUED.

FlowThere are 2 possible scenarios:Approve

The Carrier approves the request to surrender the Transport Document for delivery and updates the state of the Transport Document to SURRENDERED FOR DELIVERY.
The Carrier sends a lightweight notification to the relevant registered counterparts, containing the Transport Document reference and the state of the Transport Document.

Reject

The Carrier rejects the request to surrender the Transport Document for delivery and changes the state of the Transport Document back to ISSUED.
The Carrier sends a lightweight notification to the relevant registered counterparts, containing the Transport Document reference and the state of the Transport Document, indicating the reason for rejecting the surrender request.

UC14: Confirm Shipping Instructions completed

Actors: Carrier to ShipperDescription: The Carrier confirms the Shipping Instructions are completed after the Transport Document has been surrendered for delivery. This use case marks the end of the Shipping Instructions document as defined by DCSA.Preconditions

The Shipping Instructions are in state RECEIVED.
The Transport Document is in state SURRENDERED FOR DELIVERY.

Postconditions: The Shipping Instructions are in state COMPLETED.Flow

The Carrier confirms the Shipping Instructions are completed and updates their state to COMPLETED.
The Carrier sends a lightweight notification to the relevant registered counterparts, containing the Shipping Instructions reference and/or the Transport Document reference and the state of the Shipping Instructions.