3. Use cases - Booking 2.0

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.
Components of a use case
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 following use cases have been defined by DCSA to support the Booking process. The complete list of use cases is shown below.

3.2 Use cases

The following use cases have been defined by DCSA to support the Booking process. The complete list of use cases is shown below.

#

Use case name

[Actor] to [Actor]

1

Submit Booking request

Shipper to Carrier

2

Request to update Booking request

Carrier to Shipper

3

Submit updated Booking request

Shipper to Carrier

4

Reject Booking request

Carrier to Shipper

5

Confirm Booking request

Carrier to Shipper

6

Request to amend confirmed Booking

Carrier to Shipper

7

Request amendment to confirmed Booking

Shipper, Consignee or Endorsee to Carrier

8

Process amendment to confirmed Booking

Carrier to Shipper, Consignee or Endorsee

9

Cancel amendment to confirmed Booking

Shipper, Consignee or Endorsee to Carrier

10

Decline Booking by Carrier

Carrier to Shipper

11

Cancel Booking request by Shipper

Shipper to Carrier

12

Confirm Booking completed

Carrier to Shipper

13

Cancel confirmed Booking by Shipper

Shipper to Carrier

14

Process Booking cancellation

Carrier to Shipper

UC1: Submit Booking request

ActorsShipper to CarrierDescriptionThe Shipper submits the Booking request for a shipment.PreconditionsThe Shipper has sufficient information to submit a Booking request.PostconditionsThe Booking is in state RECEIVED.FlowThe Shipper submits the Booking request.The Carrier responds synchronously with a successful HTTP status code and sets the Booking state to RECEIVED.The Carrier sends asynchronously a notification to the relevant registered counterparts containing the Carrier Booking request reference and the state of the Booking.

UC2: Request to update Booking request

ActorsCarrier to ShipperDescriptionThe Carrier requests that the Shipper submits an update to the Booking request.PreconditionsThe Booking is in one of the following states:
  • RECEIVED
  • PENDING UPDATE (if the Carrier has already requested that the Shipper updates the Booking request without having received the update)
  • UPDATE RECEIVED (if the Carrier has already received a Booking update from the Shipper but is requesting additional updates)
PostconditionsThe Booking is in state PENDING UPDATE.FlowThe Carrier decides to request an update to the Booking request and updates its state to PENDING UPDATE.The Carrier sends a notification to the relevant registered counterparts, containing the Carrier Booking request reference, the state of the Booking and indicating the reason for requesting the update.

UC3: Submit updated Booking request

ActorsShipper to CarrierDescriptionThe Shipper submits the updated Booking request.PreconditionsThe Booking is in one of the following states:
  • RECEIVED
  • PENDING UPDATE (if the Carrier has requested that an update to the Booking request be made)
  • UPDATE RECEIVED (if the Shipper has already submitted an updated Booking request but is submitting a new one)
PostconditionsThe Booking is in state UPDATE RECEIVED.FlowWhether or not requested by the Carrier, the Shipper submits an updated Booking request.The Carrier performs an initial synchronous processing of the updated Booking request. The Carrier can accept or reject the request itself and responds with the appropriate HTTP status code.The Carrier sets the Booking state to UPDATE RECEIVED. If a previous update was submitted, the updated Booking request overwrites the content and state of the previous one.The Carrier sends asynchronously a notification to the relevant registered counterparts containing the Carrier Booking request reference and the state of the Booking.

UC4: Reject Booking request

ActorsCarrier to ShipperDescriptionThe Carrier rejects the Booking request received from the Shipper.PreconditionsThe Booking is in one of the following states:
  • RECEIVED
  • PENDING UPDATE
  • UPDATE RECEIVED
PostconditionsThe Booking is in state REJECTED.FlowThe Carrier decides to reject the Booking request and updates its state to REJECTED.The Carrier sends a notification to the relevant registered counterparts, containing the Carrier Booking request reference, the state of the Booking and indicating the reason for the rejection.

UC5: Confirm Booking request

ActorsCarrier to ShipperDescriptionThe Carrier confirms the Booking request.PreconditionsThe Booking is in one of the following states:
  • RECEIVED
  • UPDATE RECEIVED
  • CONFIRMED (if the Carrier has already confirmed the Booking but is updating its content)
PostconditionsThe Booking is in state CONFIRMED.FlowThe Carrier confirms the Booking request and updates its state to CONFIRMED.The Carrier sends a notification to the relevant registered counterparts, containing the Carrier Booking request reference, the Carrier Booking reference and the state of the Booking.

UC6: Request to amend confirmed Booking

ActorsCarrier to ShipperDescriptionThe Carrier requests that the Shipper submits an amendment to the confirmed Booking.PreconditionsThe Booking is in one of the following states:
  • CONFIRMED
  • PENDING AMENDMENT (if the Carrier has already requested that an amendment be submitted but is requesting additional changes)
PostconditionsThe Booking is in state PENDING AMENDMENT.FlowThe Carrier decides to request changes to the confirmed Booking and updates their state to PENDING AMENDMENT.The Carrier sends a notification to the relevant registered counterparts, containing the Carrier Booking reference, the state of the Booking and indicating the reason for requesting to amend the confirmed Booking.

