DCSA Reference Documentation / Standards / Standard Releases / Verified Gross Mass / Verified Gross Mass v1.0.1

DCSA Interface Standard for VGM 1.0.1 - Use Cases

This page is republished as part of the complete documentation set for this version. No content changes were made compared to the 1.0.0 version.

Contents

Introduction

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. Use cases support user stories: a user story is supported by one or more use cases and vice versa. Together, user stories and use cases can be used to provide a high level understanding of the business requirements of the system being built.

Use case structure

Use cases are descriptions 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 interacting with the system being defined, and can be either users or other systems. They participate in the use case interaction 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

Relevant criteria of the system state 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.

VGM standard use cases

The following use cases have been created by DCSA to define the business process supported by the VGM standard.

UC1: Submitting VGM Declarations

Actors

  • VGM Producer

  • VGM Consumer

Description

A VGM Producer sends to a VGM Consumer the initial or updated VGM Declarations associated with an explicit or implicit subscription that defines a set of relevant bookings, or relevant pieces of equipment.

For simplicity and clarity, throughout the rest of this use case we will refer as “VGM Declarations within the registration scope” to the VGM Declarations that are related to the relevant bookings, or the relevant pieces of equipment, defined by a certain registration. (The actual registration mechanism, filtering and lifecycle management are out of scope in this standard.)

Preconditions

  • The VGM Consumer is explicitly or implicitly registered to receive from the VGM Producer any VGM Declarations within a certain registration scope.

  • The VGM Producer has generated, collected or retrieved from another party the VGM Declarations that are within the scope of a certain registration of the VGM Consumer.

Postconditions

The VGM Consumer has the relevant VGM Declarations.

Flow

  1. The VGM Producer generates, collects or retrieves (from its systems or from one or more other parties) initial or updated VGM Declarations that are within the registration scope of a VGM Consumer.

  2. The VGM Producer sends the VGM Declarations to the VGM Consumer.

Exceptions

  • If the VGM Consumer cannot process some or all of the VGM Declarations in the received list, it responds with a list of feedback items indicating what the problems were.

UC2: Retrieving VGM Declarations

Actors

  • VGM Consumer

  • VGM Producer

Description

A VGM Consumer requests from a VGM Producer the VGM Declarations associated with a booking, transport document reference or with one of its pieces of equipment.

Preconditions

  • The VGM Consumer has the carrier booking reference, transport document reference or equipment reference of a piece of equipment.

  • The VGM Producer has received, collected or generated from a third party (or can retrieve on demand) the VGM Declarations for the shipment (or the specific piece of equipment).

Postconditions

The VGM Consumer has the relevant VGM Declarations.

Flow

  1. The VGM Consumer sends the VGM Producer a request containing the carrier booking reference, transport document reference, or the equipment reference.

  2. The VGM Producer retrieves (from its systems or from one or more other parties) the latest (initial or updated) VGM Declarations relevant to the shipment (or to the specified equipment).

  3. The VGM Producer sends the VGM Declarations to the VGM Consumer.

Exceptions

  • If the VGM Producer cannot retrieve the VGM Declarations, it sends back to the VGM Consumer an empty list of VGM Declaration objects, along with optional feedback information indicating why no VGM Declarations could be provided (for example, an unknown carrier booking reference, transport document reference or equipment reference).

UC3: Forwarding VGM Declarations

Actors

  • originating VGM Producer

  • intermediary party acting as VGM Consumer / VGM Producer

  • destination VGM Consumer

Description

The intermediary party acting as VGM Consumer receives VGM Declarations from the originating VGM Producer, optionally processes them, then acting as a VGM Producer it forwards the VGM Declarations to the destination VGM Consumer.

Note that this is a generic use case that works both with the “push” mechanism from use cases UC1, and with the “pull” mechanism from UC2.

Preconditions

  • The destination VGM Consumer can request VGM Declarations from the intermediary party that acts as VGM Producer, or is explicitly or implicitly registered to receive relevant VGM Declarations from the intermediary party that acts as VGM Producer.

  • The intermediary party that acts as a VGM Consumer can request VGM Declarations from the originating VGM Producer, or is explicitly or implicitly registered to receive VGM Declarations from the originating VGM Producer.

Postconditions

The destination VGM Consumer has the relevant VGM Declarations.

Flow

  1. The intermediary party acting as VGM Consumer receives or retrieves from the originating VGM Producer the latest (initial or updated) VGM Declarations for bookings or pieces of equipment that are relevant to the destination VGM Consumer.

  2. The intermediary party optionally adjusts the routing information of the VGM Declarations and/or the content, for example by enriching it with data from its systems or from other VGM Declarations.

  3. The intermediary party acting as VGM Producer sends the VGM Declarations to the destination VGM Consumer.

Exceptions

  • (Same exceptions from UC1 and/or UC2, depending on whether the forwarding uses a push or pull mechanism.)