This document describes the process of creating and configuring DCSA conformance sandboxes for measuring the conformance of adopter implementations with DCSA standards.
Accessing your conformance environment
For access to a DCSA conformance cloud environment, contact us.Use the credentials provided by DCSA to log on to your DCSA conformance cloud environment:
Creating a conformance sandbox
The home page of your environment lists your current conformance sandboxes.Use the “Create sandbox” button on the home page to create a new sandbox.Standard
Select the DCSA standard with which you want to measure the conformance of your implementation:
Version
Select the version of the standard with which you want to measure the conformance of your implementation:
Scenario suite
Select the scenario suite with which you want to measure the conformance of your implementation. This will typically be the conformance scenario suite of the entire standard or of the standard module that you are focusing on.In special cases, you may choose the advanced option to use the entire reference implementation of the standard, in order to go through one or more of the scenarios that are not included in a conformance scenario suite.
Tested role
Select the role that your application plays within the context of the standard with which you are measuring conformance.In the special situation in which you implement more than one role of a standard, for example both the schedule publisher and the schedule consumer in Operational Vessel Schedules, you need to create separate sandboxes to measure the conformance of your implementation in each role.
Sandbox type
Select the type of sandbox that you want to create.As an adopter of DCSA standards, always choose the default sandbox type. This sandbox contains the orchestrator that guides you through the relevant scenarios, and a synthetic counterpart that will exchange API calls with your application.Do not use the "tested party" sandbox type, which is reserved for use by DCSA only.
Sandbox name
Enter a unique and meaningful name that will allow you to distinguish this sandbox from your other ones in the list, then click "Create".
Configuring a conformance sandbox
The sandbox settings page is displayed right after creating a sandbox. Later on it can be accessed by navigating to the sandbox page from the home page and then clicking the cog icon (⚙️) next to the sandbox name.Sandbox name
You can rename the sandbox using the text field at the top of the "Update sandbox settings" (see the screenshot below). Renaming the sandbox has no effect on its API connectivity or other functionality.Configuring your application to connect to the sandbox
The top section of the sandbox settings page provides the information that you need in order to configure your application to successfully connect to the sandbox.If your application does not need to connect to the sandbox (for example, if you implement the Carrier party of the Booking API without support for sending notifications), you can ignore this section.Sandbox URL
The base URL of all the DCSA standard endpoints on which the synthetic counterpart of your application expects to receive all API calls. The specific full URL of each endpoint is derived by appending to this base URL the endpoint URI defined in the OpenAPI specification (e.g. "/v2/bookings").Request authentication header name and value
All traffic sent to your sandbox is authenticated and authorized using a header name and value. Configure your application to include the authentication header name and value listed here with every API request that it sends to the sandbox.
Configuring the sandbox to connect to your application
Use the "Sandbox settings" section to configure the sandbox to connect to your application.If the sandbox does not need to connect to your application (for example, if you implement the Shipper party of the Booking API without support for receiving notifications), you can leave the URL and the header name and value empty.Sandbox counterpart URL
Set the counterpart URL to the base URL of all the DCSA standard endpoints on which your application expects to receive all API calls. The synthetic counterpart of your application created in the sandbox will append to this URL the appropriate endpoint URI defined in the OpenAPI specification (e.g. "/v2/bookings") for each API call.Sandbox counterpart authentication header name and value
The sandbox adds this header name and value to each API request that it makes to your application. Set these fields to the name and value of a header that your application uses for authentication and authorization.Additional headers (name and value pairs)
If your application requires more than one header name and value pair for authentication and authorization, use the plus and minus buttons to adjust the number of headers and configure the names and values of the additional headers as needed.These additional headers will be included alongside the primary authentication header in every API request that the sandbox makes to your application.
If your application requires OAuth2
There is currently no explicit support for OAuth2 in the conformance framework, but there is a simple workaround for configuring a sandbox to connect to your application using OAuth2:1. Generate an OAuth2 bearer token for your application.2. Set the "Sandbox counterpart authentication header name" to "Authorization".3. Set the "Sandbox counterpart authentication header value" to "Bearer" followed by a space and by the OAuth2 bearer token.Depending on the expiration of your bearer token, it may be convenient to keep the sandbox configuration page open in a separate tab and to generate and apply a new token before running each scenario (or in the case of complex scenarios that require lengthy manual operations within your system, before each action).