Aidbox Topic-Based Subscriptions

This functionality is available in Aidbox versions 2409 and later and requires FHIR Schema validation engine to be enabled.

Overview

This feature enables dynamic subscriptions to changes in FHIR resources, allowing users/systems to receive notifications through multiple channels, including Kafka.

For an application example, refer to Aidbox Subscriptions & Kafka AidboxTopicDestination

Key Components

• AidboxSubscriptionTopic is a custom Aidbox resource modeled after the FHIR R6 SubscriptionTopic resource. The resource allows defining a set of events that clients can subscribe to, such as changes in specific resources.

• AidboxTopicDestination is a custom Aidbox resource that defines where and how the notifications triggered by an AidboxSubscriptionTopic should be sent. This resource offers flexibility in specifying various types of destinations. And is considered as a system configuration resource.

• AidboxSubscriptionStatus is a custom Aidbox resource which describes the notifications: what messages stored in the bundle, source and destination.

AidboxSubscriptionTopic

The AidboxSubscriptionTopic resource describes the data sources for subscriptions. It allows clients to subscribe to events in Aidbox and filter them using user-defined triggers, which are specified by the trigger element. Supported properties:

Property	Type	Description
resource *	uri	Resource (reference to definition) for this trigger definition. It is binding to All Resource Types.
supportedInteraction	code	create | update | delete
fhirPathCriteria	string	FHIRPath based trigger rule. FHIRPath criteria are evaluated only within the context of the current resource. Supports %current and %previous variables for comparing resource states during updates.
description	string	Text representation of the event trigger.

* required.

Create AidboxSubscriptionTopic resource

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

{
  "resourceType": "AidboxSubscriptionTopic",
  "url": "http://example.org/FHIR/R5/SubscriptionTopic/QuestionnaireResponse-topic",
  "status": "active",
  "trigger": [
    {
      "resource": "QuestionnaireResponse",
      "fhirPathCriteria": "status = 'completed' or status = 'amended'"
    }
  ]
}

AidboxTopicDestination

The AidboxTopicDestination resource is used to define channel configurations for processing subscription data.

Create a TopicDestination

To start processing subscription data, create a AidboxTopicDestination resource with a reference to the AidboxSubscriptionTopic. Examples of AidboxTopicDestination resources can be found in sub-sections.

Stop subscription data processing

To stop processing subscription data, delete the AidboxTopicDestination resource.

AidboxTopicDestination Profile

Ensure that the resource metadata contains the kind-specific AidboxTopicDestination profile.

Elements

Property	Type	Description
status	code	active - the only possible value for now. Expected to be expanded.
topic *	string	Url of AidboxSubscriptionTopic resource.
kind *	code	Defines the destination for sending notifications. Supported values: kafka-at-least-once, kafka-best-effort, webhook-at-least-once, gcp-pubsub-at-least-once
parameter *	FHIR parameters	Defines the destination parameters for sending notifications. Parameters are restricted by profiles for each destination.
content	Subscription payload content	full-resource | id-only | empty full-resource is the default value.

* required.

Currently supported channels

Webhook AidboxTopicDestinationGCP Pub/Sub AidboxTopicDestinationKafka AidboxTopicDestinationClickHouse AidboxTopicDestinationAidboxTopicSubscription NATS tutorial

Notification Shape

Notification is a FHIR Bundle resource with history type, containing relevant resources in its entries. The first entry is a AidboxSubscriptionStatus resource, which describes the payload. The other entries depend on AidboxTopicDestination content parameter. This parameter is the binding to the FHIR subscription-payload-content value set: full-resource | id-only | empty

full-resource

{
  "resourceType":"Bundle",
  "type":"history",
  "timestamp":"2024-10-03T10:07:55Z",
  "entry":[
    {
      "resource":{
        "resourceType":"AidboxSubscriptionStatus",
        "status":"active",
        "type":"event-notification",
        "notificationEvent":[
          {
            "eventNumber":1,
            "focus":{
              "reference":"QuestionnaireResponse/458e771c-0ff1-4858-ac07-93b7a10c8e3b"
            }
          }
        ],
        "topic":"http://example.org/FHIR/R5/SubscriptionTopic/QuestionnaireResponse-topic",
        "topic-destination":{
          "reference":"AidboxTopicDestination/kafka-destination"
        }
      }
    },
    {
      "resource":{
        "id":"458e771c-0ff1-4858-ac07-93b7a10c8e3b",
        "item":[
          {
            "text":"Leishmania sp 14kD IgG Ser Ql IB",
            "answer":[
              {
                "valueString":"123"
              }
            ],
            "linkId":"128852"
          },
          {
            "text":"Leishmania sp 16kD IgG Ser Ql IB",
            "answer":[
              {
                "valueString":"432"
              }
            ],
            "linkId":"128851"
          }
        ],
        "meta":{
          "lastUpdated":"2024-10-03T10:07:55.843374Z",
          "versionId":"1970",
          "extension":[
            {
              "url":"ex:createdAt",
              "valueInstant":"2024-10-03T10:07:42.342731Z"
            }
          ]
        },
        "author":{
          "identifier":{
            "type":{
              "coding":[
                {
                  "code":"UID",
                  "system":"urn:system:aidbox",
                  "display":"User ID"
                }
              ]
            },
            "value":"admin",
            "system":"http://localhost:8765"
          }
        },
        "status":"completed",
        "authored":"2024-10-03T10:07:55.664Z",
        "resourceType":"QuestionnaireResponse",
        "questionnaire":"http://loinc.org/q/100109-8"
      },
      "fullUrl": "http://aidbox-server/fhir/QuestionnaireResponse/458e771c-0ff1-4858-ac07-93b7a10c8e3b",
      "request":{
        "method":"POST",
        "url":"/fhir/QuestionnaireResponse"
      }
    }
  ]
}

id-only

{
  "resourceType":"Bundle",
  "type":"history",
  "timestamp":"2024-10-03T10:07:55Z",
  "entry":[
    {
      "resource":{
        "resourceType":"AidboxSubscriptionStatus",
        "status":"active",
        "type":"event-notification",
        "notificationEvent":[
          {
            "eventNumber":1,
            "focus":{
              "reference":"QuestionnaireResponse/458e771c-0ff1-4858-ac07-93b7a10c8e3b"
            }
          }
        ],
        "topic":"http://example.org/FHIR/R5/SubscriptionTopic/QuestionnaireResponse-topic",
        "topic-destination":{
          "reference":"AidboxTopicDestination/kafka-destination"
        }
      }
    },
    {
      "fullUrl": "http://aidbox-server/fhir/QuestionnaireResponse/458e771c-0ff1-4858-ac07-93b7a10c8e3b",
      "request":{
        "method":"POST",
        "url":"/fhir/QuestionnaireResponse"
      }
    }
  ]
}

empty

{
  "resourceType":"Bundle",
  "type":"history",
  "timestamp":"2024-10-03T10:07:55Z",
  "entry":[
    {
      "resource":{
        "resourceType":"AidboxSubscriptionStatus",
        "status":"active",
        "type":"event-notification",
        "notificationEvent":[
          {
            "eventNumber":1,
            "focus":{
              "reference":"QuestionnaireResponse/458e771c-0ff1-4858-ac07-93b7a10c8e3b"
            }
          }
        ],
        "topic":"http://example.org/FHIR/R5/SubscriptionTopic/QuestionnaireResponse-topic",
        "topic-destination":{
          "reference":"AidboxTopicDestination/kafka-destination"
        }
      }
    }
  ]
}