Overview

The Founda Healthcare Gateway supports FHIR R4 Subscriptions allowing Application Providers to be notified when (clinical) events happen at a Provider Organization. Applications can subscribe to specific event topics that are published by provider organizations. Provider Organizations authorize applications to be notified. The Founda Healthcare Gateway transforms event messages into FHIR Message bundles, and delivers them as webhook calls to the destination endpoint registered by the subscribing application.

Setting up Subscriptions can be completely managed from within the Console or via API calls. This guide describes the creation of a Subscription as an Application Provider user for one of your Clients via API calls.

đź’ˇ This requires a Client with the scope Create Subscriptions approved by at least one provider!

Flow

alt text

There are two stages to consider: the approval stage and the processing stage. During the approval stage the Application (subscriber) creates a Subscription with a particular Provider. Once the Subscription exists it has status "requested" and requires approval from the Provider’s administrator to be activated. Once a subscription is "active", the client application is notified about events that meet the filter criteria of the Subscription. Events are sent as FHIR R4 compliant Bundles of the type "message", and delivered as JSON payload over HTTPS.

Prerequisites

You can create Subscriptions with Provider Organizations that have approved at least one Client containing the scopes necessary to manage Subscriptions. Such a Client is required to have these scopes:

  • FHIR R4 Create Subscriptions: to create new subscriptions
  • FHIR R4 Read Subscriptions: to view existing subscriptions
  • FHIR R4 Update Subscriptions: to update existing subscriptions (that have not been approved yet)
  • FHIR R4 Delete Subscriptions: to delete subscriptions (approved or not yet approved)
  • FHIR R4 Search Subscriptions: to query all subscriptions within that Client’s scope

Setting up the Subscription

Creating the Subscription

To create a Subscription send a POST request to the Subscription endpoint ({host}/organizations/{organizationId}/fhir/4/Subscription). Use the id of the organization that has approved this Client with the scope to Create Subscriptions.

Request body

Property Type Required Description
resourceType string Yes This is a "Subscription" resource.
id id The logical id of the resource, as used in the URL for the resource. Once assigned, this value never changes.
reason string A description of why this subscription is defined.
criteria string Describes the type of event that that this subscription listens to. Founda follows the R5 Subscription Backport pattern of FHIR.

Criteria are always expressed as an operation (create, update, delete) and any R4 FHIR resource; for example create.patient suggests this Subscription’s notifications are triggered by a subscription topic of the type "create patient".
channel SubscriptionChannel Yes Details where to send notifications when resources are received that meet the criteria.)
channel.type string Supports only rest-hook.
channel.endpoint url URL where the notification will be send to.
channel.payload string Supports application/fhir+json only.
channel.header string[] Any additional headers to send with the request.

Request example

{
  "resourceType": "Subscription",
  "id": "808",
  "reason": "Monitor new neonatal function",
  "criteria": "create.patient",
  "channel": {
    "type": "rest-hook",
    "endpoint": "https://test.founda.com/demo-app",
    "payload": "application/fhir+json",
    "header": [
      "Authorization: Bearer secret-token-abc-123"
    ]
  }
}

Response (200)

The Subscription now exists with the status "requested". The Subscription can be edited until it is approved.

đź’ˇ You cannot edit the Provider for which the Subscription was created. You can only edit its content.

{
  "resourceType": "Subscription",
  "id": "808",
  "meta": {
  },
  "status": "requested",
  "reason": "Monitor new neonatal function",
  "criteria": "create.patient",
  "channel": {
    "type": "rest-hook",
    "endpoint": "https://test.founda.com/demo-app",
    "payload": "application/fhir+json",
    "header": [
      "Authorization: Bearer secret-token-abc-123"
    ]
  }
}

Approval of the Subscription

After the subscription has been approved by the provider, the new subscription will have its state set to active. If instead the Subscription is rejected, the status is set to off. You can opt to maintain the resource or delete it using the DELETE operation.

Guidelines on how to approve the Subscription as a Provider Organization user can be found in the Console Manual.

Deletion of a Subscription

Currently we do not support the end field of the subscription resource as described in FHIR R4. Alternatively to stop a subscription one could use the delete operation.

To delete a Subscription perform a DELETE request using the identifier of the resource: DELETE {host}/organizations/{organizationId}/fhir/4/Subscription/{resourceId}.

Response (200)

{
  "resourceType": "OperationOutcome",
  "text": {
    "status": "generated"
  },
  "issue": [
    {
      "severity": "information",
      "code": "informational",
      "diagnostics": "Successfully deleted 1 resource(s) in 95ms"
    }
  ]
}

Possible error responses

The above described operations could return different error responses, which are described below.

400 (Bad Request)

Indicates that the body sent in the request did not pass the validation.

Violations are described in the issue[].diagnostics property.

  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "processing",
      "diagnostics": "{\"fields\":{\"body/resourceType\":[{\"type\":\"required\",\"info\":\"resourceType\",\"message\":\"body/resourceType is required\"}]}}"
    }
  ]
}

401 (Unauthorized)

Indicates that the authorization header contains an invalid token.

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "security",
      "diagnostics": "Unauthorized"
    }
  ]
}

403 (Forbidden)

Indicates that the Client is not authorized by the Provider Organization to execute operations against the Subscription endpoints. Make sure that your Client Authorization has been approved by the Provider Organization and that it possesses the right scopes, which are described in the Prerequisites section.

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "security",
      "diagnostics": "Forbidden"
    }
  ]
}

What's next?

Once the Subscription is approved the Subscription status is set to "active".

Providers should ensure that the relevant event messages reach the Founda platform. Provider admins can discuss setting this up with their Account manager.

Application users can delete active or rejected Subscriptions using the DELETE operation or from the Console, as described in the Console manual.

Message format

Upon receiving an event trigger the Founda Health Gateway evaluates the trigger event to the list of active subscriptions. Each subscription that meets the subscription criteria is transformed into a notification that is sent to the list of eligible subscribers. Each subscriber will receive the notification through the endpoint defined by the channel property of the subscription.

Two types of trigger event messages can be sent to the Founda Health Gateway:

  • FHIR R4 Bundles of the type message.
  • HL7v2.x messages of types ADT, OMG, ORM and SIU.

Notifications are always sent as FHIR R4 Bundles. Incoming HL7v2.x messages are transformed to a FHIR R4 equivalent as a bundle. Readily available transformations exist for ADT, OMG, ORM and SIU type messages.

Example

Consider an application that intends to keep track of new patients. This application would create a subscription where subscription.criteria equals to create.patient. This subscription is authorized by a Provider Organisation that uses the application.

Upon creating new patient records the Provider Organisation's EHR system sends out HL7v2.x ADT messages. Upon receiving such messages the Founda Gateway identifies the application as the eligable subscriber and transforms the HL7v2.x ADT message into a FHIR R4 Bundle. The bundle, including a FHIR Patient Resource, is submitted to the channel endpoint listed for the application.

The FHIR R4 message bundle conforms to the HL7 v2-to-FHIR Implementation Guide.