Aidbox subscriptions module is a way to subscribe and get notifications about updating resources on server. It is a common denominator of FHIR R4/R5 subscriptions specification with some extensions.
This module introduces two new resources into Aidbox:
SubsSubscription — meta-resource which binds events (create/update/delete resource) with communication channel through which subscriber will be notified about changes.
SubsNotification — resource which represents notification with its status (sent or not).
Aidbox doesn't delete SubsNotification resources by itself. Simple way to implement retention policy is creating a cron job. Let us know if there is more clear way.
See tutorial "Subscribe to new Patient resource"
Your service can register subscription by POST SubsSubscription resource:
POST /SubsSubscriptionid: myservice-subsstatus: active # 'active' is default, if 'off' - subscription is disabled# Subscribe to all changes of Patient and Person resourcestrigger:# resource typePatient:event: ['all'] # can be all | create | update | delete# collection of filtersfilter:# use matcho engine to filter resources- matcho: { active: true }Person:event: ['all']# how to deliver notificationschannel:type: rest-hook# url to send hookendpoint: https://myservice/subs/patient# headers to add to request (for consistency use lowercase names)headers:Authorization: Bearer <......># recomended timeout for web hook in ms, server may use it's owntimeout: 1000payload:# this is default value, you can use id-onlycontent: full-resource # full-resource | id-only# means aidbox format, or fhir+json to get resource in FHIR formatcontentType: json # json | fhir+json
Subscription.trigger is a key-value object, where key is resource type and each value can contain collection of events (values can be 'all', 'create', 'update', 'delete') and .filter collection. For now filter support matcho engine (FHIRPath and FHIR Search filters are coming soon):
trigger:Encounter:filter:- matcho: { class: {code: 'inpatient'} }- matcho: { type: { coding: [{code: 'Sometype'}]}
Filter matches if at least one of item in collection matches, i.e. collection has or
semantic.
After you registered subscription, Aidbox sends on channel.endpoint handshake
notification in json format. It's good if your service responds with status: 200
POST https://myservice/subs/patientContent-Type: application/json... channel.headers ...{"type": "handshake","subscription": { ...SubsSubscription resource content... }}
On every trigger event Aidbox will send notification to your service endpoint. Your service has to respond with status: 200
and optional json body.
POST https://myservice/subs/patientContent-Type: application/json... channel.headers ...{"id": <unique-id>,"type": "notification","event": "create", # update | delete"resource": {"resourceType": "Patient", ..... }}
Results of all notifications are logged into SubsNotification resource:
GET /SubsNotification---id: <unique-id>subscription: { id: 'myservice-subs', resourceType: SubsSubscription }duration: 23 # hook duration in msstatus: success # failnotification: <notification content>response: <response content if present>
You can force handshake notification for specific subscription with:
POST /SubsSubscription/<sub-id>/$handshake# responseresourceType: SubsNotificationnotification:type: handshakedebug: truesubscription: ...subscription: {resourceType: SubsSubscription, id: <sub-id>}duration: 1status: failederror: {message: Connection refused}
To debug subscription notifications you can send debug messages with:
POST /SubsSubscription/<sub-id>/$debugid: notif-idevent: createtype: notificationresource:resourceType: Patientid: pt-1# responseresourceType: SubsNotificationnotification:type: notificationresource: {id: pt-1, resourceType: Patient}debug: truesubscription: {resourceType: SubsSubscription, id: <sub-id>}duration: 1status: failederror: {message: Connection refused}
Or you can send list of notifications by providing list of search params:
POST /SubsNotification/$notify?_id=id-1,id-2,id-3
You can resend specific notification with
POST /SubsNotification/<notif-id>/$notify# responsestatus: ...duration: ...notification: ....response: ...
You can subscribe one instance of Aidbox to notifications from another instance and replicate data between boxes by using /subs/webhook/<source-id>
endpoint:
POST /SubsSubscriptionid: box-replicationstatus: activetrigger:Patient: { event: ['all'] }channel:type: rest-hookendpoint: <other-box-url>/subs/webhook/box-1headers:Authorization: Bearer <token>