Tutorial: Subscribe to Topic (R4B)

Introduction

This tutorial requires configuring your Aidbox instance with a specific SubscriptionTopic for Observation resource. Additionally, a web service that will receive rest-hook notifications is required. This Repo contains a suitable template project, which should be used for this tutorial.

Choose a topic

Use FHIR API to discover available topics. Each topic contains URL field which should be specified as a criteria field of Subscription.

GET /fhir/SubscriptionTopic
accept: application/json

In response, one configured topic is available, with "url": "http://aidbox.app/SubscriptionTopic/observations".

Create Subscription (R4B)

Create a Subscription resource with all the necessary attributes.

Profile http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription is required for R4B.

Most interesting part are:

  • "criteria" : "http://aidbox.app/SubscriptionTopic/observations" - the Topic that a subscription are created for.

  • {"url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-max-count", "valuePositiveInt" : 2} notification will be delivered immediately when specified number of suitable events is met.

  • {"url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-heartbeat-period", valueUnsignedInt" : 20} period in seconds when all available to the moment messages will be delivered. if no messages collected - heartbeat event will be fired.

  • {"url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-payload-content", "valueCode" : "id-only"} notification will only contain ids of resources. The other options are full-resource and empty.

  • "endpoint" : "http://subscription-demo-server:9000/callback-test-1" endpoint to which POST request with notifications will be sent.

  • {"url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-filter-criteria", "valueString" : "Observation?value=42"} specifies, that only observation with value=42 should be delivered for this notification. Available filters or resources may be configured in SubscriptionTopic.

POST /fhir/Subscription
content-type: application/json
accept: application/json

{
  "meta" : {
    "profile" : [ "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription" ]
  },
  "criteria" : "http://aidbox.app/SubscriptionTopic/observations",
  "channel" : {
    "extension" : [ {
      "url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-heartbeat-period",
      "valueUnsignedInt" : 20
    }, {
      "url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-timeout",
      "valueUnsignedInt" : 60
    }, {
      "url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-max-count",
      "valuePositiveInt" : 2
    } ],
    "type" : "rest-hook",
    "endpoint" : "http://subscription-demo-server:9000/callback-test-1",
    "payload" : "application/fhir+json",
    "_payload" : {
      "extension" : [ {
        "url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-payload-content",
        "valueCode" : "id-only"
      } ]
    }
  },
  "_criteria" : {
    "extension" : [ {
      "url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-filter-criteria",
      "valueString" : "Observation?value=42"
    } ]
  },
  "resourceType" : "Subscription",
  "reason" : "R4/B Test Topic-Based Subscription for Observation",
  "status" : "requested",
  "id" : "test-sub-1",
  "end" : "2024-12-31T12:00:00.000-00:00"
}

As a result of this step Aidbox will try to perform a handshake with the subscriber service. By default Aidbox expects Status:200 response.

You may notice handshake event in demo server UI:

After the successful handshake, the status of the Subscription will be active.

GET /fhir/Subscription/test-sub-id/$status
content-type: application/json
accept: application/json

Aidbox will attempt a handshake with the service three times at 10-second intervals. If no successful response is received, the subscription will be shifted to an "errored" status. To restart the process, the subscription should be deleted and recreated

Last updated

Was this helpful?