Topic-Based Subscriptions


The Topic-Based Subscriptions module is currently in preview
Aidbox's Topic-Based Subscription module offers a robust and efficient mechanism designed to allow clients to ask for notifications when data changes. It is an active notification system, an Aidbox server actively sends notifications to clients as changes occur.

Key Features of the Module:

  • FHIR Conformance: Our implementation strictly adheres to the FHIR Topic-Based Subscriptions Framework Guide, ensuring interoperability and standardized practices.
  • Fault-Tolerant: Built with resilience in mind, the system gracefully handles disruptions, ensuring uninterrupted operations and continuous data flow.
  • Data Integrity Guarantee: Relying on the Change Data Capture (CDC) methodology, the module ensures that every piece of data is accurately captured and relayed, minimizing the risk of data loss or inconsistency.
  • Flexibility: Administrators enjoy a significant degree of flexibility, especially when it comes to defining Topics. The system offers a versatile range of filters that subscribers can use to refine the data they receive.
  • High Performance: Engineered for efficiency, our Topic-Based Subscription module is capable of effortlessly managing thousands of subscribers, maintaining its performance standards even under heavy loads.

Main Components

The Subscription mechanism is composed of two main parts.
  1. 1.
    SubscriptionTopic - defines what is available for subscription, and specifies available filters and shapes of the notification. SubscriptionTopics should be added through the configuration project, only READ and SEARCH operations are available for them.
  2. 2.
    Subscription - describes client request 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 through the FHIR API


The following image shows the architecture of the Aidbox topic-based subscriptions module:
topic-based subscription module
The module is composed of two loosely coupled services:
  1. 1.
    Change Data Capture (CDC) Service - is responsible for processing data change log stream from the PostgreSQL replication slot. The replication slot is created and processed according to topic configuration, which received from Aidbox configuration project. It's CDC service that is responsible for selecting only events who are match the Topic Trigger definition, evaluating canFilterBy expressions, and decoding events into proper FHIR resources. The final events are stored in Topic Queue Storage. At the moment, only PostgreSQL is available as a queue storage, but support for other options is planned. Every event consists of headers, which include focusResourceType, focusResourceId, and canFilterByValues, with the optional inclusion of triggered resources.
  2. 2.
    Delivery Service - is responsible for delivering notifications from Topic Queue Storage to a client who created a subscription via specified channels. For every subscription, the service tracks all sent notifications to allow detection of delivery errors. The delivery is carried out by workers, the number of whom can be adjusted for each topic based on the anticipated number of subscriptions and available resources. The requests for Subscriptions are created by clients with create operations. Subscriptions are initiated in the requested status. after which the handshake procedure is started. Following this, the handshake procedure begins. If successful, the subscription is activated, and corresponding events begin to be delivered from that point onward. These events are grouped into a single notification based on the maxCount and heartbeatPeriod fields of the subscriptions.

Supported FHIR versions

Aidbox Supports Topic-Based Subscriptions for both R5 and R4B (4.3.0) versions. To work with the R4B version Resource Profile: R4/B Topic-Based Subscription is required.

Currently supported features