# Smile CDR Tutorial - Convert a CDA Document into FHIR Resources The CDA Exchange+ module is a Premium Solution and therefore access requires a separate purchasable license. If you are interested in adding this module, please contact [sales@smiledigitalhealth.com](mailto:sales@smiledigitalhealth.com) for further assistance. **This tutorial has been written using SmileCDR 2025.05.R01.** 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](/content/docs/quickstart/smile_quickstart.html) or [using Docker](/content/docs/guide_installation/docker_container_installation.html). **2\. Start Smile CDR** Start Smile CDR by running the following command: ```bash $ bin/smilecdr start ``` Copy **3\. Access the Web Admin Console** Access the Web Admin Console by navigating to the following URL in your web browser: [http://localhost:9100](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`. **For Smile instances of 2025.05.R01 and up**: set the `import_mode` to `TRANSACTIONAL`. The default setting for CDA Exchange Plus is `DOCUMENT_BUNDLE` which stores the CDA document in a single FHIR document Bundle instead of individual resources. For this tutorial, we want to see the individual resources, however in an actual implementation, it's often recommended to save it as a FHIR document Bundle and separate the resources into individual resources later by taking the various business logic and necessary deduplication steps into account. 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: ```json { "resourceType": "Parameters", "parameter": [\ {\ "name": "document",\ "valueString": "[...],"\ }\ ] } ``` Copy 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/$sdh.import-cda](http://localhost:8000/$sdh.import-cda) Use [this json snippet](/content/docs/guide_tutorials/tutorial_cda_import_json.html) as the body of the POST. It should return a response like the following ```json { "resourceType": "OperationOutcome", "issue": [\ {\ "severity": "information",\ "code": "informational",\ "location": [\ "DocumentReference/1408"\ ]\ },\ {\ "severity": "information",\ "code": "informational",\ "diagnostics": "Persisted received CCD",\ "location": [\ "DocumentReference/1408"\ ]\ }\ ] } ``` Copy **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=\*](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. ## Bonus: 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](/content/docs/cda_exchange_plus/javascript_import_export_hooks.html) or the [Java Interceptors](/content/docs/cda_exchange_plus/javascript_import_export_hooks.html). 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 `` 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](/content/docs/cda_exchange_plus/javascript_import_export_hooks.html#cda-pre-import-scripts/index.html) and the [XML API](/content/docs/javascript_execution_environment/xml.html). 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](/content/docs/cda_exchange_plus/javascript_import_export_hooks.html#cda-post-import-scripts/index.html) 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. [MDM Web UI Admin Setup Tutorial](/content/docs/guide_tutorials/mdm_web_ui_admin_setup.html) CDA Import Tutorial Tutorials [Introduction](/content/docs/guide_tutorials/tutorial_intro.html) [Integration Testing Tutorial](/content/docs/guide_tutorials/tutorial_integration_test.html) [Custom Operations Tutorial](/content/docs/guide_tutorials/tutorial_custom_operations.html) [HL7 v2.x Ingestion Tutorial](/content/docs/guide_tutorials/tutorial_processing_hl7_v2x_feeds.html) [Federated OAuth2/OIDC Tutorial](/content/docs/guide_tutorials/tutorial_federated_oauth2.html) [MDM Tutorial](/content/docs/guide_tutorials/tutorial_mdm.html) [MDM UI Tutorial](/content/docs/guide_tutorials/tutorial_mdm_ui.html) [MDM First Golden Resource Tutorial](/content/docs/guide_tutorials/first_golden_resource.html) [MDM Advanced Rule Authoring Tutorial](/content/docs/guide_tutorials/advanced_rule_authoring.html) [MDM Web UI Admin Setup Tutorial](/content/docs/guide_tutorials/mdm_web_ui_admin_setup.html) [CDA Import Tutorial](/content/docs/guide_tutorials/tutorial_cda_import.html) [CDA Export Tutorial](/content/docs/guide_tutorials/tutorial_cda_export.html) [CDA Export - Custom Narrative Generation Tutorial](/content/docs/guide_tutorials/tutorial_cda_export_narrative_generation.html) [CDA Import JSON example](/content/docs/guide_tutorials/tutorial_cda_import_json.html) [CDA Export Template JSON example](/content/docs/guide_tutorials/tutorial_cda_export_json.html) [Consent Tutorial](/content/docs/guide_tutorials/tutorial_consent.html) [CMS-0057-F IG Setup Tutorial](/content/docs/guide_tutorials/tutorial_terminology_cms57f.html) [CDA Export Tutorial](/content/docs/guide_tutorials/tutorial_cda_export.html)