On this page:
  • Implementation
  • 11.0 CDA Exchange Plus Import Implementation
    • Table of Contents

    CDA Exchange Plus Import Implementation

    11.0.1Implementation of CDA Exchange Plus Import

     

    This document details some basic configuration settings to use when setting up CDA Exchange Plus.

    Before implementing, it is strongly recommended the planning document for CDA is reviewed to ensure the necessary considerations have been made for a smooth implementation and testing/validating of the CDA Exchange Plus.

    11.0.1.1Checklist

    ✔ Install SmileCDR
        ✔ add licence to enable CDA Exchange Plus
    ✔ configure CDA Exchange Plus Module with the licence - if already configured, skip this section
        ✔ if using Helm charts, go to: method 1, skip other methods
        ✔ if using Docker or Properties mode, go to: method 2, skip other methods.
        ✔ if using WebAdmin Console, go to: method 3, skip other methods
    ✔ configure Message Broker - if already configured, skip this section
        ✔ if using Channel Import, go to: Channel Import
        ✔ if using Camel, go to: Camel
           ✔ configure camel routes
    ✔ Troubleshooting CDA Exchange Plus

    11.0.1.2Installing SmileCDR and configuring the CDA Exchange Plus

    1. Install SmileCDR

    SmileCDR can be installed via a couple of ways, via tarball, using Docker, or using helm chart.

    It is recommended the latest version of smileCDR is used with CDA Exchange Plus, at minimum 2025.02.R01 or later.

    1. Add License

    CDA Exchange Plus is a premium module, as such a license is required in order for it to work. The licence can be added via helm chart, properties file or via the webadmin console.

    Via Helm chart The SmileCDR licence is a regular JWT token and can be stored in an AWS Secrets Manager Secret under the jwt key in the JSON object. It can then be added to the values file via the following as defined by the secretSpec schema:

    license:
 type: sscsi
 provider: aws
 secretArn: arn:aws:secretsmanager:us-east-1:111111111111:secret:my-smile-license

    Properties file The properties file can take either a location to the file containing the JWT token (JWT_file), or the JWT token directly (JWT_token).

    module.license.type=LICENSE

