Migration Guide: V2 → V3

1. Changes to Overall Flow

Configuration

• Mandatory for every communication party that uses EDI 2.0.
• Each party is identified by its HER‑Id.
• As a system provider you must create a configuration for every HER‑Id belonging to your clients.
  • When you acquire a new client → add a configuration for its HER‑Id(s).
  • When you release a client → remove the configuration for its HER‑Id(s).
• Requests on behalf of an un-configured HER‑Id are rejected.
• Configurations are managed via the /mshconfigurations endpoint.

Polling & Notifications

• Polling now occurs only on /notifications. The old /messages polling endpoint is retired.
• /notifications returns:
  • New‑message alerts (as in V2).
  • Status‑update alerts for sent messages.
  • (Possibly more types of notifications in the future).
• This reduces the number of HTTP calls required to stay up‑to‑date.
• The endpoint exposes its own offset (see “Handling Offsets” below).
• No extra steps are needed to start receiving notifications - they are available immediately.
• You do not delete notifications — simply move to the next offset.

Server‑Sent Events (SSE) Stream

• /notifications also supports an SSE stream.
• A GET request to /notifications/stream opens a long‑living HTTP connection that pushes events in real time.
• If you use the SSE stream, you can stop polling any endpoint entirely.

2. Functional Changes to /messages

3. Transition Procedure

The most important part is to stop handling messages with your V2 client before you start handling messages with your V3 client.

Recommended Procedure:

• 1. Deploy the V3 client without processing messages.
• 2. Register configurations for all your HER‑Ids via the V3 client.
• 3. (Optional) Record the current notification offset (see below).
• 4. Stop the V2 client. Messages will begin queuing.
• 5. Start the V3 client and process the backlog that accumulated in step 4.
• 6. If processing fails, temporarily revert to the V2 client.
• 7. Once stable, undeploy the V2 client.

Alternative Single-Deploy Procedure:

• 1. Undeploy the V2 client (messages will queue).
• 2. (Optional) Record the current offset.
• 3. Deploy the V3 client - it will declare its configuration and automatically consume the queued messages.

Running both clients concurrently is technically supported, but you may see “missing” documents as one client may trigger deletion of a message that the other has not yet processed. If this is something your application can handle, it is also viable.

4. Handling Notification Offsets

• The offset you send to /notifications (poll or SSE) must be the last offset you have successfully processed.
• Starting at offset 0 is allowed, but you will receive duplicate notifications for every message that already exists in V3, which may be weeks or months worth of data.
• Offsets are global and non‑sequential; gaps are expected.

Determining a Pre‑Existing Offset

• Starting from a pre-existing offset is a way to eliminate almost all duplicate handling.
• Ask an EDI 2.0 developer on Slack for the offset that corresponds to a specific message id (all systems running in producion should already be in contact with us).
• Caveats:
  • We cannot guarantee that V2 message order completely matches V3 notification order, nor that your client processes messages in the same sequence.
  • Trying to deploy a V3 client to start exactly after last message handled in V2 (with no duplicates) is theoretically possible, but runs the risk of loosing messages.
  • Choose an offset that is at least 1-2 minutes older than the moment you stopped the V2 client, and handle the duplicates.

5. Duplicate Handling

You should already have logic to ignore duplicate messages! If you need to add or verify this logic, follow the steps below.

Example V2 Message (GET /messages)

{
    "id": "524f2619-49e0-4899-a26a-9ccb2c682b9a",
    "contentType": "application/xml",
    "receiverHerId": 8142092,
    "senderHerId": 8094866,
    "businessDocumentId": "01ec80d4-ad73-457e-9ae0-3808971e4a84",
    "businessDocumentGenDate": "2026-05-15T07:57:03",
    "isAppRec": false,
    "sourceSystem": "Meldingsvalidator, 2.0.1533.0"
},

or, without metadata:

{
    "id": "524f2619-49e0-4899-a26a-9ccb2c682b9a",
    "receiverHerId": 8142092
}.

Note that id (internal id for EDI 2.0 message handler) is not the same as businessDocumentId (id for the clinical message (business document/payload)).

Corresponding V3 Notification

{
    "relatedMessageId": "524f2619-49e0-4899-a26a-9ccb2c682b9a",
    "type": "NewMessage",
    "notificationReceiverHerId": 8142092,
    "notificationTriggeredByHerId": 8094866,
    "description": "New message received. (SVAR_LAB)",
    "createdAt": "2026-05-15T04:00:11.5833333+00:00",
    "offset": 1190794
}.

Implementing the following check prevents re‑processing the same payload when you start from offset 0 or when you overlap V2 and V3 processing windows.

Best Practice Duplicate‑Check Logic

• Keep a persistent set of V2 id values you have already processed.
• When a notification arrives, compare relatedMessageId to that set.
• If it matches → skip the notification.

Alternative Duplicate-Check Logic

• If you only store businessDocumentIds, fetch the full message (GET /messages/) or its business document (GET /messages//business-document) to resolve the ID before deciding.

If you don't have any duplicate checks whatsoever, you should implement it immediately.