12.8.1Smile CDR Tutorial - Export a CDA document from the SmileCDR repository

This step-by-step tutorial will guide you through the process of exporting CDA documents from Smile CDR, it starts from the beginning with installing SmileCDR and setting up the CDA module.

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 following permissions to the user account that needs to export CDA documents:

• CREATE_CDA_TEMPLATE
• USE_CDA_TEMPLATE
• DELETE_CDA_TEMPLATE
• VIEW_CDA_TEMPLATE

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. Creating a CDA template

The generateCdaExchangeComposition() function is used to build the Composition upon which the CDA will be built. More information on properly building a Composition can be found under the CDA Module Mappings for Export as well as the CDA JavaScript Templating System.

8. Upload CDA export template

Note, this tutorial assumes there is already data in the repository, if no CDAs have been ingested yet, please consult the CDA import tutorial before returning to this page.

Upload the template of your preference to the template endpoint with the template in the body of the request. The template will have to be converted to a JSON format put together, the full call should resemble the following structure:

PUT http://localhost:9000/cda/{module_id}/template/{template_id}
Content-Type: application/json
{
    "id": "default-ccd-template",
    "script": "function generateCdaExchangeComposition(inputMap) {[...]}",
	 "params": ["Patient"],
    "description": "Aggregate CCD Template"
    }

module_id: is the id of the CDA Exchange Plus module in SmileCDR template_id: is the id of the CDA template you intend to create, update, delete or view.

Just like before, special characters will require escaping.

An example CCD template JSON body can be found here. Upload this to the endpoint as mentioned above.

The default-ccd-template id is special as this is the id that will be used when using the $docref endpoint.

Upon successful ingestion, a 200 OK will be displayed.

9. Export a CDA

There are three ways to create a new CDA document:

Method 1: $sdh.generate-cda

The $sdh.generate-cda endpoint allows a user to specify which CDA template they want to apply to the Patient via the valueString under the "name": "scriptName". More information can be found in Endpoints for exporting CDA documents.

POST http://localhost:8000/$sdh.generate-cda
Content-Type: application/json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "scriptName",
      "valueString": "my_script_name"
    },
    {
      "name": "scriptParameters",
      "resource": {
        "resourceType": "Parameters",
        "parameter": [
          {
            "name": "patient",
            "valueString": "Patient/123"
          },
          {
            "name": "startDate",
            "valueDate": "2024-01-01"
          }
        ]
      }
    }
  ]
}

Upon successful creation of a CDA document, the return will be a 200 OK along with the following body:

{
	"resourceType": "Bundle",
	"type": "searchset",
	"entry": [
		{
			"resource": {
				"resourceType": "DocumentReference",
				"status": "current",
				"subject": {
					"reference": "Patient/1413"
				},
				"content": [
					{
						"attachment": {
							"contentType": "text/plain",
							"data": "PD94bWwgdmVyc2lvbj0nMS4wJOnhzaT0i[redacted]",
							"url": "/Binary/1452",
							"title": "Uri where the data can be found: [base]/Binary/1452"
						}
					}
				]
			}
		}
	]
}

Where the data will contain the generated CDA in base64 encoding and url will contain a Binary resource with the generated XML CDA document.

Method 2: using a Bundle or Composition resource

In the event a Bundle or Composition resource already exists for the generation of the CDA document, the resource itself can be converted into the CDA format.

For generating a CDA document via a Bundle resource the following API call is used. This method assumes the Bundle resource contains all the resources necessary to generate a CDA document:

POST http://localhost:8000/Bundle/{bundle_id}/$sdh.generate-cda

For generating a CDA document via a Composition resource, the following API call is used. This method assumes the Composition resource defines the structure of a document and contains references to all the necessary resources to include in each section.

POST http://localhost:8000/Composition/{composition_id}/$sdh.generate-cda

On success, the output will be similar to the output in $sdh.generate-cda.

Method 3: DocumentReference/$docref

This method will be changing significantly in SmileCDR versions 2025.02 and upwards

The DocumentReference/$docref operation uses the default-ccd-template template to generate a CDA document with. It requires the input parameter patient which corresponds with the id of the Patient for whom the document will be generated. No other input parameters will be accepted.

POST http://localhost:8000/DocumentReference/$docref
Content-Type: application/json
{
   "resourceType": "Parameters",
   "parameter": [
      {
         "name": "patient",
         "valueId": "Patient/1413"
      }
   ]
}

On success, the output will be similar to the output in $sdh.generate-cda.

Putting it all together

With this knowledge, identify a Patient in your repo via

GET http://localhost:8000/Patient

Take its id and perform a CDA export first using $sdh.generate-cda with the id default-ccd-template.

In order to generate from a Composition find a Composition resource via

GET http://localhost:8000/Composition

Use this Composition to generate a CDA document via the Composition based $sdh.generate-cda route.

For more information on the various CDA endpoints, visit our documentation.