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 digitalisation 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.Components of a use caseUse 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.

3.2 Use cases

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

#

Use case name

[Actor] to [Actor]

1

Submit Shipping Instructions

Shipper to Carrier

2

Request to update Shipping Instructions

Carrier to Shipper

3

Submit updated Shipping Instructions

Shipper, Consignee or Endorsee to Carrier

4

Process updated Shipping Instructions

Carrier to Shipper, Consignee or Endorsee

5

Cancel update to Shipping Instructions

Shipper, Consignee or Endorsee 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, Consignee or Endorsee to Carrier

10

Process Transport Document surrender request (amendment)

Carrier to Shipper, Consignee or Endorsee

11

Void original Transport Document and issue amended Transport Document

Carrier to Shipper, Consignee or Endorsee

12

Request surrender Transport Document (delivery)

Shipper, Consignee or Endorsee to Carrier

13

Process Transport Document surrender request (delivery)

Carrier to Shipper, Consignee or Endorsee

14

Confirm Shipping Instructions completed

Carrier to Shipper

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 are in state CONFIRMED.
Postconditions The Shipping Instructions are in state RECEIVED.FlowThe Shipper submits the Shipping Instructions.The Carrier responds synchronously with a successful HTTP status code and updates the Shipping Instructions state to RECEIVED.The Carrier sends asynchronously a notification to the relevant registered counterparts containing the Shipping Instructions reference and the state of the Shipping Instructions.

UC2: Request to update Shipping Instructions

ActorsCarrier to ShipperDescriptionThe Carrier requests that the Shipper submits an update to the Shipping Instructions.PreconditionsThe 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.FlowThe Carrier decides to request an update to the Shipping Instructions and updates the state to PENDING UPDATE.The Carrier sends a 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

ActorsShipper, Consignee or Endorsee to CarrierDescription 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, Consignee or Endorsee I want to request an amendment to the Transport Document
PreconditionsThe 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 previous update to the Shipping Instructions was submitted, the updated copy of the Shipping Instructions is in one of the following states:
  • UPDATE RECEIVED
  • UPDATE CONFIRMED
  • UPDATE DECLINED
  • UPDATE CANCELLED
If a Transport Document has already been issued, it is in one of the following states:
  • DRAFT
  • ISSUED
  • PENDING SURRENDER FOR AMENDMENT
PostconditionsThe 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 Transport Document has already been issued, it is in the same state as in the preconditions.FlowDepending on the underlying user story:
  • Whether or not requested by the Carrier, the Shipper submits an updated version of the Shipping Instructions; OR
  • The Shipper requests an amendment to the Draft Transport Document; OR
  • The Shipper, Consignee or Endorsee requests an amendment to the Transport Document.
The Carrier performs an initial synchronous processing of the updated Shipping Instructions. The Carrier can accept or reject the request itself and responds with the appropriate HTTP status code.The Carrier keeps the original Shipping Instructions unchanged (including their state) and creates a copy of the Shipping Instructions with the latest changes requested by the Shipper, Consignee or Endorsee, setting its state to UPDATE RECEIVED. If a previous update was submitted, the updated Shipping Instructions state will be newly set to UPDATE RECEIVED, overwriting the content and state of the previous update.The Carrier sends asynchronously a 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, Consignee or Endorsee may reference the Shipping Instructions using either the Shipping Instructions reference or the Transport Document reference.Note: The Shipper, Consignee or Endorsee 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).Multiple updates can be requested in succession, overwriting each other.

UC4: Process updated Shipping Instructions

ActorsCarrier to Shipper, Consignee or EndorseeDescriptionThe Carrier reviews the updated copy of the Shipping Instructions and decides whether the proposed changes can be confirmed.PreconditionsThe 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.If a Transport Document has already been issued, it is in one of the following states:
  • DRAFT
  • ISSUED
  • PENDING SURRENDER FOR AMENDMENT
PostconditionsThere 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 a Transport Document has already been issued, it is in the same state as in the preconditions.
  • 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.If a Transport Document has already been issued, it is in the same state as in the preconditions.FlowThere 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 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 the state to UPDATE DECLINED. The original Shipping Instructions remain in place with the state and content unchanged.The Carrier sends a 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

ActorsShipper, Consignee or Endorsee to CarrierDescriptionUC5 supports the following user stories:
  • As a Shipper I want to cancel the update to the Shipping Instructions
  • As a Shipper I want to cancel the amendment to the Draft Transport Document
  • As a Shipper, Consignee or Endorsee I want to cancel the amendment to the Transport Document
