A Maritime Single Window (MSW) is the designated digital reporting mechanism for exchanging required port-call information with public authorities. Connecting anchorage records to it means mapping the local data, submitting through the authority's supported interface and tracking rejection, correction and acceptance separately.
The International Maritime Organization (IMO) states that its Member States have been required to use maritime single windows for electronic port information exchange since 1 January 2024 under amendments to the Facilitation Convention. The local authority's schema, permissions and submission rules control the actual connection.
Which Declarations And Responses Must The MSW Interface Support?
List the declarations required at this port. For each, confirm who submits it, which fields are required and when it is due. Check the local interface and reporting rules with the responsible authority. A combined platform may offer other functions, but they need their own owners.
The table separates typical responsibilities; it does not prohibit a combined platform. Confirm the jurisdiction and implementation before assigning ownership.
| Concern | Typical single window responsibility | Typical operational owner |
|---|---|---|
| Authority declarations | Yes | Not applicable |
| Submission status and acknowledgement | Yes | Not applicable |
| Operational allocation and queues | Outside the core reporting purpose | Designated anchorage application |
| Commercial stakeholder exchange | Outside the core reporting purpose | Designated community system |
| Traffic picture and positions | Outside the core reporting purpose | Designated traffic systems |
The comparison between single window, community system and traffic systems is the reference to settle this with stakeholders before interface work starts.
The IMO explanation of the maritime single window requirement provides the international context. Confirm the declarations, permitted submitters and applicable implementation requirements with the designated authority.
Map Declaration Fields To Their Authoritative Port Records
The principle worth defending is that a fact is supplied once and reused. In practice this means mapping each declaration field back to the system that already owns it, and only collecting what genuinely has no existing source.
Do the mapping field by field and record the owner. Where a field has no owner, decide whether it should be captured operationally or entered as part of the declaration. The International Maritime Organization (IMO) Maritime Single Window guidance describes the IMO Compendium’s Data Set and Reference Model.
Use these shared definitions for mapping, then validate the required fields, codes and responses against the designated authority’s interface contract.
Build A Field Mapping Worksheet Before Coding
| Mapping item | What to record |
|---|---|
| Declaration field | Authority defined name, format and requirement condition |
| Source record | Owning system, entity and field |
| Transformation | Approved code conversion, unit change or formatting rule |
| Missing or conflicting value | Review owner and submission hold behavior |
| Verification | Sample input, expected declaration value and retained test result |
A port identifier may need conversion into the authority's code list. Store the mapping version. Send an unknown code for review instead of inventing a replacement. Also check how corrections work: some changes may require a new declaration version. The worksheet is an example; the authority defines the real submission fields and duties.
Include declarations, source fields, the authority interface and exclusions in the reporting connection’s scope of work. This makes missing data and source-side work visible in the estimate.
Reuse permitted port-call milestone records where their meaning matches the required declaration; a service commitment is not automatically an authority-accepted value.
Map A Declaration Before Sending It
Illustrative example
Map the fields and statuses to the designated authority’s supported schema. Declaration D-41 concerns call C-182; it does not grant an anchorage allocation.
| Port Record | Sample Submission Field | Validation |
|---|---|---|
| Call C-182 | local_call_reference | Required local correlation value |
| Vessel V-18 | vessel_reference | Map to the authority’s required identifier |
| Arrival estimate 14:00 | estimated_arrival | Include date and offset |
| Agent A7 | submitter_reference | Authenticated organization must be permitted |
| Reporting port TEST-OLD | reporting_port | Present locally; authority must validate the reference |
Submission, Rejection And Correction
| Time | Exchange | Local State |
|---|---|---|
| 09:00 | D-41 revision 1 submitted | Sent; acceptance unknown |
| 09:01 | Receipt ACK-8 arrives | Received by service; not yet accepted |
| 09:03 | Authority rejects an unrecognized reporting_port | Rejected; error linked to D-41 revision 1 |
| 09:10 | Authorized agent submits corrected revision 2 | Revision 1 retained; revision 2 pending |
| 09:12 | Authority accepts revision 2 | Accepted revision 2 with response reference |
{
"declaration_id": "D-41",
"revision": 1,
"status": "rejected",
"errors": [
{
"field": "reporting_port",
"code": "invalid_reference"
}
]
}A retry after a lost receipt uses the authority’s documented duplicate handling rule. It must not create an unrelated declaration or erase the original rejection. Operational screens can show the reporting status alongside allocation status, with each owner kept explicit.
The Declaration Changes Across Revisions
The messages complete D-41’s sequence. This negative test deliberately sends an incomplete revision 1 to exercise the authority error path. In normal use, the adapter’s required field check would block it before transmission.
{
"declaration_id": "D-41",
"revision": 1,
"local_call_reference": "C-182",
"vessel_reference": "TEST-V-18",
"estimated_arrival": "2026-09-18T14:00:00Z",
"submitter_reference": "A7",
"reporting_port": "TEST-OLD"
}{
"receipt_id": "ACK-8",
"declaration_id": "D-41",
"revision": 1,
"status": "received"
}After the rejection, the permitted submitter supplies the missing value. Revision 2 retains the unchanged fields and replaces the missing field; the local archive stores both complete submissions.
{
"declaration_id": "D-41",
"revision": 2,
"supersedes_revision": 1,
"local_call_reference": "C-182",
"vessel_reference": "TEST-V-18",
"estimated_arrival": "2026-09-18T14:00:00Z",
"submitter_reference": "A7",
"reporting_port": "TEST-PORT"
}{
"declaration_id": "D-41",
"revision": 2,
"status": "accepted",
"response_id": "RESP-12"
}TEST-PORT is a fictitious code, not a value suitable for a real authority submission. ACK-8 proves receipt of revision 1; RESP-12 records acceptance of revision 2. Keeping those references separate prevents the earlier receipt from being mistaken for acceptance.
Isolate Authority Formats In A Versioned Submission Adapter
Single window interfaces vary by jurisdiction and are usually not negotiable. Build an adapter rather than shaping internal models around a submission format that will change.
- Adapter isolating the submission format from internal entities
- Field mapping held as configuration, versioned and reviewable
- Validation applied before submission, with errors returned to the owning system
- Submission status tracked per declaration, not per call
- Acknowledgements, rejections and corrections all represented
The application programming interface (API) and interface requirements guide explains how to identify records, handle repeated submissions and support format changes. Agree what each error means and who must fix it.
Get Identity And Reference Data Right
Identity and reference data mismatches can cause declaration rejection. Agree the authoritative vessel and voyage identifiers, hold the mapping to external references, and make it inspectable when a submission fails.
Keep shared code lists in a controlled location and record their versions. These may include port codes, cargo classes and purpose codes. Separate local copies can drift apart and cause rejections. Port community system integration covers sharing these values with other participants.
Treat Status, Audit And Correction As Requirements
Make The Submission Lifecycle Understandable
A submission is not a fire and forget message. The port needs to know what was sent, when, by whom, what came back, and what was subsequently corrected.
- Full submission history retained, including superseded versions
- Attribution of each submission and correction to a principal
- A worklist for rejections with an owner and an age
- Clear separation between a transmission failure and a business rejection
- Retention aligned with the regulatory requirement, not with convenience
Secure The Channel And Test It Properly
Keep live and test submissions separate. Name who holds the credentials, how they are replaced and who watches for failed exchanges. Agree the permitted network path and the actions each account may perform.
Testing needs a real test environment on the authority side, which is frequently the long pole. Confirm its availability, refresh policy and data rules early. Build the test set from rejections as well as acceptances, because the rejection path is the one operators will use.
Phase The Rollout By Declaration Type
Start with a declaration whose source data and acceptance owner are known. Compare the new exchange with the current process in an approved test or shadow run. Keep only one live submission path to avoid duplicates. Review why records were rejected before adding more declaration types.
Before rollout, walk through an accepted submission, a rejection and a correction with the responsible authority and the actual interface documentation.
Agree who decides whether the current submission route can be retired. Check acknowledgements and business responses against the authority's test records, including delayed and duplicated replies. If a failure occurs after transmission, the operator needs a way to check disposition before sending again.
At the release gate, retain the mapping version, test results and unresolved conditions. Name the owner of future authority schema changes and the route for correcting a rejected submission. Expand to the next declaration only when the existing one can be supported through rejection and recovery, not merely sent successfully once.
Record authority side test access in the integration checklist before committing to a submission cutover date.
Conclusion
Take one declaration through submission, rejection, correction and acceptance in the permitted test environment. Retain the revisions and responses so the operator can identify the outstanding issue and the accepted version.
Expand to another declaration type only after its mapping and status rules are verified. Keep unavailable test access or missing source data visible as an acceptance dependency.
Discuss A Reporting Adapter With SDLC Corp
Discuss the reporting boundary with SDLC Corp when assessing the anchorage operations platform and its software integration services. Supply the designated authority's schema, access requirements and correction process. Request a proposal covering mapping, validation, acknowledgement and revision history, while leaving declaration rules and acceptance with the responsible authority and identifying any source-side work before an implementation is agreed.
Frequently Asked Questions
How Do We Know A Declaration Was Accepted?
Use the acceptance status defined by the designated reporting service. Preserve its response and the related declaration revision. Sending the message successfully or receiving a transport receipt is not sufficient.
Do We Need A Separate Adapter?
A supported direct connection may suit a bounded workflow. A shared adapter can centralize mapping, validation and response handling across applications. Choose the boundary from the supported contract and the team's maintenance responsibilities.
What Determines The Integration Timeline?
The declaration types, source data readiness, supported interface and authority test access determine much of the work. Confirm those dependencies and the required rejection and correction tests before committing to a delivery date.
