On this page:

6.2Channel Types

 

The following sections outline the various channel types (delivery mechanisms) that are supported by Smile CDR.

6.2.1Channel Type: rest-hook

 

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.

6.2.2Channel Type: email

 

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",
    "payload": "An Emergency Department encounter has been created or updated."
  }
}

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).
  • payload – The payload is used as the body of the email.

Email Extensions

HAPI FHIR and Smile CDR provide several extensions that may be placed on the Subscription.channel element:

URLTypeDescription
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",
    "payload": "This is the body."
  }
}

6.2.3Channel Type: websocket

 

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.

6.2.4Channel Type: message

 

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 anamed 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.