interopiO FHIR® Subscriptions Overview

interopiO supports FHIR® Subscriptions on all FHIR resources that pass through an interopiO Gateway. This enables notifications via Email, SMS, WebSocket or REST Hook whenever a resource within the subscribed resource set encounters a write operation.  These subscriptions are implemented following the HL7® FHIR® Subscription specification.

Subscriptions are managed for each gateway on the endpoint <gateway_base_url>/io/Subscription.  Interactions with this endpoint follow the standard REST operations for dealing with a FHIR Subscription resource.

Supported Versions of FHIR®

Note that the FHIR® version of the Subscription resource will be the same as the FHIR version of the gateway where you are managing the Subscription resource.

interopiO offers support of FHIR Subscription on the following versions of FHIR (follow the links below for documentation of the specification for each version):

• FHIR v1.0.2 (DSTU2)
• Coming Soon (reach out to us for early access): FHIR v4.0.1 (R4)

Example Use Cases for Subscriptions

interopiO's support for FHIR® Subscriptions enables many useful and powerful use cases needed for sophisticated decision support apps and services. The following are a few Subscriptions use case examples:

• Notify active sessions of a SMART App of new data relevant to a given session. In this situation, the app may notify the user of the new data and request a refresh charts, algorithms, etc. to consider the new/updated data. 
• Notify users via email or SMS of returned/updated results. The message could encourage the user back into the app for guidance based on the results.
• Trigger outbound messaging/notification to third-parties of specific events. For example, send a payer patient reported data in realtime via HL7 v2 or FHIR Messaging.
• Provide in realtime, CDS services with relevant updates to clinical data so it can respond with more context at various user driven CDS Hook event points.

Authentication

When interacting with the <gateway_base_url>/io/Subscription endpoint, all calls must include an authentication token retrieved from the interopiO auth server during a SMART on FHIR launch of an application activated on that gateway.  Include this as a bearer token in the Authorization header of each request. 

Supported Channel Types

The following channel types are supported according to the Subscription specification:

• Email
• SMS
• WebSocket
• REST Hook

WebSocket Subscription Example

In the following example we'll create a subscription to be notified of all Observation updates for a patient with the id PATIENT-123 and how a browser may use JavaScript to receive these WebSocket notifications.

Create a Subscription Resource

Here we send a POST request that creates a new Subscription in the account example, the environment foo and the gateway bar:

curl --request POST \
 --url https://interopio.com/gateway/fhir/example/foo/bar/io/Subscription \
 --header 'authorization: Bearer <bearer_token>' \
 --header 'content-type: application/json' \
 --data '<see_next_code_block>'
}

This POST request will have the JSON body:

{
  "resourceType": "Subscription",
  "reason": "Notify of all Observation updates (creates and edits) for patient PATIENT-123.",
  "criteria": "Observation?patient=PATIENT-123",
  "channel": {
    "type": "websocket"
  },
  "end": "2020-05-19T16:50:41.471+00:00"
}

The response will contain the created subscription resource:

{
  "resourceType": "Subscription",
  "reason": "Notify of all Observation updates (creates and edits) for patient PATIENT-123.",
  "criteria": "Observation?patient=PATIENT-123",
  "channel": {
    "type": "websocket"
  },
  "end": "2020-05-19T16:50:41.471+00:00"
}

Note that the response contains the assigned resource id fc4603de-24b4-4c54-b558-7abc7dc8c7fd.  We'll use this in the next step to bind our WebSocket.

Bind a WebSocket to the Subscription

Now that we have the resource id of an active subscription, we can initiate a WebSocket connection.  A common use case is to do this in a browser so that running applications can get notifications in real time.

The WebSocket connection endpoint for all gateways is wss://ws.interopio.com. This can also be found by querying the /metadata endpoint and looking for the proper extension:

{
  "resourceType": "Conformance",
  ...,
  "rest": [{
    "extension": [{
      "url": "http://hl7.org/fhir/StructureDefinition/capabilitystatement-websocket",
      "valueUri": "wss://ws.interopio.com"
    }],
  ...,
  }],
  ...,
}

The WebSocket connection is established, then we bind to the resource id identified above:

let connection = new WebSocket("wss://ws.interopio-dev.com");
connection.send('bind fc4603de-24b4-4c54-b558-7abc7dc8c7fd');

If the resource id is valid and the bind successful, the server responds with the message bound fc4603de-24b4-4c54-b558-7abc7dc8c7fd.

Each time an Observation resources is updated for PATIENT-123, the serve will send the message ping fc4603de-24b4-4c54-b558-7abc7dc8c7fd on this WebSocket connection.