Channel Types
The following sections outline the various channel types (delivery mechanisms) that are supported by Smile CDR.
The rest-hook channel type specifies that Smile CDR should create an HTTP REST request to a FHIR endpoint any time that a resource changes that matches the given subscription.
For example, suppose a Subscription is created with the following values:
{
"resourceType": "Subscription",
"status": "requested",
"criteria": "Patient?name=smith",
"channel": {
"type": "rest-hook",
"endpoint": "http://example.com:8080/fhir",
"payload": "application/json"
}
}
In this case, if a new Patient is created with the name "Smith", and the FHIR Storage module assigns it an ID of 123, an HTTP PUT will be performed to the address http://example.com:8080/fhir/Patient/123 with the resource body as the payload.
The email channel type uses an SMTP relay to deliver notification about changed resources to the recipient. The contents, recipient, and body of the transmitted email may be specified using properties in the Subscription.
For example, the following example shows a simple email subscription:
{
"resourceType": "Subscription",
"status": "requested",
"reason": "Monitor new emergency department encounters",
"criteria": "Encounter?class=http://hl7.org/fhir/v3/ActCode|EMER",
"channel": {
"type": "email",
"endpoint": "mailto:foo@example.com"
}
}
Note the following fields:
endpoint – The endpoint must be set to a `mailto:` URI that will be treated as the recipient email address. Additional recipients may be specified by using comma-separated values (e.g. mailto:recipient1@example.com,recipient2@example.com).
HAPI FHIR and Smile CDR provide several extensions that may be placed on the Subscription.channel element:
| URL | Type | Description |
|---|---|---|
| http://hapifhir.io/fhir/StructureDefinition/subscription-email-from | uri | If specified, this extension contains the "from" address that the email will show as the sender. |
| http://hapifhir.io/fhir/StructureDefinition/subscription-email-subject-template | string | If specified, this extension contains the subject of the email being sent. |
An example resource including these extensions is shown below.
{
"resourceType": "Subscription",
"status": "requested",
"reason": "Monitor new emergency department encounters",
"criteria": "Encounter?class=http://hl7.org/fhir/v3/ActCode|EMER",
"channel": {
"extension": [
{
"url": "http://hapifhir.io/fhir/StructureDefinition/subscription-email-from",
"valueUri": "mailto:myfrom@from.com"
},
{
"url": "http://hapifhir.io/fhir/StructureDefinition/subscription-email-subject-template",
"valueString": "This is a subject."
}
],
"type": "email",
"endpoint": "mailto:foo@example.com"
}
}
Websocket subscriptions are useful when the endpoint that needs to be notified has a user-interface like a web application or a mobile app. When a websocket subscription is activated on Smile CDR, the Smile CDR opens a websocket that listens for client websocket connections. When a client connects, the client indicates a subscription id it is interested in and then when incoming resources match that subscription, Smile CDR will notify the client over that websocket. This can be useful, for example, a in resource dashboad application that need to be refreshed as new resources arrive: rather than the costly overhead of constantly polling the server for new records; the client can just sit and wait to be notified of changes.
For example, suppose a Subscription is created with the following values:
{
"resourceType": "Subscription",
"status": "requested",
"criteria": "Patient?name=smith",
"channel": {
"type": "websocket"
}
}
To be notified of matches to this subscription (i.e. all new and updated Patients with the name "Smith"), you would create a websocket client and attach it to the endpoint you specified in the Websocket Subscription module. For example, if your Websocket Subscription is configured with a port of 9333 and a Context Path of /websocket, then if you are connecting locally, your websocket client would connect to ws://localhost:9333/websocket. After connecting, the websocket client sends a bind :id message to the server where :id corresponds to the id of the subscriptiuon your client needs to be notified about. If the bind is successful, the server will send back bound :id. From then on, whenever a match occurs, the server sends the message ping :id to the websocket client. Typically, the client would then go back to the FHIR Endpoint and retrieve the resource(s) it is interested in. A client can use the :lastUpdated parameter if it only wants to catch-up to new matching resources that arrived since the last time it queried the server.
The message channel type specifies that Smile CDR should submit the matched resource to the named broker channel (e.g. the named JMS queue or a named Kafka topic).
For example, suppose a Subscription is created with the following values:
{
"resourceType": "Subscription",
"status": "requested",
"criteria": "Patient?name=smith",
"channel": {
"type": "message",
"endpoint": "channel:my-queue-name",
"payload": "application/json"
}
}
In this case, if a new Patient is created with the name "Smith", and the FHIR Storage module assigns it an ID of 123, a ResourceModifiedJsonMessage will submitted to the "my-queue-name" queue.