SFM Basis API Implementation Guide

Asynchronous message delivery for Helseplattformen

The term asynchronous indicates the locigal level, the messages are triggered elsewhere in the e-resept chain, but will be delivered synchronously by HTTP to Helseplattformen.

The approach is based on, but not fully compliant to, FHIR messaging.

SFM is already capable of receiving the e-resept XML (M-messages) from Reseptformidleren by using a dedicated entry in the verify message for registering and de-registering an organization as active SFM organization.

Flow diagram showing the registration of a new or updating information for an organization. Active organization will be registered for message delivery to SFM.

Flow diagram showing messages from RF to SFM and further to EPJ system endpoint.

"Deliver" is interpreted as a http POST with a FHIR message bundle as HTTP body. This is a simplified scheme and not a full blown FHIR messaging service, based on:

• Message is already received by SFM on behalf of HP, and acknowledge is sent back to RF.
• One to one service, no addressing is required. (HP may have internal business logic applied based on the receiver of the message, but that is not a part of this spec)

Main principles

• Subscribtion for each organization from HP by updating sfm-Organization in API. This triggers RF subscribtion to RF by HER-id for alternative message delivery (Verify/ERMV).

• Accordingly, un-subscription follows the same principle. RF will fall back to default delivery by AR information.

• SFM reveives messages from RF and accepts them based on criterias (known receiver, etc) and places messages in queue for forarding.

• Messages received by SFM is assumed correctly delivered based on up to date information about organizations, GP responsibility and Multidose responsibility.

• Dedicated process/thread converts incoming messages to FHIR and places in queue/pool for forwarding:

  • M6 legemiddel is converted to sfm-MedicationDispense
  • M6 handelsvare is converted to sfm-GeneralDispense
  • M8 legemiddel is converted to sfm-MedicationDispense
  • M8 handelsvare is converted to sfm-GeneralDispense
  • M25.2 is converted to sfm-MedicationBundle (egen spesifikasjon for multidose)
  • M25.3 is converted to sfm-MedicationBundle (egen spesifikasjon for multidose)
  • M15 is converted to sfm-SlvReseponse
  • M28 is converted to sfm-Task
  • M7 (with m5 attachment) is converted to sfm-RecallInfo
  • ERMV is delivered as FHIR Binary in its original form. (May also be sent as "Ping" as described below).
  • If a message can not be parsed correctly, but is received from RF: eresept-mesage is delivered as FHIR Binary. This is unlikey, but may happen.

• The messages above is wrapped in Bundle with type=message.

• Helseplattformen provides a FHIR HTTP API for reception of Bundle/message in FHIR format

• SFM client uses HTTP POST with Bundle as http Body using XML format.

• The server API is not REST compliant.

• Security is provided by means of 2 way SSL

• Successful reception of messages is responded by HTTP 200 OK.

• Upon delivery SFM will remove the message from the queue, but all messages are logged.

Error handling

The http protocol describes a range of status codes. Upon normal reception of POST message request the server responds 200 OK. The client shall act upon other status codes as follows:

• 300-3xx: Normally not used, treated as a general failure and message delivery is halted. Error message shall be logged by SFM and messages will que up until normal situation is obtained.
• 400-4xx: May occur due to sequrity requirements. Message delivery is halted. Error message shall be logged by SFM and messages will que up until normal situation is obtained.
• 500-5xx: The service is considered "down" or unreacheble". Message delivery is halted. Error message shall be logged by SFM and messages will que up until normal situation is obtained.

SFM may for all situations schedule messages for rety on confugurable intevals. After configurable time and error count without successful delivery, the situation shall be presented to SFM operations team at NHN

Timeout / missing response

Shall be treated the same way as 5xx range status code.

Performance

Helseplattformen indicates that the server will be capable of receiving messages without reasonable delay and with sufficient speed to support SFM client, even after a downtime. Throtteling mechanism is not necessary.

Service endpoints

As of august 2021 the follwing endpoint(s) are defined:

Message delivery endpoint: https://app-test.helseplattformen.no/hpbiztalksfmws/ForskrivningWS.svc/Message

Ping endpoint: https://app-test.helseplattformen.no/hpbiztalksfmws/ForskrivningWS.svc/Ping

Endpoints for production will be established

Security

The service is secured by mutual (Two way) SSL. Helseplattformen issues client certificate for SFM on their side and issues to NHN. Helseplattformen is responsible for renewal and procedures for replacement of server and client certificates.

Operations

Helseplattformen is responsible for procedures for errors and downtime. HNH will receive contact points and procedures for problem solving.

Testing

The service supports a separate "Ping" message for connection check / health-check. The Ping message will be send with a payload as for the Verify message, but without verify content.

* eventCoding/code = "ERMV"
* Focus (reference) er ikke oppgitt. 

The server will ignore the content and shall respond 200 OK if up and running.

Message format

Messages are delivered in the POST payload as a FHIR bundle with type=message. The first entry in the bunlde shall be a FHIR MessageHeader.

Format requirements:

* Bundle/type=message
* Bundle/timestamp= time when SFM generated the bundle
* Bundle/entry[1]: MessageHeader
* Bundle/entry[2]: FHIR Resource according to the list above. 

* MessageHeader/meta/source: Origninal message ID from RF: urn:uuid:<UUID> 
* MessageHeader/eventCoding:  Code from Volven codeset 8279/Meldingens funksjon: (code=V, display=DN) Example: eventCoding/code="ERM8",  eventCoding/display="Utleveringsrapport fastlege"
* MessageHeader/destination: Used when the Resource does not contain information on the receiver 
* MessageHeader/focus: Referanse til selve meldingen i Bundle.

Special considerations

M8 will be delivered to Helseplattformen even if the M6 also will be delivered to helseplattformen for the same dispence event.

Profiling

The initial version of this protocol uses the standard versions of MessageHeader and Bundle without any profiling.