Overview

The Founda Health Platform 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 Health Platform 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.

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 https://api.eu.founda.com/1/health/organizations/{organizationId}/fhir/4/Subscription. Use the id of the organization that has approved this Client with the scope to Create Subscriptions.

Request

An example Subscription payload:

Response

If the operation is successful, the response is 200 OK. The Subscription now exists with the status "requested". The Subscription can be edited until it is approved.

An example response Subscription:

Approval of the subscription

After the Provider has approved the subscription, you will be notified by Founda that the Subscription is now 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 by using the DELETE operation.

Deletion of the 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: https://api.eu.founda.com/1/health/organizations/{organizationId}/fhir/4/Subscription/{resourceId}.

Response

If the operation is successful, the response is 200 OK.

An example response:

Possible error responses

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

400 (Bad Request)

This response indicates that the body sent in the request did not pass the validation. Violations are described in the issue.diagnostics property.

An example response:

401 (Unauthorized)

This response indicates that the authorization header contains an invalid token.

An example response:

403 (Forbidden)

This response 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, as was described in the Prerequisites section on this page.

An example response:

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 Health Platform. Provider admins can discuss setting this up with their account manager. Application users can delete active or rejected Subscriptions by using the DELETE operation or from the console, as described in the Console.

Message format

Upon receiving an event trigger, the Founda Health Platform 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 Platform:

• 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 Organization that uses the application.

Upon creating new patient records, the Provider Organization's EHR system sends out HL7v2.x ADT messages. Upon receiving such messages the Founda Health Platform 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 HL7v2-to-FHIR Implementation Guide.