Helix AU Core - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Subscriptions

Subscriptions

The subscription publish/subscribe pattern enables FHIR clients to retrieve data from a server without performing a more expensive periodic polling queries.

This is the preferred method of detecting changes from the Helix FHIR API.

During the Alpha period please contact partner support to have any required subscriptions created.

Creation

To create a new Subscription, the subscription should be submitted to the server via a FHIR create operation (i.e. exactly the same way that any other resource is created).

Subscriptions should be requested by submitting the subscription in REQUESTED state. The server will examine the subscription, and if it is able to activate it, the status will automatically be changed to ACTIVE.

Subscriptions will only listen to changes on resources from the same Helix tenant.

Helix supports the FHIR REST Hook notification channel.

{
  "resourceType": "Subscription",
  "status": "requested",
  "criteria": "Patient?name=smith",
  "channel": {
    "type": "rest-hook",
    "endpoint": "http://example.com:8080/fhir",
  }
}

In this case, if a new Patient is created with the name "Smith", and the FHIR Storage module assigns it an ID of 123, an HTTP POST will be performed to the address http://example.com:8080/fhir/Patient/123.

Alternatively, the server can be asked to send the entire resource to a nominated FHIR end-point.

{
  "channel": {
    "type": "rest-hook",
    "endpoint": "http://example.com:8080/fhir"
  }
}

More details can be found here: R4 Subscriptions

Retry

Subscriptions that fail to deliver will retry on error. By default, they will continue to retry indefinitely until they succeed. This can be controlled by the subscription-delivery-retry-count extension. Note that after the retry count is exceeded the subscription will be discarded potentially resulting in clinical data loss unless another mechanism is in place to ensure the system has the latest data.

{
    ...
    "extension": [
        {
            "url": "http://hapifhir.io/fhir/StructureDefinition/subscription-delivery-retry-count",
            "valueInteger": "5"
        }
    ],
    ...
}

Delivering Delete Events

By default, subscriptions don't deliver resource delete events. This behavior can be adjusted using a subscription extension.

{
    ...
    "extension": [
        {
            "url": "http://hapifhir.io/fhir/StructureDefinition/subscription-send-delete-messages",
            "valueBoolean": "true"
        }
    ],
    ...
}

Delivering Latest Version

By default if a resource is created and then updated in rapid succession, the deliverer will deliver versions 1 and 2 to the REST HOOK target.

This can be adjusted so that if the resource gets updated before the deliverer manages to transmit the resource, only the latest version will be transmitted (it may be delivered more than once).

{
    ...
    "extension": [
        {
            "url": "http://hapifhir.io/fhir/StructureDefinition/subscription-resthook-deliver-latest-version",
            "valueBoolean": true
        }
    ],
    ...
}