Conformance Scenarios

This page documents the key concepts involved in executing DCSA conformance scenarios to measure the conformance of your application with the implemented DCSA standard.

To access all conformance documentation, go to the DCSA Conformance page.

 

Sandbox scenarios

Each sandbox page lists the scenarios that DCSA considers to be relevant when measuring the conformance of an adopter implementation. It is possible to return to the Sandbox overview page by clicking the house button (🏠︎) in the top left corner of the screen.

At the top, the name for the Sandbox provided by you is displayed with a cog icon (⚙️) next to it. Press the cog-icon to open the Conformance Sandbox Configuration to modify any configurations for the Sandbox. Then the standard (below example is Booking), the version (below example is 2.0.0), the scenario suite (below example is Conformance) and the role of your application (below example is Carrier). On each Sandbox page it is possible to switch between 2 tabs:

  • Scenarios
  • Reports

 

Scenarios

A list of relevant scenarios often split into meaningfully titled scenario groups. The example below is from the Booking standard showing the group: Dry cargo. Each group contains a list of scenarios. It is possible to run scenarios in any order from any group, there are no dependencies between scenarios.

👉 Important note: Only 1 scenario can be run (played) at any given time for a standard. If a new scenario is to be started, it is necessary to stop the current active scenario, before starting the new.

Scenario status

The button at the left end of each scenario title indicates its running status:

  • The "play" icon (▶) indicates that the scenario was either never run, or was reset after being partially or completely run. Click this icon to start a scenario. If the icon is grey, it indicates that another scenario is running. Stop the running scenario before starting a new scenario.
  • The "stop" icon (🟦) indicates that the scenario is currently running. Click this button to stop the scenario.
  • The "restart" icon (↺) indicates that the scenario was completely run. Click this button to delete the previous conformance results and restart the scenario. If the icon is grey, it indicates that another scenario is running. Stop the running scenario before restarting a scenario.

A scenario can be left at any time during the process of running it. In order to continue where it was left, click anywhere in the scenario - except the "stop" icon (🟦).

 

Conformance result

The second icon at the left of each scenario title indicates the conformance result:

  • The green check mark (✅) indicates that your application behaved in a fully conformant way throughout the entire execution of the scenario.
  • The yellow triangle (⚠️) indicates that your application behaved in a partially conformant way during the execution of the scenario.
  • The red sign (🚫) indicates that your application behaved in a non-conformant way during the execution of the scenario.
  • The grey question mark (❔) indicates that no API traffic was recorded and analyzed upon which to evaluate the conformance of your application for this scenario.

 

Reports

At any point in time a report can be created with the current state of the Sandbox result. Choose a report title and wait for the report to be generated.

The page also contains a list of previously generated reports. Clicking on any of the reports in the list opens the report. If a report has been opened, press the ⬅️ Back to all reports in the top to return to the list.

 

Scenario page

Pressing any scenario on the Scenarios overview page opens a scenario.

The scenario page displays the following information for an active scenario:

  • The title of the scenario, shown as a series of actions separated by dashes. Actions typically correspond to the use cases or actions of a standard. For example UC3 above refers to the Booking standard Use Case 3 - Submit updated Booking request. GET refers to a GET-request to fetch the Booking. You need to be familiar with the standard to understand these actions before running conformance scenarios for it. For more information about standards - please visit dcsa.org for Standards.
  • The list of remaining actions in the scenario, which is the subset of actions that have not yet been performed in the scenario; this list steadily decreases in length with each action you perform.
  • The current action in the scenario, displayed prominently above the action buttons.
  • A description of what needs to be done.
  • Action buttons for refreshing the scenario status (Refresh status) and to complete the current action (Action completed).
  • A button to view the data exchanged (HTTP messages exchanges)
  • The conformance status of all scenario actions, updated as each API exchange relevant to the current action is recorded and analyzed.

For an inactive scenario, the page states that the scenario is not currently running, meaning that no actions can be performed within the scenario page.

It is possible to return to the scenarios page listing all scenarios for the standard by pressing the Sandbox link at the top of the page.

 

View HTTP exchanges window

If the View HTTP exchanges button is pressed, a pop-up windows is displayed. The window contains a textbox where all message information is included for the last action performed. The message includes the request and response with all relevant information like: headers, body, url, method, timestamps, etc...

 

