Booking 2.0 Beta 1

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 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.Open in Confluence to see this content.

Carrier exception handling

If the Ccarrier 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 1 Data overview.

State Diagram with all use cases

UC1: Submit booking request

Actors
Shipper to Carrier

Description
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 Shipper

Description

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

ActorsShipper to CarrierDescriptionThe Shipper submits the updated Booking request.PreconditionsThe Booking is in one of the following states:RECEIVEDPENDING 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 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

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

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

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

ActorsShipper to CarrierDescriptionThe 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)

PostconditionsThe original Booking is in the same state as in the preconditions.The Booking amendment is in state AMENDMENT RECEIVED.FlowWhether 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

ActorsCarrier to ShipperDescriptionThe 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.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 the amendment is declined:The original Booking is in the same state as in the preconditions.The Booking amendment is in state AMENDMENT DECLINED.FlowThe 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

ActorsShipper to CarrierDescriptionThe Shipper cancels the amendment to the confirmed Booking.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.PostconditionsThe original Booking is in the same state as in the preconditions.The Booking amendment is in state AMENDMENT CANCELLED.FlowThe 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

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 RECEIVEDAMENDMENT CONFIRMEDAMENDMENT DECLINEDAMENDMENT CANCELLEDPostconditionsThe 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 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

ActorsShipper to CarrierDescriptionThe Shipper cancels the Booking.PreconditionsThe 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 RECEIVEDAMENDMENT CONFIRMEDAMENDMENT DECLINEDAMENDMENT CANCELLEDPostconditionsThe Booking is in state CANCELLED.If a Booking amendment exists, it is in state AMENDMENT CANCELLED.FlowThe 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

ActorsCarrier to ShipperDescriptionThe Carrier confirms the Booking is completed after the Transport Document has been surrendered for delivery.PreconditionsThe Booking is in state CONFIRMED.The Transport Document is in state SURRENDERED FOR DELIVERY.PostconditionsThe Booking is in state COMPLETED.FlowThe 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.