10.5.1Smile CDR Tutorial - Convert a CDA Document into FHIR Resources

This step-by-step tutorial will guide you through the process of importing CDA documents into Smile CDR.

1. Install Smile CDR

Install Smile CDR either from a tarball or using Docker.

2. Start Smile CDR

Start Smile CDR by running the following command:

$ bin/smilecdr start

3. Access the Web Admin Console

Access the Web Admin Console by navigating to the following URL in your web browser: http://localhost:9100

Log in with the default credentials "admin", "password".

4. Install your license

Navigate to Configuration Module Config and click on license on the left hand side.

Paste your license key into License JWT Text.

Click Save Config.

Click Restart to restart the License module.

5. Add a CDA Exchange+ Module

In the Web Admin Console, navigate to Configuration Module Config and click the Add Module button.

Select the CDA Exchange+ module and click Add.

Scroll to the Dependencies section at the bottom and set FHIR Storage Module (any FHIR version) to persistence (FHIR Storage (R4 RDBMS))

Click Create Module.

Click Start to start the CDA Exchange+ module.

Verify that the module is running by checking there is a green checkmark beside cda_exchange_plus on the bottom left. If the module failed to start, there will be an error displayed on the top of the Module Config page, e.g. you will see InsufficientLicenseException if your license doesn't grant access to the CDA Exchange+ module.

6. Grant Permissions

In a proper setup, we'd add the IMPORT_CDA (Import CDA Documents) permission to the user account that needs to import CDA documents. But since we're just in a quickstart testing environment, we will simply grant superuser permissions to the anonymous user:

Navigate to Users & Authorization User Management.

Beside the ANONYMOUS user, click on Edit.

Enable the ROLE_FHIR_CLIENT_SUPERUSER (FHIR Client (Superuser)) permission and click Save User

7. Import a CDA Document

Although CDA documents are in XML format, they must be converted to a JSON structure in order to be sent to SmileCDR. See below for an example of the format:

{
	"resourceType": "Parameters",
	"parameter": [
		{
			"name": "document",
			"valueString": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?>[...],"
		}
	]
}

Note that special characters such as \ and " will need to be escaped. Instances of \r\t should be removed and \r\n should be replaced with \\n to maintain newlines.

Using a REST client such as Bruno or Postman, import a CDA document by sending a POST request to the following URL: http://localhost:8000/$import-cda

Use this sample CDA Import Json as the body of the POST.

It should return a response like the following

{
	"resourceType": "OperationOutcome",
	"issue": [
		{
			"severity": "information",
			"code": "informational",
			"location": [
				"DocumentReference/1408"
			]
		},
		{
			"severity": "information",
			"code": "informational",
			"diagnostics": "Persisted received CCD",
			"location": [
				"DocumentReference/1408"
			]
		}
	]
}

8. View the FHIR documents generated from the CDA Document

Using the DocumentReference id returned from the last step, you can request all FHIR resources generated by the CDA document with a query like the following: http://localhost:8000/Provenance?entity=DocumentReference/1408&_include:iterate=*

For this example CDA, the response Bundle will contain the following resources:

• 1 Provenance resource that records the generation of the FHIR resources from the CDA document
• 2 DocumentReference resources. One that contains the original CDA document and the other that contains clinical notes from the CDA
• 1 Composition resource that lists references to all of the generated FHIR resources organized into sections
• 1 Patient resource
• 2 Organization resources
• 1 Location resource
• 1 CareTeam resource
• 5 Practitioner resources
• 4 Encounter resources
• 2 AllergyIntolerance resources
• 4 DiagnosticReport resources
• 20 Observation resources
• 1 MedicationStatement resource
• 1 Immunization resource

for a total of 46 resources.

10.5.1.1Bonus: Using the pre- and postprocessing CDA hooks

Identify use case

There are a number of ways to alter the CDA or the resulting transaction bundle be it through the JavaScript hooks or the Java Interceptors. When considering which method to use, complexity should be considered. Below are some example scenarios:

Scenario A: SSN removal

The SSN node is located in the <patientRole> and may not always contain the SSN but rather a placeholder. This information is not informative and may be elected to be removed.

Because this is a simple find and remove action, a JavaScript script using the onPreImportCda JavaScript hook and the XML API. Where the SSN node is located in the /ClincalDocument/recordTarget/patientRole section of the CCD using the SSN root (2.16.840.1.113883.4.1).

Scenario B: Restructuring the transaction bundle

Restructuring the transaction bundle postprocessing is a complex and delicate task, although there is a onPostImportCda JavaScript pointcut it is recommended to only use this for small changes such as adding an identifier or changing request methods. If it has to do with editing references in the bundle, a Java interceptor is recommended to avoid interference between the JavaScript and Java layers.