Booking 2.0 Beta 2

Standard documentation

Standard Documentation Page | Booking 2.0 beta 2
Overview1. Introduction2. User stories3. Use cases4. Data overview5. Booking and Bill of Lading | State Transition Diagrams

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 support the booking request, amendment, and confirmation process. The complete list of use cases supporting the booking process is shown below. The user stories are defined in the dedicated booking user stories page.

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 to Carrier

8

Process amendment to confirmed Booking

Carrier to Shipper

9

Cancel amendment to confirmed Booking

Shipper to Carrier

10

Decline Booking by Carrier

Carrier to Shipper

11

Cancel Booking by Shipper

Shipper to Carrier

12

Confirm Booking 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 Booking process defined in this standard. If subscribed, the API consumer (e.g. Shipper) is notified whenever the state or content of a Booking or Booking amendment 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 booking amendment 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 Booking 2.0 Beta 2 Data overview.

State Diagram with all use cases

UC1: Submit booking request
Actors Shipper to CarrierDescription The Shipper submits the booking request for a shipment.Preconditions The Shipper has sufficient information to submit a booking request.Postconditions The booking is in state RECEIVED.Flow
  • The Shipper submits the booking request.
  • The Carrier responds synchronously with a successful HTTP status code.
  • The Carrier sends asynchronously a lightweight notification to the relevant registered counterparts containing the Carrier Booking request reference and the state of the booking.
UC2: Request to update booking request
Actors: Carrier to ShipperDescription: The Carrier requests that the Shipper submits an update to the Booking request.Preconditions:The 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)
Postconditions: The Booking is in state PENDING UPDATE.Flow
  • The Carrier decides to request an update to the Booking request and updates its state to PENDING UPDATE.
  • The Carrier sends a lightweight 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
Actors: Shipper to CarrierDescription: The 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)
Postconditions: The Booking is in state UPDATE RECEIVED.Flow:
  • Whether or not requested by the Carrier, the Shipper submits an updated Booking request.
  • The Carrier responds synchronously with a successful HTTP status code.
  • The Carrier sends asynchronously a lightweight notification to the relevant registered counterparts containing the Carrier Booking request reference and the state of the Booking.
UC4: Reject Booking request
Actors:Carrier to ShipperDescription: The Carrier rejects the Booking request received from the Shipper.Preconditions:The Booking is in one of the following states:
  • RECEIVED
  • PENDING UPDATE
  • UPDATE RECEIVED
Postconditions: The Booking is in state REJECTED.Flow:
  • The Carrier decides to reject the Booking request and updates its state to REJECTED.
  • The Carrier sends a lightweight 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
Actors: Carrier to ShipperDescription: The 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.Flow
  • The Carrier confirms the Booking request and updates its state to CONFIRMED.
  • The Carrier sends a lightweight 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
Actors: Carrier to ShipperDescription: The 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)
Postconditions: The Booking is in state PENDING AMENDMENT.Flow:
  • The Carrier decides to request changes to the confirmed Booking and updates their state to PENDING AMENDMENT.
  • The Carrier sends a lightweight 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
Actors: Shipper to CarrierDescription: The Shipper requests an amendment to the confirmed Booking.PreconditionsThe Booking is in one of the following states:
  • CONFIRMED
  • PENDING AMENDMENT (if the Carrier has requested that the amendment be submitted)
  • If a (Draft/) Transport Document has already been issued, it is in one of the following states:
  • DRAFT
  • ISSUED
Postconditions:
  • The original Booking is in the same state as in the preconditions.
  • The Booking amendment is in state AMENDMENT 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 requests an amendment to the confirmed Booking.
  • The Carrier keeps the original Booking unchanged (including its state) and creates a copy of the Booking with the amendment requested by the Shipper, setting its state to AMENDMENT 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 Carrier Booking reference, the state of the original Booking and of the Booking amendment.
UC8: Process amendment to confirmed Booking
Actors: Carrier to ShipperDescription: The Carrier reviews the Booking amendment and decides whether the proposed changes can be confirmed.Preconditions: The 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.
Postconditions:There 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 the amendment is declined:
  • The original Booking is in the same state as in the preconditions.
  • The Booking amendment is in state AMENDMENT DECLINED.
Flow:The Carrier performs an initial synchronous processing of the request to amend the confirmed Booking. Whether or not the Carrier will accept the proposed changes, the Carrier can accept or reject the request itself following the exception flow described in the section Carrier exception handling.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 lightweight 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 lightweight 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
Actors: Shipper to CarrierDescription: The Shipper cancels the amendment to the confirmed Booking.Preconditions:The 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.
Postconditions:
  • The original Booking is in the same state as in the preconditions.
  • The Booking amendment is in state AMENDMENT CANCELLED.
Flow:
  • The Shipper cancels the amendment to the confirmed Booking.
  • The Carrier performs an initial synchronous processing of the request to cancel the Booking amendment. 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 Booking unchanged (including its state) and cancels the Booking amendment, setting its state to AMENDMENT 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 Carrier Booking reference, the state of the original Booking and of the Booking amendment.
UC10: Decline Booking by Carrier
Actors: Carrier to ShipperDescription: The Carrier declines the Booking after it was confirmed.Preconditions:The 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
Postconditions:
  • The Booking is in state DECLINED.
  • If a Booking amendment exists, it is in state AMENDMENT DECLINED.
Flow:
  • The 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 lightweight 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 by Shipper
Actors: Shipper to CarrierDescription: The Shipper cancels the Booking.Preconditions:The Booking is in one of the following states:
  • RECEIVED
  • PENDING UPDATE
  • UPDATE RECEIVED
  • CONFIRMED
  • PENDING AMENDMENT
If a Booking amendment exists, it is in one of the following states:
  • AMENDMENT RECEIVED
  • AMENDMENT CONFIRMED
  • AMENDMENT DECLINED
  • AMENDMENT CANCELLED
Postconditions:
  • The Booking is in state CANCELLED.
  • If a Booking amendment exists, it is in state AMENDMENT CANCELLED.
Flow:
  • The Shipper cancels the Booking. If a Booking amendment exists, it is cancelled along with the original Booking.
  • The Carrier performs an initial synchronous processing of the request to cancel the Booking. The Carrier can accept or reject the request itself following the exception flow described in the section Carrier exception handling.
  • The Carrier responds synchronously with a successful HTTP status code.
  • The Carrier sends asynchronously a lightweight notification to the relevant registered counterparts containing the Carrier Booking request reference and/or the Carrier Booking reference, the state of the Booking and of the Booking amendment, when applicable.
UC12: Confirm Booking completed
Actors: Carrier to ShipperDescription: The Carrier confirms the Booking is completed after the Transport Document has been surrendered for delivery.Preconditions:
  • The Booking is in state CONFIRMED.
  • The Transport Document is in state SURRENDERED FOR DELIVERY.
Postconditions: The Booking is in state COMPLETED.Flow
  • The Carrier confirms the Booking is completed and updates its state to COMPLETED.
  • The Carrier sends a lightweight notification to the relevant registered counterparts, containing the Carrier Booking reference and the state of the Booking.

Standard documentation chapters

Introduction
User stories
Data overview