Supplying scenario parameters

The synthetic counterpart created within the DCSA conformance sandbox needs to exchange API calls with your application in order to measure its conformance. However, it is a generic DCSA reference implementation of the standard that does not have any information about your organization's data. Therefore, as a first step in many scenarios, you are prompted to provide some input for the scenario, so that the synthetic counterpart of your application knows how to make API calls that your application will accept. There are two ways the input can be provided:

  • Scenario parameters are used to populate a DCSA-templates containing placeholders. This applies to the following standards:

    • Commercial Schedules (CS)
    • eBL-Issuance (EBL-ISS)
    • eBL Surrender (EBL-SUR)
    • eBL Platform Interoperability (EBL_PINT)
    • Just in Time Portcalls (JIT)
    • Operational Vessel Schedules (OVS)
    • Track & Trace (TNT)

    The values provided from the scenario parameter "view" are inserted into a predefined DCSA template for the standard, substituting placeholder values. The result is a JSON payload.

    An example of this is when measuring the conformance of a Carrier within the eBL-Surrender standard. Before the synthetic eBL Solution Provider can send a Surrender request, you need to tell it the Transport Document Reference (transportDocumentReference), which party to issue to (issueToParty), etc.. This is done by editing the values below. The result is a JSON payload to send with the Surrender request, which your application can successfully process and accept.

  • JSON payload populating the requests without being modified. This applies to the following standards:

    • Booking (BKG)
    • electronic Bill of Lading (EBL)

    The JSON payload provided is used without being modified.

    An example of this is when measuring the conformance of a Carrier within the Booking standard. Before the synthetic shipper can send a booking request, you need to provide the Booking as a JSON object. The object is sent with the Booking request, which your application can successfully process and accept.

Providing values for a scenario virtually always happens in the first action of most scenarios, and there's a clear prompt that you need to take action (▶️) followed by an example JSON object that you need to customize and submit back. (We use JSON rather than a complex web form so you can easily reuse these parameters between scenarios.)

Copy the example JSON into the empty text area, adjust (if needed) each attribute value as needed by your application, then click Submit.

 

Waiting for backend activity

Whenever one or more backend entities is waiting for something, the scenario page displays messages that indicate what needs to happen before you can proceed with the scenario execution.

 

Refreshing current action status

The frontend web UI does not maintain a continuous connection to the backend through which to receive push notifications, nor does it continuously poll the backend for updates when it is your application's turn to make an API call.

Whenever your application has perform an API call that it was expected to perform, for example the Carrier sending a notification to the Shipper within the Booking standard, click the Refresh status button to have the UI updated with the latest information available on the backend.

 

Marking scenario actions completed

When all the exchanges corresponding to a scenario action were completed (for example in Booking, both the primary PUT exchange performed by the Shipper in UC3 and the notification sent back by the Carrier), or when you don't expect further exchange for that action (in the same Booking example, if the notification exchange has not happened but your system does not support sending notifications), you need to click Action completed in order to proceed to the next scenario action.

In addition to supporting systems who don't make optional API calls, for example Booking Carriers who don't send notifications, this also allows you in many cases to retry an exchange that was reported as less than fully conformant without having to restart the scenario.

👉 Important note: To complete the execution of the scenario, you must click Action completed after the last action of the scenario; otherwise the scenario remains running and you cannot start other scenarios.

 

Actions performed by your application

In many scenario actions, the synthetic counterpart of your application that runs in the sandbox sends API requests that your applications handles automatically.

In other scenario actions, your application is expected to perform a specific action that usually results in an API call made to its synthetic counterpart running in the sandbox.

For example, when measuring the conformance of a Carrier application within the Booking standard, UC5 (Use Case 5 - Confirm Booking request) is a use case that your application needs to perform on its own, typically prompted by human action.

In such a case, the fact that it's your application's turn to perform an action is signaled by a "play" icon (▶️) and a clear prompt instructing you what action needs to be performed.

Perform the requested action in your application, then click Refresh status to check the conformance status, then click Action completed when verifying that your application has performed the action in a conformant way.

 

Completing the scenario

When all the actions of a scenario were completed and your application has performed all API requests and responses in a fully conformant way, all actions of the scenario and the scenario itself are marked as fully conformant.

👉 Important note: Remember to click Action completed after the last action of a scenario!