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

DCSA Interface Standard for VGM 1.0.1 - User Stories

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

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 user stories.

User stories are typically concise, informal descriptions of a feature or functionality written from an end user’s or stakeholder’s perspective. They express the needs, goals, and expectations of users in a way that is easily understandable to ensure the delivered product meets the intended requirements. In standards development, this translates to creating testable acceptance criteria to validate that the standard is correctly implemented and achieves its intended purpose.

Definitions

The DCSA VGM standard defines in a unified way the exchange of VGM Declarations between relevant business parties defined below as “actors”.

Actors

The VGM standard defines the exchange of VGM Declarations between business entities with the following generic roles.

VGM Producers

VGM Producers are business entities that measure or collect VGM information and submit VGM Declarations or allow them to be retrieved by other parties.

The following categories represent typical types of entities that can act as VGM Producers within the context of the VGM standard. Note that the list is indicative rather than exhaustive.

  • Shipper

  • Consolidator / NVOCC

  • Intermediary party

  • Terminal

  • Weighing facility acting on behalf of the shipper

  • An authorized party acting on behalf of any party above

VGM Consumers

VGM Consumers are business entities that receive VGM Declarations about bookings that are relevant to their business activities.

The following categories represent typical types of entities that can act as VGM Consumers within the context of the VGM standard. Note that the list is indicative rather than exhaustive.

  • Carrier

  • Terminal

  • Intermediary party

User Stories

This section documents the user stories that DCSA has considered as the basis for developing the VGM standard, as well as the mapping to the use cases that implement them. The use cases are defined in a separate IFS section.

US1: Submitting VGM Declarations

As a VGM Producer, I want to submit to the VGM Consumer the initial or updated VGM Declarations for one or all containers of a booking, so that they can use them as soon as they are available without having to repeatedly poll for them.

This user story is implemented by the following use cases:

  • UC1: Submitting VGM Declarations

US2: Retrieving VGM Declarations

As a VGM Consumer, I want to retrieve from the VGM Producer the latest VGM Declarations for one or all containers of a booking, so that I can use them without having to register with the VGM Producer for receiving API calls.

This user story is implemented by the following use cases:

  • UC2: Retrieving VGM Declarations

US3: Forwarding VGM Declarations

As a VGM Consumer, I want to forward or make available to another VGM Consumer the VGM Declarations received or retrieved from a VGM Producer, so that the destination VGM Consumer can use them without having to connect directly with the VGM Producer.

This user story is implemented by the following use cases:

  • UC3: Forwarding VGM Declarations

Alignment of User Stories vs. VERMAS EDIFACT Message

This section provides an overview of how DCSA VGM user stories align with the VERMAS scenarios as defined by SMDG (Version 1.0, 2016-06-21).

US1 - Submitting VGM Information

VERMAS-UC1: The shipper has determined the VGM himself using Method 1 or Method 2 (weighing or calculation) and transmits it directly to the carrier.

VERMAS-UC2: A forwarder, authorized by the shipper, transmits the VGM to the carrier. The weighing has been done by a third party as instructed by the forwarder (Method 1 or 2).

VERMAS-UC4: The shipper ordered the weighing at a weighing facility, and the facility reports the result to the shipper. - This scenario represents a producer-to-consumer transfer initiated by the weighing station, which is conceptually aligned with DCSA UC1 (submission), though the consumer here is the shipper rather than a carrier.

VERMAS-UC5: The shipper ordered the weighing and authorized the weighing station to report the result directly to the carrier.

VERMAS-UC6: The terminal has re-weighed the container because the originally provided VGM was in doubt and sends the new result to the carrier.

VERMAS-UC7: The terminal re-weighed the container and reports to the carrier two different weights determined at different points in time. - This scenario is supported in the API by sending two separate VGM declarations, each containing a single weight value.

US3 - Forwarding VGM Information

VERMAS-UC8: The carrier provides VGM data to the terminal through the standard information channel (for loading operations).

VERMAS-UC9: The carrier has obtained a weight (e.g., from the terminal) and forwards that VGM information to the shipper.

Out of scope

VERMAS-UC3: A third party will determine the weight later; the shipper only reports his responsibility for providing the verified weight. - This scenario doesn’t convey an actual VGM value, only a declaration of obligation, so it doesn’t map to a DCSA API use case.