Topic-based subscriptions using AidboxSubscriptionTopic

This functionality was introduced in the 2408 release and is available in Beta. Please note that this feature is subject to change and may contain incomplete or experimental functionality.

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.

FHIR Compliance:

• For FHIR R4: Use the AidboxSubscriptionTopic as it is, since FHIR does not include this functionality in R4.

• For FHIR R4b, R5, and R6: You can use either the AidboxSubscriptionTopic or the FHIR SubscriptionTopic resource, depending on the FHIR version used. These version-specific resources will be added in the upcoming releases.

• 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.

• AidboxSubscription (not implemented yet) is a custom Aidbox resource that describes client requests to be notified about events described by SubscriptionTopic, specifies what actual filters to apply, and specifies channel, endpoint, and payload shape. Subscriptions are created by a client using FHIR API.

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 resourceTrigger element. Supported properties:

Property	Type	Description
resource *	uri	Resource (reference to definition) for this trigger definition. It is binding to All Resource Types.
fhirPathCriteria	string	FHIRPath based trigger rule. Only current resource state is allowed.
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 kind-specific 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. Kafka - the only possible value for now. Expected to be expanded.
parameter *	FHIR parameters	Defines the destination parameters for sending notifications. Parameters are restricted by profiles for each destination.

* required.

Currently supported channels

Kafka AidboxTopicDestination

Notification Shape

Notification is a FHIR Bundle resource with subscription-notification type, containing relevant resources in its entries.

{
  "resourceType": "Bundle",
  "type": "subscription-notification",
  "timestamp": "2024-08-28T11:10:13.675866Z",
  "entry": [
    {
      "resource": {
        "type": "event-notification",
        "topic": "http://example.org/FHIR/R5/SubscriptionTopic/QuestionnaireResponse-topic",
        "resourceType": "AidboxTopicDestinationStatus",
        "topic-destination": {
          "reference": "AidboxTopicDestination/kafka-destination"
        }
      }
    },
    {
      "resource": {
        "id": "3df44906-a578-4437-915c-f0c006838b2d",
        "item": [
          {
            "text": "ROS Defaults",
            "answer": [
              {
                "valueString": "sdfvzbdfgqearcxvbgadfgqwerdtasdf"
              }
            ],
            "linkId": "1"
          },
          {
            "text": "Constitutional ",
            "linkId": "2"
          }
        ],
        "meta": {
          "lastUpdated": "2024-08-28T11:10:13.673430Z",
          "versionId": "124",
          "extension": [
            {
              "url": "ex:createdAt",
              "valueInstant": "2024-08-28T11:09:51.431354Z"
            }
          ]
        },
        "status": "in-progress",
        "resourceType": "QuestionnaireResponse",
        "questionnaire": "http://forms.aidbox.io/questionnaire/ros|0.1.0"
      },
      "request": {
        "method": "POST",
        "url": "/fhir/Questionnaire/$process-response"
      }
    }
  ]
}