On this page:

8.0Channel Import Overview

 

Many health systems already have data stored in FHIR format that you might want to ingest into Smile CDR. While there are tools like ETL Import and CSV Bulk Import, these rely on a static data source, which is often not how you want to have the data ingested. While various mechanisms exist to attempt to push data in real-time from one system to another, the Channel Import module aims to provide a channel-based method of ingesting FHIR data into Smile CDR.

When a Channel Import module is added, it listens to a given named channel provided by a Message Broker. Whenever a message arrives on that channel, the Channel Import module will consume it, and process the message accordingly. There are three types of operations supported by the Channel Import module, which mirror the standard FHIR REST operations; POST, PUT, and DELETE. Since this module is specifically for importing data, it does not support the GET operation.

Some external publisher will publish messages into the channel, and the Channel Import module will consume them. The module supports functionality for retrying failed messages, which is documented in the Message Broker Management section.

8.0.1Enabling and Configuring Channel Import

 

To enable channel import on a Smile CDR instance, several modules must be used together. The following diagram shows how these modules relate to each other.

Channel Import Components

This diagram identifies the modules outlined below.

Cluster Manager Module

The Cluster Manager module contains the configuration used to connect to the selected message broker.

See the Message Broker documentation for information on how to select and configure a message broker. By default an embedded Apache ActiveMQ server will be used, and this is acceptable for testing purposes but an external broker should be used in a production scenario.

FHIR Storage Module

The FHIR Storage module is used as the destination for data coming in from the channel.

Channel Import Module

The Channel Import module subscribes to the channel defined in configuration. It processes incoming messages, and forwards the requests to the FHIR Storage module.

Publishing Messages to a Channel

In order to publish valid messages to the Channel Import channel, they must follow the JSON structure of a ResourceOperationMessage. Here is an example of such a message:

{
   "headers": {
      "customHeaders": {}
   },
   "attributes": {
      "key": "value"
   },
   "transactionId": "f31d9d2f-4857-4344-824a-74c124bbb21f",
   "payload": {
      "operationType": "UPDATE",
      "payload": "{\"resourceType\":\"Patient\",\"id\":\"Patient/G123\",\"name\":[{\"family\":\"Sample\",\"given\":[\"Sample\",\"Samplington\"]}]}"
   }
}
  1. headers – Top-level message headers, which are used to store retry information for subsequent processing attempts.
  2. customHeaders – Any headers added by the user or the messaging system.
  3. transactionId – An optional arbitrary transaction identifier.
  4. payload – The content of the message, containing two elements:
    1. operationType – An OperationTypeEnum, consisting of either UPDATE/DELETE/CREATE. These map to the FHIR operations PUT/DELETE/POST.
    2. payload – An IBaseResource, converted to a string. This is the primary content of the message.

Troubleshooting

The Channel Import Troubleshooting Log can be helpful in diagnosing issues relating to Channel Import. Furthermore, if a message completely fails processing, the cause of the failure is stored along with the failed message.

Examples

The following examples will show how to form ResourceOperationMessages for different use cases you may have.

Transfer a Resource from One System to Another

Posting the following message to the channel would result in the resource being ingested into the storage module.

{
   "headers": {
      "customHeaders": {}
   },
   "payload": {
      "operationType": "CREATE",
      "payload": "{\"resourceType\":\"Patient\",\"name\":[{\"family\":\"Sample\",\"given\":[\"Sample\",\"Samplington\"]}]}"
   }
}

Note that the operationType is set to CREATE, and the resource in the payload has no ID. This is acceptable because the server will ignore any ID in the resource during a create operation.

Transfer a Resource from One System to Another While Preserving the Resource ID

{
   "headers": {
      "customHeaders": {}
   },
   "payload": {
      "operationType": "UPDATE",
      "payload": "{\"resourceType\":\"Patient\",\"id\":\"Patient/G123\",\"name\":[{\"family\":\"Sample\",\"given\":[\"Sample\",\"Samplington\"]}]}"
   }
}

When using operationType UPDATE, the server will attempt to respect and preserve the ID of the resource. Caution must be exercised when using this method as there exists the possibility of conflicting with existing resources on the server.

Deleting a resource via Channel Import

{
   "headers": {
      "customHeaders": {}
   },
   "payload": {
      "operationType": "DELETE",
      "payload": "{\"resourceType\":\"Patient\",\"id\":\"Patient/G123\",\"name\":[{\"family\":\"Sample\",\"given\":[\"Sample\",\"Samplington\"]}]}"
   }
}

When using operationType DELETE, the resource's ID must be present in the payload body. If the resource ID is known to the FHIR Storage module, it will be deleted.