Configuration of EDI 2.0

For detailed technical specifications, please refer to the Swagger documentation.

You can configure parts of how EDI 2.0 should behave as your message handler. One configuration is required per HER‑Id.

Configurations should be updated regularly. We recommend defining the desired configuration declaratively and submitting it on appliation startup.

Submit a Configuration

PUT /mshconfigurations

Request

Locking a Communication Party to a HelseID Client

Set the property ClientLocked to true if you want to make sure you are the only client that may use EDI 2.0 on behalf of the communication party with the given HER‑Id. The lock is applied and tied to your HelseID client Id. If someone calls the API on behalf of a locked HER-Id with credentials that originate from a different HelseID client, they receive return code 423 Locked.

The locked actions include:

• Sending a message from the HER-Id.
• Marking a message as downloaded for the HER-Id.
• Sending application receipt for the HER-Id.
• Updating the configuration for the HER-Id.

The purpose of this functionality is to prevent other applications/EPJs that represent the same legal entity from "stealing" (in the technical sense, not legal) messages from each other. Read more about the scope of HelseID rights on the HelseID considerations page.

When relinquishing responsibility of a communication party, you must release the HER-Id from the lock. Either submit a new configuration with ClientLocked = false or DELETE the configuration.

Automatically Rejecting Certain Messages

Use the property rejectMessageFilters. Here you can provide keys (dictionary/key) that indicate which fields you want to filter on, and values (dictionary/value) that specify which values for those fields should be rejected. Currently only MessageFunction is a possible key:

• MessageFunction – Provide codes from FinnKode 8279 – "Meldingens funksjon".
  • For a message received over traditional EDI, check against Action in the EbXml envelope, which uses FinnKode 8279 (specified in HIS1209:2018).
  • For a message received from another API user of EDI 2.0, check against the property messageTypeIdentificator from the POST /messages request.

When EDI 2.0 rejects a message from an EDI sender, a negative transport acknowledgment (MessageError) with the error code NotSupported is sent. When EDI 2.0 rejects a message from a EDI 2.0 sender, the receiver status is set to Rejected.

Example:

Specify that you want to reject some values from FinnKode 8279. These specific values are in use, but are not permitted in the relevant message standard Svarrapport 1.4:

{
    "rejectMessageFilters": {
        "MessageFunction": [
            "IMTR",
            "SVAR_CYT",
            "SVAR_HIST",
            "SVAR_IMTR"
            "SVAR_KKL",
            "SVAR_MBIO",
            "SVAR_OBD",
        ]
    }
}

Notifications for Rejected Messages

Set the property receiveRefusedMessageNotices to true to receive notifications of type RefusedMessage. This covers messages that are refused from configuration, and messages where we could identify the recipient but was otherwise malformed or contained critical errors.

You can then retrieve information about what sort of message was addressed to you, however the message will not be delivered by EDI 2.0 and you cannot download it. Read more about the relevant notifications on the notifications endpoint page.

Deleting Configurations

DELETE /mshconfigurations

Deletes the configurations for the provided HER-Ids. All the provided HER-Ids must have a stored configurations, and none of the provided HER-Ids may be reserved by another client.

Request