Run Aidbox locallyRun Aidbox in SandboxTalk to us Ask community

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.

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

{
  "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"
      }
    }
  ]
}
PreviousSubscriptionsNextAidbox SubSubscriptions

Last updated

Was this helpful?