Subscriptions in Ontoserver

Ontoserver implements the R4 version of the Subscriptions Backport R5 IG using the Subscription resource, allowing a client to subscribe to be notified about changes to other resources in the server.

To enable subscriptions in Ontoserver, set the configuration parameter ontoserver.fhir.subscriptions.enabled to true.

SubscriptionTopics

Ontoserver supports the following subscription topic canonicals:

Changes (Create, Update, Delete) to CodeSystem resources http://ontoserver.csiro.au/fhir/SubscriptionTopic/codesystem|0.0.1
Changes (Create, Update, Delete) to ValueSet resources http://ontoserver.csiro.au/fhir/SubscriptionTopic/valueset|0.0.1
Changes (Create, Update, Delete) to ConceptMap resources http://ontoserver.csiro.au/fhir/SubscriptionTopic/conceptmap|0.0.1
Changes (Create, Update, Delete) to StructureDefinition resources http://ontoserver.csiro.au/fhir/SubscriptionTopic/structuredefinition|0.0.1
Changes (Create, Update, Delete) to NamingSystem resources http://ontoserver.csiro.au/fhir/SubscriptionTopic/namingsystem|0.0.1
Changes (Create, Update, Delete) to Subscription resources http://ontoserver.csiro.au/fhir/SubscriptionTopic/subscription|0.0.1

Creating Subscriptions

Subscriptions must obey the Ontoserver profile for subscriptions. Specifically:

the subscription must reference one of Ontoserver's topic canonicals (with or without version) in its criteria element. These are:
subscriptions can use any search parameter supported by the resource as a filter, using the Backport Filter Criteria extension on the criteria element.
subscriptions must use the rest-hook channel type, in the channel.type element.
endpoints must be whitelisted by the server (using the ontoserver.fhir.subscriptions.endpoints.allowed configuration parameter)
endpoints must use HTTPS, unless the server allows otherwise (using the ontoserver.fhir.subscriptions.endpoints.requireTLS configuration parameter)
subscriptions must specify id-only using the Backport Payload Content extension on the channel.payload element

Subscriptions should be created with a status of requested (or off). The server will then carry out a handshake before setting the subscription's status to active.

Endpoint Security

Endpoints for Subscriptions (as specified in the Subscription.endpoint element) must be whitelisted (using the ontoserver.fhir.subscriptions.endpoints.allowed configuration parameter), and must use TLS (HTTPS) encryption (unless the server is configured otherwise using the ontoserver.fhir.subscriptions.endpoints.requireTLS parameter).

If the Subscription endpoint requires authentication, this can be configured using the authentication.oauth.endpoint.* family of credentials to provide configuration details.

Protocol

Subscriptions in Ontoserver follow the protocols described in the R5 FHIR Specification, with the following restrictions:

Subscriptions must satisfy the Ontoserver Subscriptions profile
On creation or activation (update of a Subscription's status to requested) , the server will attempt to validate the endpoint by sending a handshake request. The following sequence diagram describes the protocol of this process.

The following diagram illustrates the interactions between a client creating a subscription, the Ontoserver instance, and the endpoint for the created subscription.

Subscription Protocol

The following are examples of the payloads for

Status

Clients can inspect the status of Subscriptions using the $status operation, either at the type level (using the id and status parameters to narrow the set of Subscriptions), or at the instance level.

Example: