30.2.1CDA REST OperationsExperimental
The rest operations available to use with the CDA Module are fully documented in the CDA Exchange Endpoint section of the docs.
This document will serve as a higher level overview of the available operations.
30.2.2Endpoints for configuring templatesExperimental
After you construct a JavaScript template script to suit your CDA document needs, you will want to add it to the available templates in your CDA module instance.
POST/PUT/DELETE/GET http://localhost:9000/cda/{module_id}/template/{template_id}
module_id: This is the id of the cda module in your instance of Smile.
template_id: This is the id of the cda template you intend to create, update, delete, or view
30.2.2.1Creating a CDA Template
POST/PUT:
You have a script you are happy with and you are ready to upload it to your cda module.
In addition to the script parameter, there are two optional parameters that we recommended you include.
params: An array of strings indicating which parameters the script expects for its input map. What you include here has no bearing on the actual script but serves to help the eventual consumer of your script to know what to include with their request. Example:["patient", "author"]description: A human readable description explaining the purpose of the script, how it works, and the purpose / format it expects for the params.
Example request:
POST http://localhost:9000/cda/{module_id}/template/example
body:
{
"script" : "function generateCdaExchangeComposition(inputMap) {\n var composition = ResourceBuilder.build('Composition');\n composition.title = inputMap['title'];\n return composition;\n}",
"params" : ["title"],
"description" : "A very basic cda template script example"
}
Once posted, you can update any of these three fields with a PUT request to the same URL, delete it with DELETE, or view it with GET
In addition to being able to view a single template, you can view all templates in your CDA module with GET http://localhost:9000/cda/{module_id}/template
30.2.2.2Help! My script has illegal unescaped characters!
If your CDA script has natural new line characters, tabs, or double-quotes, then you can't just paste it into your JSON request body. You could use a tool or manually convert your script to escape special characters and then paste those into your request.
Alternatively, the CDA module has a route designed to work around this issue: PUT http://localhost:9000/cda/{module_id}/template/{template_id}/script.
This route takes an input of type "application/javascript".
This route will add/replace the script in template_id with the code you include as the body of your request.
In order to also populate the description and params fields, you would have to make a call to
PUT http://localhost:9000/cda/{module_id}/template/{template_id} with description and params included in your json body. If using PUT, you can make the calls in either order.
30.2.3Endpoints for applying templatesExperimental
Once your template has been posted to your CDA module, you will likely want to use it! There is a single route for applying a template, and an additional route for creating CDA Documents from an existing Composition or Bundle.
30.2.4Endpoints for importing CDA documentsExperimental
Smile CDR exposes a single custom operation for importing CDA documents.
POST http://localhost:8000/$import-cda
The payload of the operation is a FHIR Parameters resource.
{
"resourceType": "Parameters",
"parameter": [
{
"name": "document",
"valueString": "[The CDA document in XML format]"
}
]
}
If the document is successfully imported, the operation will return a 201 Created response code.
Otherwise, a 4XX or 5XX error code will be returned depending on the type of problem encountered.
In either case, an OperationOutcome resource will be returned containing a list of issues describing any business rule violations encountered during transformation.
The received CCD is recorded on a FHIR DocumentReference resource, which is then persisted, and included in the audit trail. The location of this resource is included in the aforementioned OperationOutcome provided by the endpoint, regardless of whether the import operation was a success.
30.2.5Endpoints for exporting CDA documentsExperimental
30.2.5.1Generate a document from a resource
Smile CDR exposes a custom operation for generating CDA documents. This operation has three forms.
If your repository contains a document Bundle that contains all the resources necessary to generate a CDA document, you can use the operation to convert that Bundle instance to CDA format.
POST http://localhost:8000/Bundle/{bundle_id}/$smile-generate-cda
If your repository contains a document Composition that defines the structure of a document and contains reference to all the necessary resources to include in each section, you can use the operation to export a CDA document based on that
Composition instance.
POST http://localhost:8000/Composition/{composition_id}/$smile-generate-cda
30.2.5.2Apply a template
If your repository does not already contain a Bundle or a
Composition defining your document, you can use the system-level operation to invoke a script that assembles a new Composition.
POST http://localhost:8000/$smile-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"
}
]
}
}
]
}
30.2.5.2.1Parameters
scriptName: the name of the script to be invoked. For details on how to create and update a script, please see the CDA Exchange Endpoint documentation.scriptParameters: a nestedParametersresource that contains the parameters to be passed into the script. The names of these parameters can be anything, but must match the parameters defined for your script. Please see the JavaScript Templates documentation for more details.
The scriptParameters accepted by your script must include a parameter that uniquely and unambiguously identifies a Patient
resource. This can be the resource id, as shown in the example above, or it can be any other unique business key. The
scriptParametrs may also include any other parameters you wish to support in your script. These parameters may be used, for example, to filter the resources to include by date range or by association with a particular encounter. You may also support parameters to populate fields of the Composition itself,
such as specifying a Practitioner or Device to use as the author of the document.
30.2.5.3Persisting intermediate resources
The CDA Exchange+ module offers several configuration parameters for determining whether the intermediate artifacts generated during the document generation process will be retained in the repository or discarded at the end of the process. By default, all these properties are false and nothing is stored in the repository.
- Store Generated Composition
- Store Generated Bundle
- Store Generated CDA Document as Binary
- Store Generated CDA Document as DocumentReference
30.2.5.4Migrating from JSON Admin API to $smile-generate-cda
Prior to release 2025.02.R01, Smile supported the generation of CDA documents using several endpoints on the JSON Admin API.
These endpoints have been removed, and any use of them must be migrated to the new $smile-generate-cda operation.
30.2.5.4.1Migrating generation from resources
The previous endpoint
POST http://localhost:9000/cda/{module_id}/{resource_type}/{resource_id}/apply
must be replaced with one of
POST http://localhost:8000/Bundle/{bundle_id}/$smile-generate-cda
or
POST http://localhost:8000/Composition/{composition_id}/$smile-generate-cda
depending on which resource type is being targeted.
30.2.5.4.2Migrating generation by script
The previous endpoint
POST http://localhost:9000/cda/{module_id}/template/{template_id}/apply
Content-Type: application/json
{
"inputParams": {
"patient": "Patient/1",
"exampleParam2": "30",
}
}
must be replaced with
POST http://localhost:8000/$smile-generate-cda
Content-Type: application/json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "scriptName",
"valueString": "{template_id}"
},
{
"name": "scriptParameters",
"resource": {
"resourceType": "Parameters",
"parameter": [
{
"name": "patient",
"valueString": "Patient/1"
},
{
"name": "exampleParam2",
"valueInteger": "30"
}
]
}
}
]
}
The parameter persistComposition has been replaced by the configuration parameter Store Generated Composition.
The parameter persistFhirDocument has been replaced by the configuration parameter Store Generated CDA Document as DocumentReference.
The remaining parameters of the old endpoint were placeholders with no functionality associated to them, and have been dropped.