PreconditionsThe 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.If a Transport Document has already been issued, it is in one of the following states:
  • DRAFT
  • ISSUED
  • PENDING SURRENDER FOR AMENDMENT
PostconditionsThe original Shipping Instructions are in the same state as in the preconditions.The updated copy of the Shipping Instructions is in state UPDATE CANCELLED.If a Transport Document has already been issued, it is in the same state as in the preconditions.FlowDepending on the underlying user story:
  • The Shipper cancels the updated version of the Shipping Instructions; OR
  • The Shipper cancels the amendment to the Draft Transport Document; OR
  • The Shipper, Consignee or Endorsee cancels the amendment to the Transport Document.
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 and responds with the appropriate HTTP status code.The Carrier keeps the original Shipping Instructions unchanged (including their state) and cancels the updated copy of the Shipping Instructions, setting its state to UPDATE CANCELLED.The Carrier sends asynchronously a 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, Consignee or Endorsee may reference the Shipping Instructions using either the Shipping Instructions reference or the Transport Document reference.

UC6: Publish Draft Transport Document

ActorsCarrier to ShipperDescriptionThe Carrier publishes the Draft Transport Document based on the input provided by the Shipper in the Shipping Instructions, the Booking request and possible subsequent Shipping Instructions updates or Booking amendments.PreconditionsThe 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 are in state CONFIRMED.
In addition, the following condition may apply:
  • The Transport Document is in state DRAFT.
PostconditionsThe Transport Document is in state DRAFT.FlowThe Carrier publishes the Draft Transport Document and updates the state of the Transport Document to DRAFT.If an amendment to the Draft Transport Document was previously requested (via UC3 Submit updated Shipping Instructions and/or via UC7 Request amendment to confirmed Booking - see Booking use cases) and confirmed, the Carrier publishes an amended Draft Transport Document overwriting the content of the previous one and sets the Transport Document state to DRAFT.The Carrier sends a notification to the relevant registered counterparts, containing the Transport Document reference and the state of the Transport Document.

UC7: Approve Draft Transport Document

ActorsShipper to CarrierDescriptionThe Shipper approves the Draft Transport Document.PreconditionsThe Transport Document is in state DRAFT.PostconditionsThe Transport Document is in state APPROVED.FlowThe Shipper approves the Draft Transport Document.The Carrier performs an initial synchronous processing of the request. The Carrier can accept or reject the request itself and responds with the appropriate HTTP status code.The Carrier sends asynchronously a notification to the relevant registered counterparts containing the Transport Document reference and the state of the Transport Document.As an alternative to UC7: If the Shipper would like to request changes to the Draft Transport Document they can do so either by submitting updated Shipping Instructions via UC3 Submit updated Shipping Instructions and/or via UC7 Request amendment to confirmed Booking (see Booking use cases).

UC8: Issue Transport Document

ActorsCarrier to ShipperDescriptionThe Carrier issues the Transport Document to the Shipper.PreconditionsThe Transport Document is in one of the following states:
  • DRAFT
  • APPROVED
  • ISSUED (only applicable to Sea Waybills)
PostconditionsThe Transport Document is in state ISSUED.FlowWhether 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.Usually, the Carrier issues the Transport Document after the Shipper has approved the Draft. However, if no approval has been received in due time, the Carrier auto-approves the Draft and issues the Transport Document following the steps described above.In case of electronic Bill of Ladings (eBL), this flow is performed via the eBL Platform of Carrier’s choice.In case of Sea Waybills, if an amendment to the Transport Document was previously requested (via UC3 Submit updated Shipping Instructions and/or via UC7 Request amendment to confirmed Booking - see Booking use cases) and confirmed, the Carrier issues an amended Transport Document overwriting the content of the previous one and updates the state of the document to ISSUED.The Carrier sends a notification to the relevant registered counterparts, containing the Transport Document reference and the state of the Transport Document.

UC9: Request surrender Transport Document (amendment)

ActorsShipper, Consignee or Endorsee (via eBL Platform) to CarrierDescriptionThe Shipper, Consignee or Endorsee requests the Carrier to surrender the Transport Document for an amendment.PreconditionsThe Transport Document is in state ISSUED.PostconditionsThe Transport Document is in state PENDING SURRENDER FOR AMENDMENT.FlowThe Shipper, Consignee or Endorsee requests the Carrier to surrender the Transport Document for an amendment. In case of an electronic Bill of Lading (eBL), the request is submitted via the same eBL Platform from which the eBL was issued.The Carrier responds synchronously with a successful HTTP status code.The Carrier sends asynchronously a notification to the relevant registered counterparts containing the Transport Document reference and the state of the Transport Document.Note:
  • This use case does not apply to Sea Waybills.
  • The process for amendment to an electronic Bill of Lading (eBL), including switch to paper, shall be exclusively governed by and executed in accordance with the bylaws of the eBL Platform where the surrender for amendment request was received, including establishing whether the user in control of the eBL submitting the request is entitled to carry out this action.