UC7: Request amendment to confirmed Booking

ActorsShipper, Consignee or Endorsee to CarrierDescriptionUC7 supports the following user stories:
  • As a Shipper I want to request an amendment to the confirmed Booking
  • 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 Booking is in one of the following states:
  • CONFIRMED
  • PENDING AMENDMENT (if the Carrier has requested that the amendment be submitted)
If a Transport Document has already been issued, it is in one of the following states:
  • DRAFT
  • ISSUED
  • PENDING SURRENDER FOR AMENDMENT
PostconditionsThe original Booking is in the same state as in the preconditions.The Booking amendment is in state AMENDMENT 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 requests an amendment to the confirmed Booking; 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 Booking amendment request. The Carrier can accept or reject the request itself and responds with the appropriate HTTP status code.The Carrier keeps the original Booking unchanged (including its state) and creates a copy of the Booking with the amendment requested by the Shipper, Consignee or Endorsee, setting its state to AMENDMENT RECEIVED.The Carrier sends asynchronously a notification to the relevant registered counterparts containing the Carrier Booking reference, the state of the original Booking and of the Booking amendment.Note: It is not possible to request multiple Booking amendments in succession overwriting each other. If the Shipper, Consignee or Endorsee would like to submit a new amendment request, they will have to wait until the previous amendment has been processed by the Carrrier or cancel the previous amendment before submitting a new one. Once the Booking amendment is in state AMENDMENT RECEIVED, the only possible paths are:
  • UC8: Process amendment to confirmed Booking
  • UC9: Cancel amendment to confirmed Booking
  • UC10: Decline Booking by Carrier
  • UC13: Cancel confirmed Booking by shipper

UC8: Process amendment to confirmed Booking

ActorsCarrier to Shipper, Consignee or EndorseeDescriptionThe Carrier reviews the Booking amendment and decides whether the proposed changes can be confirmed.PreconditionsThe original Booking is in one of the following states:
  • CONFIRMED
  • PENDING AMENDMENT (if the Carrier has requested that the amendment be submitted)
The Booking amendment is in state AMENDMENT 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 two possible scenarios:
  • If the amendment is confirmed:
The original Booking is in state CONFIRMED.The Booking amendment is in state AMENDMENT CONFIRMED.If a Transport Document has already been issued, it is in the same state as in the preconditions.
  • If the amendment is declined:
The original Booking is in the same state as in the preconditions.The Booking amendment is in state AMENDMENT DECLINED.If a Transport Document has already been issued, it is in the same state as in the preconditions.

Flow

There are two possible scenarios:
  • Confirm
The Carrier confirms the requested Booking amendment and fully and permanently replaces the original Booking with it.The Carrier updates the state of the original Booking to CONFIRMED and the state of the Booking amendment to AMENDMENT CONFIRMED.The Carrier sends a notification to the relevant registered counterparts, containing the Carrier Booking reference, the state of the original Booking and of the Booking amendment.
  • Decline
The Carrier declines the requested Booking amendment and updates its state to AMENDMENT DECLINED. The original Booking remains in place with its state and content unchanged.The Carrier sends a notification to the relevant registered counterparts, containing the Carrier Booking reference, the state of the original Booking and of the Booking amendment, indicating the reason for declining the amendment.

UC9: Cancel amendment to confirmed Booking

ActorsShipper, Consignee or Endorsee to CarrierDescriptionUC9 supports the following user stories:
  • As a Shipper I want to cancel an amendment to the confirmed Booking
  • As a Shipper I want to cancel an amendment to the Draft Transport Document
  • As a Shipper, Consignee or Endorsee I want to cancel an amendment to the Transport Document
PreconditionsThe original Booking is in one of the following states:
  • CONFIRMED
  • PENDING AMENDMENT (if the Carrier has requested that the Shipper submits the amendment)
The Booking amendment is in state AMENDMENT RECEIVED.If a Transport Document has already been issued, it is in one of the following states:
  • DRAFT
  • ISSUED
  • PENDING SURRENDER FOR AMENDMENT

Postconditions

The original Booking is in the same state as in the preconditions.The Booking amendment is in state AMENDMENT CANCELLED.If a Transport Document has already been issued, it is in the same state as in the preconditions.

Flow

Depending on the underlying user story:
  • The Shipper cancels the amendment to the confirmed Booking; 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 Booking amendment. The Carrier can accept or reject the request itself and responds with the appropriate HTTP status code.The Carrier keeps the original Booking unchanged (including its state) and cancels the Booking amendment, setting its state to AMENDMENT CANCELLED.The Carrier sends asynchronously a notification to the relevant registered counterparts containing the Carrier Booking reference, the state of the original Booking and of the Booking amendment.

UC10: Decline Booking by Carrier

ActorsCarrier to ShipperDescriptionThe Carrier declines the Booking after it was confirmed.PreconditionsThe Booking is in one of the following states:
  • CONFIRMED
  • PENDING AMENDMENT
