GCP Pub/Sub AidboxTopicDestination

This functionality is available starting from version 2411 and requires FHIR Schema validation engine to be enabled.

The GCP Pub/Sub AidboxTopicDestination works in the following way:

• Aidbox stores events in the database within the same transaction as the CRUD operation.

• After the CRUD operation, Aidbox collects unsent messages from the database and sends them to the GCP Pub/Sub.

• If an error occurs during sending, Aidbox will continue retrying until the message is successfully delivered. So Aidbox guarantees at least once delivery for an event.

Aidbox topic-based subscriptions

Configuration

To use Webhook with #aidboxsubscriptiontopic you have to create #aidboxtopicdestination resource.

You need to specify the following profile:

http://aidbox.app/StructureDefinition/aidboxtopicdestination-gcp-pubsub-at-least-once

Available Parameters

Parameter name	Value type	Description
projectId *	valueString	GCP project identifier.
topicId *	valueString	The name of the Pub/Sub topic to which you want to publish messages.
timeout	valueUnsignedInt	Set the delay threshold to use for batching. Default value (ms) - 1
maxCount	valueUnsignedInt	Set the element count threshold to use for batching. After this many elements are accumulated, they will be wrapped up in a batch and sent. Aidbox always generates one notification for each event. Therefore, you will receive as many notifications as there are events, but they will be sent in batches. Default value - 100
bytesThreshold	valueUnsignedInt	Set the request byte threshold to use for batching. After this many bytes are accumulated, the elements will be wrapped up in a batch and sent. Default value (bytes) - 1000

* required parameter.

Examples

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

{
  "resourceType": "AidboxTopicDestination",
  "meta": {
    "profile": [
      "http://aidbox.app/StructureDefinition/aidboxtopicdestination-gcp-pubsub-at-least-once"
    ]
  },
  "kind": "gcp-pubsub-at-least-once",
  "id": "gcp-pub-sub-destination",
  "topic": "http://example.org/FHIR/R5/SubscriptionTopic/QuestionnaireResponse-topic",
  "parameter": [
    {
      "name": "projectId",
      "valueString": "project-id"
    },
    {
      "name": "topicId",
      "valueString": "topic-id"
    },
    {
      "name": "timeout",
      "valueUnsignedInt": 1000
    },
    {
      "name": "maxCount",
      "valueUnsignedInt": 4
    },
    {
      "name": "bytesThreshold",
      "valueUnsignedInt": 10000
    }
  ]
}

Status Introspection

Aidbox provides $status operation which provides short status information of the integration status:

Request

GET /fhir/AidboxTopicDestination/<topic-destination-id>/$status
content-type: application/json
accept: application/json

Response

200 OK

{
 "resourceType": "Parameters",
 "parameter": [
  {
   "valueDecimal": 2,
   "name": "messagesDelivered"
  },
  {
   "valueDecimal": 0,
   "name": "messagesDeliveryAttempts"
  },
  {
   "valueDecimal": 0,
   "name": "messagesInProcess"
  },
  {
   "valueDecimal": 0,
   "name": "messagesQueued"
  },
  {
   "valueDateTime": "2024-10-03T07:23:00Z",
   "name": "startTimestamp"
  },
  {
   "valueString": "active",
   "name": "status"
  },
  {
   "name": "lastErrorDetail",
   "part": [
    {
     "valueString": "Connection refused",
     "name": "message"
    },
    {
     "valueDateTime": "2024-10-03T08:44:09Z",
     "name": "timestamp"
    }
   ]
  }
 ]
}

Response format:

Property	Type	Description
messagesDelivered	valueDecimal	Total number of events that have been successfully delivered.
messagesDeliveryAttempts	valueDecimal	Number of delivery attempts that failed. It represents the overall failed delivery attempts.
messagesInProcess	valueDecimal	Current number of events in the buffer being processed for delivery.
messagesQueued	valueDecimal	Number of events pending in the queue for send.
startTimestamp	valueDateTime	AidboxTopicDestination start time in UTC.
status	valueString	AidboxTopicDestination status is always active, which means that AidboxTopicDestination will try to send all received notifications.
lastErrorDetail	part	Information about errors of the latest failed attempt to send an event. This parameter can be repeated up to 5 times. Includes the following parameters.
lastErrorDetail .message	valueString	Error message of the given error.
lastErrorDetail .timestamp	valueDateTime	Timestamp of the given error.

Enable GCP Pub/Sub

To enable Aidbox to send messages to Pub/Sub, you must set up GCP Application Default Credentials in the Aidbox environment.

Running Pub/Sub Integration with a local emulator

Aidbox supports integrating GCP Pub/Sub with a local emulator for testing and development purposes. To set up this, specify the following environment variable in the Aidbox configuration:

BOX_SUBSCRIPTIONS_PUBSUB_EMULATOR__URL=<pub-sub-emulator-url>