UC10: Process Transport Document surrender request (amendment)

ActorsCarrier to Shipper, Consignee or Endorsee (via eBL Platform)DescriptionThe 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.PreconditionsThe Transport Document is in state PENDING SURRENDER FOR AMENDMENT.PostconditionsThere 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.FlowThere 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 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 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.Note:
  • This use case does not apply to Sea Waybills.
  • The process for amendment to an electronic Bill of Lading (eBL), including switch to paper, shall be exclusively governed by and executed in accordance with the bylaws of the eBL Platform where the surrender for amendment request was received, including establishing whether the user in control of the eBL submitting the request is entitled to carry out this action.

UC11: Void original Transport Document and issue amended Transport Document

ActorsCarrier to Shipper, Consignee or Endorsee (via eBL Platform)DescriptionThe Carrier voids the original Transport Document that was surrendered for amendment by the Shipper, Consignee or Endorsee and issues a new Transport Document, including the requested amendment.PreconditionsThe Transport Document is in state SURRENDERED FOR AMENDMENT.PostconditionsThe original (surrendered) Transport Document is in state VOIDED.The new (amended) Transport Document is in state ISSUED.FlowThe Carrier voids the original Transport Document that was surrendered by the Shipper, Consignee or Endorsee via UC9 Request surrender Transport Document (amendment) and updates the state of the document to VOIDED.The Carrier sends a 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 via the same eBL Platform from which it was initially issued and sets the document state to ISSUED.The Carrier sends a notification to the relevant registered counterparts, containing the Transport Document reference and the state of the Transport Document.Note: This use case does not apply to Sea Waybills.

UC12: Request surrender Transport Document (delivery)

ActorsShipper, Consignee or Endorsee (via eBL Platform) to CarrierDescriptionThe Shipper, Consignee or Endorsee requests the Carrier to surrender the Transport Document to take delivery of the cargo at destination.PreconditionsThe Transport Document is in state ISSUED.PostconditionsThe Transport Document is in state PENDING SURRENDER FOR DELIVERY.FlowThe Shipper, Consignee or Endorsee requests the Carrier to surrender the Transport Document for delivery. In case of an electronic Bill of Lading (eBL), the request is submitted via the same eBL Platform from which the eBL was issued.The Carrier responds synchronously with a successful HTTP status code.The Carrier sends asynchronously a notification to the relevant registered counterparts containing the Transport Document reference and the state of the Transport Document.Note:
  • This use case does not apply to Sea Waybills.
  • The process to surrender an electronic Bill of Lading (eBL) to take delivery of the goods shall be exclusively governed by and executed in accordance with the bylaws of the eBL Platform where the surrender for delivery request was received, including establishing whether the user in control of the eBL submitting the request is entitled to carry out this action.

UC13: Process Transport Document surrender request (delivery)

ActorsCarrier to Shipper, Consignee or Endorsee (via eBL Platform)DescriptionThe 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.PreconditionsThe 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 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 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.Note:
  • This use case does not apply to Sea Waybills.
  • The process to surrender an electronic Bill of Lading (eBL) to take delivery of the goods shall be exclusively governed by and executed in accordance with the bylaws of the eBL Platform where the surrender for delivery request was received, including establishing whether the user in control of the eBL submitting the request is entitled to carry out this action.

UC14: Confirm Shipping Instructions completed

ActorsCarrier to ShipperDescriptionThe Carrier confirms the Shipping Instructions are completed.PreconditionsThe Shipping Instructions are in state RECEIVED;AND:The Booking is in one of the following states: CANCELLED, DECLINED; ORThe Transport Document is in one of the following states: SURRENDERED FOR DELIVERY, ISSUED (only applicable to Sea Waybills);PostconditionsThe Shipping Instructions are in state COMPLETED.Flow
  • After the named Consignee has presented the Sea Waybill to take delivery of the goods at destination; OR
  • After the Transport Document has been surrendered for delivery; OR
  • After the related booking(s) has been cancelled by the Shipper; OR
  • After the related booking(s) has been declined by the Carrier
The Carrier confirms the Shipping Instructions are completed and updates their state to COMPLETED.The Carrier sends a notification to the relevant registered counterparts, containing the Shipping Instructions reference and/or the Transport Document reference and the state of the Shipping Instructions.

Explore chapters

Introduction
User stories
State Transition Diagram