Aidbox topic-based subscriptions
This functionality is available in Aidbox versions 2409 and later and requires FHIR Schema Validator validation engine to be Setup Aidbox with FHIR Schema validation engine.
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
AidboxSubscriptionTopicis 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
AidboxSubscriptionTopicas it is, since FHIR does not include this functionality in R4. - For FHIR R4b, R5, and R6: You can use either the
AidboxSubscriptionTopicor the FHIR SubscriptionTopic resource, depending on the FHIR version used. These versionspecific resources will be added in the upcoming releases.
AidboxTopicDestinationis a custom Aidbox resource that defines where and how the notifications triggered by anAidboxSubscriptionTopicshould be sent. This resource offers flexibility in specifying various types of destinations. And is considered as a system configuration resource.AidboxSubscriptionStatusis 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. 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 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 |
|
\* required.
Currently supported channels
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"
}
}
]
}{
"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"
}
}
]
}{
"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"
}
}
}
]
}