If a Booking amendment exists, it is in one of the following states:
  • AMENDMENT RECEIVED
  • AMENDMENT CONFIRMED
  • AMENDMENT DECLINED
  • AMENDMENT CANCELLED
PostconditionsThe Booking is in state DECLINED.If a Booking amendment exists, it is in state AMENDMENT DECLINED.FlowThe Carrier decides to decline the Booking and updates its state to DECLINED. If a Booking amendment exists, it is declined along with the original Booking and the Carrier updates its state to AMENDMENT DECLINED.The Carrier sends a notification to the relevant registered counterparts, containing the Carrier Booking reference, the state of the Booking and of the Booking amendment, when applicable, indicating the reason for declining it.

UC11: Cancel Booking request by Shipper

ActorsShipper to CarrierDescriptionThe Shipper cancels the Booking request.PreconditionsThe Booking is in one of the following states:
  • RECEIVED
  • PENDING UPDATE
  • UPDATE RECEIVED
PostconditionsThe Booking is in state CANCELLED.FlowThe Shipper cancels the Booking request.The Carrier performs an initial synchronous processing of the request to cancel the Booking. The Carrier can accept or reject the request itself and responds with the appropriate HTTP status code.The Carrier sets the Booking state to CANCELLED and sends asynchronously a notification to the relevant registered counterparts containing the Carrier Booking request reference and the state of the Booking.

UC12: Confirm Booking completed

ActorsCarrier to ShipperDescriptionThe Carrier confirms the Booking is completed.PreconditionsThe Booking is in state CONFIRMED.The Transport Document is in one of the following states: SURRENDERED FOR DELIVERY; ISSUED (only applicable to Sea Waybills).PostconditionsThe Booking is 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;
The Carrier confirms the Booking is completed and updates its state to COMPLETED.The Carrier sends a notification to the relevant registered counterparts, containing the Carrier Booking reference and the state of the Booking.

UC13: Cancel confirmed Booking by Shipper

ActorsShipper to CarrierDescriptionThe Shipper requests to cancel the Booking after it has previously been confirmed.PreconditionsThe Booking is in one of the following states:
  • CONFIRMED
  • PENDING AMENDMENT
If a Booking amendment exists, it is in one of the following states:
  • AMENDMENT RECEIVED
  • AMENDMENT CONFIRMED
  • AMENDMENT DECLINED
  • AMENDMENT CANCELLED
PostconditionsThe original Booking is in the same state as in the preconditions.The Booking cancellation status is set to CANCELLATION RECEIVED.If a Booking amendment exists, it is in the same state as in the preconditions.FlowThe Shipper requests to cancel the Booking after it has previously been confirmed.The Carrier performs an initial synchronous processing of the request to cancel the Booking. The Carrier can accept or reject the request itself and responds with the appropriate HTTP status code.The Carrier sets the Booking cancellation status to CANCELLATION RECEIVED in the original Booking.The Carrier sends asynchronously a notification to the relevant registered counterparts containing the Carrier Booking reference, the state of the original Booking, the state of the Booking amendment, if one exists, and the Booking cancellation status.

UC14: Process Booking cancellation

ActorsCarrier to ShipperDescriptionThe Carrier reviews the Booking cancellation request and decides whether it can be confirmed.PreconditionsThe original Booking is in one of the following states:
  • CONFIRMED
  • PENDING AMENDMENT
The Booking cancellation status is CANCELLATION RECEIVED.If a Booking amendment exists, it is in one of the following states:
  • AMENDMENT RECEIVED
  • AMENDMENT CONFIRMED
  • AMENDMENT DECLINED
  • AMENDMENT CANCELLED
PostconditionsThere are two possible scenarios:
  • If the cancellation is confirmed:
The original Booking is in state CANCELLED.The Booking cancellation status is CANCELLATION CONFIRMED.If a Booking amendment exists, it is in state AMENDMENT CANCELLED.
  • If the cancellation is declined:
The original Booking is in the same state as in the preconditions.The Booking cancellation status is CANCELLATION DECLINED.If a Booking amendment exists, it is in the same state as in the preconditions.FlowThere are two possible scenarios:
  • Confirm
The Carrier confirms the requested Booking cancellation.The Carrier updates the state of the original Booking to CANCELLED and the Booking cancellation status to CANCELLATION CONFIRMED.If a Booking amendment exists, the Carrier updates the state to AMENDMENT CANCELLED.The Carrier sends asynchronously a notification to the relevant registered counterparts containing the Carrier Booking reference, the state of the original Booking, the state of the Booking amendment, if one exists, and the Booking cancellation status.
  • Decline
The Carrier declines the requested Booking cancellation and updates the Booking cancellation status to CANCELLATION DECLINED. The original Booking remains in place with its state and content unchanged. If a Booking amendment exists, it remains in place with its state and content unchanged.The Carrier sends asynchronously a notification to the relevant registered counterparts containing the Carrier Booking reference, the state of the original Booking, the state of the Booking amendment, if one exists, and the Booking cancellation status.

Standard documentation chapters

Introduction
User stories
State Transition Diagrams