module.license.config.jwt_file=
module.license.config.jwt_text={JWT_token}

    Webadmin console In the webadmin console, navigate to: Configuration >> Module Config >> license.
    Under this module there are two settings: License JWT File will allow you to point to the file containing the JWT token, while License JWT Text will allow you to paste the JWT token directly into the module.

    Once a selection has been made, save the config and restart the module. If all has gone correctly, the UI should update and list which modules the license allows access to.

    1. Configuring the CDA Exchange Plus module

    The CDA Exchange Plus module can be configured in a few different ways:

    Method 1: Via helm chart SmileCDR’s helm chart implementation allows for a simplified installation and configuration of SmileCDR on Kubernetes using a number of best practices. This allows you to not just configure SmileCDR but the environment around it as well.

    The following code must be added to the values.yaml file in order for the helm chart to properly configure the CDA Exchange Plus module, the properties must fall under the modules: header:

    {module_id}:
 name: CDA EXCHANGE PLUS
 enabled: true
 type: CDA_EXCHANGE_PLUS
 requires:
      PERSISTENCE_ALL: {module_id_of_persistence_module}
    config:
      target_ig: {IG_type}
      ecmascript_module: false
      prefer_supplied_translations: false
      store_original_ccd: true
      cda_processing_script.file: {processing_script_file_location}
      interceptor_bean_types: {interceptor_bean}

    Where:

    • {module_id} is the name you gave the CDA Exchange Module
      • {module_id_of_persistence_module} is the name of your persistence module
      • {IG_type} is the IG the CDA Module will map against, there are currently three IGs available: US_CORE_IG, FHIR_CORE_PROFILE and USCDI_V2.
      • OPTIONAL: {processing_script_file_location} is the location of the JavaScript processing script for CDA
      • OPTIONAL: {interceptor_bean} is the name of the interceptor class for the CDA Exchange Plus Java Interceptor

    Once all has been configured the helmchart can be spun up as usual.

    Method 2: Via the Properties file If you are installing SmileCDR via Docker or tarball using [Properties Mode](/docs/guide_installation/configuring_smile_cdr.html#module-property-source). The following properties in the cdr-Master-config.properties file must be set:

    • Module.license.config.jwt_text - should contain the SmileCDR licence for CDA Exchange Plus (and any subsequent other licenced modules you may be using)
      module.cda_exchange_plus.type=CDA_EXCHANGE_PLUS
    • The following CDA Exchange Plus module settings must also be set where:
      • {module_id} is the name you gave the CDA Exchange Module
      • {module_id_of_persistence_module} is the name of your persistence module
      • {IG_type} is the IG the CDA Module will map against, there are currently three IGs available: US_CORE_IG, FHIR_CORE_PROFILE and USCDI_V2.
      • OPTIONAL: {processing_script_file_location} is the location of the JavaScript processing script for CDA
      • OPTIONAL: {interceptor_bean} is the name of the interceptor class for the CDA Exchange Plus Java Interceptor
    module.{module_id}.type=CDA_EXCHANGE_PLUS
module.{module_id}.config.store_original_ccd=true
module.{module_id}.requires.PERSISTENCE_ALL={module_id_of_persistence_module}
module.{module_id}.config.target_ig={IG_type}
module.{module_id}.config.cda_processing_script.file={processing_script_file_location}
module.{module_id}.config.interceptor_bean_types={interceptor_bean}\

    Once the properties have been configured if configured via tarball run the following command to spin up SmileCDR: bin/smilecdr start
    If spinning up via Docker, run the docker command to start up the pods.

    Method 3: Via the webadmin console This method requires SmileCDR to already be running in the environment.

    1. Run SmileCDR by running the following command:
      bin/smilecdr start
    2. Navigate to the Web Admin Console via http://localhost:9100 or the domain URL used for it.
    3. Install the license: Configuration >> Module Config >> License, paste the licence key into Licence JWT Text, click Save Config and restart the License module.
    4. Navigate back to the main WebAdmin Console page via Configuration >> Module Config >> Add Module 5. Select CDA Exchange+ from the dropdown menu and select Add.
    5. In Dependencies, under FHIR Storage Module (any FHIR version) select the persistence module used for your database.
    6. Click Create Module.
    7. Optionally, script and interceptor can be added via the webadmin console as well under the appropriate headers.

    11.0.1.3Adding Message brokers

    CDA Exchange Plus by default uses REST API to ingest CCDs via the $import-cda operation. However, it is possible to have CDA documents ingested via a Message broker.

    SmileCDR currently has two modules that can be used for message brokers, Channel Import and Camel.

    Pre-requisites: Kafka must be set up prior to configuring Channel Import or Camel.

    11.0.1.3.1Configuring Channel Import

    Using the same methods as mentioned above, Channel Import can be added via the following methods:

    Yaml/helm chart:
    When using the helm chart method of Smile implementation, the kafka message broker can be configured within the helm chart, please consult the     SmileCDR Helm Chart docs for more information on configuring Kafka within helm.

    The module itself is added to the helm chart using the following structure:

    {module_id}:
    name: Channel CDA Exchange Plus
    enabled: true
    type: CHANNEL_IMPORT
    requires:
      PERSISTENCE_ALL: {persistence_module_id}
      CDA_EXCHANGE: {cda_exchange_plus_module_id}

    Properties file:

    module.{module_id}.type=CHANNEL_IMPORT

module.{module_id}.requires.CDA_EXCHANGE={cda_exchange_plus_module_id}
module.{module_id}.requires.PERSISTENCE_ALL={persistence_module_id}
module.{module_id}.config.channel.retry.delay_milliseconds=2000
module.{module_id}.config.channel.retry.maximum_delay_milliseconds=2000
module.{module_id}.config.channel.retry.maximum_attempts=5
module.{module_id}.config.channel.concurrent_consumers=8
module.{module_id}.config.default_mediatype=application/fhir+json
module.{module_id}.config.channel.name={channel_name}
module.{module_id}.config.channel.failed.name={failure_channel_name}
module.{module_id}.config.channel.retry.name={retry_channel_name}
module.{module_id}.config.interceptor_bean_secure_context=false

    {channel_name}, {failure_channel_name} and {retry_channel_name} must be filled in for the module to start correctly.
    The requires.CDA_EXCHANGE field must be populated with the ID of the CDA Exchange Plus module for Channel Import to be correctly hooked up to the module.

    Method 3: Webadmin Console

    1. In the webadmin console, under Configuration >> Module Config >> Add Module, select Channel Import and click Add 2. Name the module (default name is: channel_import though it’s recommended you highlight it’s the CDA Channel Import module. Ie. cda_channel_import or cda_import) 3. Fill in the properties Channel Name, Retry Channel Name, Failure Channel Name and under Dependencies choose the CDA Exchange+ module under CDA Exchange+ module (optional).
    2. Create Module and start.

    11.0.1.3.2Configuring Camel

    Yaml/helm chart:

    {module_id}:
    name: Channel CDA Exchange Plus
    enabled: true
    type: CAMEL
    requires:
      PERSISTENCE_ALL: {persistence_module_id}
    config:
      routes.script.file: {file_location}
      functions.script.file: {functions_script_location}

    Configuration file

    module.camel.type=CAMEL

module.camel.requires.PERSISTENCE_ALL=persistence
module.camel.config.routes.script.text=
module.camel.config.interceptor_bean_secure_context=false
module.camel.config.routes.script.file={file_location}

    Webadmin console Under Configuration >> Module Config >> Add Module, select Camel and click Add.

    Under Dependencies select the persistence module of choice.

    Save module config and start the module.

    Configuring the Camel routes

    Under Camel Routes (Text) (routes.script.text) or Camel Routes (File) (routes.script.file). The appropriate routes need to be set for Camel to correctly identify which broker topic it needs to be listening to and where to direct the messages from the broker towards.

    Example Camel route:

    <route>
    <from uri="smile:clustermgr/broker?topic=cda"/>
    <to uri="smile:camel/script?function=processKafkaMessage" />
    <to uri="smile:cda_exchange_plus/cdaToFhirPreConvertScriptProcessor"/>
    <to uri="smile:cda_exchange_plus/cdaToFhirPreConvertInterceptorProcessor"/>
    <to uri="smile:cda_exchange_plus/cdaToFhirProcessor"/>
    <to uri="smile:cda_exchange_plus/cdaToFhirPostConvertInterceptorProcessor"/>
    <to uri="smile:cda_exchange_plus/cdaToFhirPostConvertScriptProcessor"/>
    <choice>
        <when>
            <spel>#{body.isDoProcess()}</spel>
            <setBody>
                <spel>#{body.bundle}</spel>
            </setBody>
            <to uri="smile:persistence/bundleProcessor"/>
        </when>
    </choice>
</route>

    For this given Camel route, the data from Kafka topic cda (clustermgr/broker) is passed through the CDA Exchange flow and stored in the persistence module with the specified partition (persistence/bundleProcessor).

    Between these two events the data is passed through a Camel script camel/script?function=processKafkaMessage the CDA Exchange Plus processors JavaScript and Java Interceptors (cda_exchange_plus/* , cdaToFhirPreConvertInterceptorProcessor, cdaToFhirProcessor, cdaToFhirPostConvertInterceptorProcessor, cdaToFhirPostConvertScriptProcessor). After all conversions have taken place the data is in the format cdaToFhirConversionResultJson which is not accepted by the bundleProcessor therefore, the last part of the routes converts the body into the IBaseBundle format for use in bundleProcessor.

    Note that all pre- and post-processing processors, both JavaScript and Java are optional! If no processors are necessary these processors can be removed.

    The processKafkaMessage processor extracts the XML string from the kafka message via the following function:

    function processKafkaMessage(string) {
    return (JSON.parse(string)).payload.payload;
}

    Where the incoming data is assumed to be of the following format:

    {
	"payload": {
		"transactionId": "a0c42c2b-43e9-4e09-8cf2-be3a7b95fb19",
		"mediaType": "text/xml+cda",
		"payload": "<?xml-stylesheet type=\"text/xsl\" href=\"CCDA.xsl\" alternate=\"no\" title=\"Allscripts Default\" ?><?xml-stylesheet type=\"text/xsl\" href=\"ccda.xsl\"?><ClinicalDocument xmlns=\"urn:hl7-org:v3\" xmlns:sdtc=\"urn:hl7-org:sdtc\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"><realmCode code=\"US\"/><typeId root=\"2.16.840.1.113883.1.3\" extension=\"POCD_HD000040\"/><templateId root=\"2.16.840.1.113883.10.20.22.1.8\" extension=\"2015-08-01\"/><templateId root=\"2.16.840.1.113883.10.20.22.1.8\"/><templateId root=\"2.16.840.1.113883.3.3251.1.1\"/><templateId root=\"2.16.840.1.113883.10.20.22.1.1\" extension=\"2015-08-01\"/><templateId root=\"2.16.840.1.113883.10.20.22.1.1\"/><templateId root=\"1.3.6.1.4.1.19376.1.5.3.1.5.5.1\"/><templateId root=\"1.3.6.1.4.1.19376.1.5.3.1.5.5.2\"/><templateId root=\"2.16.840.1.113883.10.20.22.1.2\"/></ClinicalDocument>"
	}
}

    11.0.1.4Troubleshooting CDA Exchange Plus

    CDA Exchange Plus has its own troubleshooting log that can be enabled via the customerlib/logback-smile-custom.xml
    The following line should be uncommented

    	<!-- <logger name="ca.cdr.log.cda_troubleshooting" level="DEBUG"/> -->
  • Implementation
  • 11.0 CDA Exchange Plus Import Implementation