Tutorial: Subscribe to Topic (R4B)
This tutorial requires configuring your Aidbox instance with a specific SubscriptionTopic for Observation resource. Additionally, a web service that will receive
rest-hook
notifications is required. This Repo contains a suitable template project, which should be used for this tutorial.Use FHIR API to discover available topics. Each topic contains
URL
field which should be specified as a criteria
field of Subscription.Request
Response
GET /fhir/SubscriptionTopic
accept: application/json
{
"resourceType": "Bundle",
"type": "searchset",
"meta": {
"versionId": "0"
},
"total": 1,
"link": [
{
"relation": "first",
"url": "http://localhost:8765/fhir/SubscriptionTopic?page=1"
},
{
"relation": "self",
"url": "http://localhost:8765/fhir/SubscriptionTopic?page=1"
}
],
"entry": [
{
"resource": {
"id": "cf153a1fde850de90215a6cd0f0abcf5",
"url": "http://aidbox.app/SubscriptionTopic/observations",
"meta": {
"slot_name": "tbs_aidbox_with_subscriptions__observation_topic_srv",
"queue_table_name": "observation_topic",
"subscription_status_table_name": "observation_topic_subs_status",
"lastUpdated": "2023-08-31T15:17:40.355938Z",
"versionId": "0",
"extension": [
{
"url": "ex:createdAt",
"valueInstant": "2023-08-31T15:17:40.355938Z"
}
]
},
"status": "active",
"canFilterBy": [
{
"modifier": [
"eq",
"gt",
"lt",
"ge",
"le"
],
"resource": "Observation",
"filterParameter": "value"
},
{
"modifier": [
"eq"
],
"resource": "Observation",
"filterParameter": "value-increase"
}
],
"resourceType": "SubscriptionTopic",
"resourceTrigger": [
{
"resource": "Observation",
"fhirPathCriteria": "%current.value.ofType(Quantity).value > 10"
}
]
},
"search": {
"mode": "match"
},
"fullUrl": "http://localhost:8765/SubscriptionTopic/cf153a1fde850de90215a6cd0f0abcf5",
"link": [
{
"relation": "self",
"url": "http://localhost:8765/SubscriptionTopic/cf153a1fde850de90215a6cd0f0abcf5"
}
]
}
]
}
In response, one configured topic is available, with
"url": "http://aidbox.app/SubscriptionTopic/observations"
.Create a Subscription resource with all the necessary attributes.
Profile
http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription
is required for R4B.Most interesting part are:
"criteria" : "http://aidbox.app/SubscriptionTopic/observations"
- the Topic that a subscription are created for.{"url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-max-count", "valuePositiveInt" : 2}
notification will be delivered immediately when specified number of suitable events is met.{"url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-heartbeat-period", valueUnsignedInt" : 20}
period in seconds when all available to the moment messages will be delivered. if no messages collected - heartbeat event will be fired.{"url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-payload-content", "valueCode" : "id-only"}
notification will only contain ids of resources. The other options arefull-resource
andempty
."endpoint" : "http://subscription-demo-server:9000/callback-test-1"
endpoint to whichPOST
request with notifications will be sent.{"url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-filter-criteria", "valueString" : "Observation?value=42"}
specifies, that only observation withvalue=42
should be delivered for this notification. Available filters or resources may be configured in SubscriptionTopic.
Request
Response
POST /fhir/Subscription
content-type: application/json
accept: application/json
{
"meta" : {
"profile" : [ "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription" ]
},
"criteria" : "http://aidbox.app/SubscriptionTopic/observations",
"channel" : {
"extension" : [ {
"url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-heartbeat-period",
"valueUnsignedInt" : 20
}, {
"url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-timeout",
"valueUnsignedInt" : 60
}, {
"url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-max-count",
"valuePositiveInt" : 2
} ],
"type" : "rest-hook",
"endpoint" : "http://subscription-demo-server:9000/callback-test-1",
"payload" : "application/fhir+json",
"_payload" : {
"extension" : [ {
"url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-payload-content",
"valueCode" : "id-only"
} ]
}
},
"_criteria" : {
"extension" : [ {
"url" : "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-filter-criteria",
"valueString" : "Observation?value=42"
} ]
},
"resourceType" : "Subscription",
"reason" : "R4/B Test Topic-Based Subscription for Observation",
"status" : "requested",
"id" : "test-sub-1",
"end" : "2024-12-31T12:00:00.000-00:00"
}
Status: 201
{
"meta": {
"profile": [
"http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription"
],
"lastUpdated": "2023-08-31T16:30:26.411663Z",
"versionId": "12",
"extension": [
{
"url": "ex:createdAt",
"valueInstant": "2023-08-31T16:30:26.411663Z"
}
]
},
"criteria": "http://aidbox.app/SubscriptionTopic/observations",
"channel": {
"type": "rest-hook",
"payload": "application/fhir+json",
"extension": [
{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-timeout",
"valueUnsignedInt": 60
},
{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-max-count",
"valuePositiveInt": 4
},
{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-heartbeat-period",
"valueUnsignedInt": 120
}
],
"_payload": {
"extension": [
{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-payload-content",
"valueCode": "id-only"
}
]
},
"endpoint": "http://localhost:27193/callback-url"
},
"_criteria": {
"extension": [
{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-filter-criteria",
"valueString": "Observation?value=10"
}
]
},
"resourceType": "Subscription",
"reason": "R4/B Test Topic-Based Subscription for Observation",
"status": "requested",
"id": "test-sub-id",
"end": "2024-12-31T12:00:00.000-00:00"
}
As a result of this step Aidbox will try to perform a handshake with the subscriber service. By default Aidbox expects
Status:200
response.You may notice
handshake
event in demo server UI:
After the successful handshake, the status of the Subscription will be
active
.Request
Response
GET /fhir/Subscription/test-sub-id/$status
content-type: application/json
accept: application/json
Status: 200
{
"resourceType": "Bundle",
"type": "history",
"timestamp": "2023-08-31T16:33:59.161865Z",
"entry": [
{
"resource": {
"resourceType": "SubscriptionStatus",
"status": "active",
"type": "query-status",
"eventsSinceSubscriptionStart": 0,
"subscription": {
"reference": "http://localhost:8765/fhir/Subscription/test-sub-id"
},
"topic": "http://aidbox.app/SubscriptionTopic/observations",
"error": []
}
]
}
}
]
}
Aidbox will attempt a handshake with the service three times at 10-second intervals. If no successful response is received, the subscription will be shifted to an
"errored"
status. To restart the process, the subscription should be deleted and recreatedLast modified 1mo ago