C-CDA
This page describes C-CDA built-in module which provides API to convert C-CDA documents to FHIR documents and backward.
Last updated
Was this helpful?
This page describes C-CDA built-in module which provides API to convert C-CDA documents to FHIR documents and backward.
Last updated
Was this helpful?
The HL7 Clinical Document Architecture (CDA) is an XML-based markup standard intended to specify the encoding, structure and semantics of clinical documents for exchange. It’s the most widely used format for health information exchange in the US today. To help developers to comply with § 170.315(g)(9) ONC criterion Aidbox provides endpoint to convert CCDA documents to FHIR format.
Aidbox C-CDA converter aims to handle all data elements included into , more recent USCDI versions will be supported later.
To perform C-CDA to FHIR conversion without storing FHIR resources in the Aidbox database, use the /ccda/to-fhir endpoint. Simply POST C-CDA XML document in request body as in the following example:
Please note theContent-Type: application/cda+xml header. Any other MIME type will be rejected by this endpoint.
In case of error, OperationOutcome resource will be returned:
There are several options you may pass to the /ccda/to-fhir endpoint. Options are passed as query string parameters, i.e. /ccda/to-fhir?option1=value1&option2=value2.
format
aidbox | fhir
Default: fhir
sections
Comma-separated list of section aliases to process. By default all sections are processed.
Options are passed as query-string parameters, i.e. /ccda/persist?create-docref=true&option2=value2. sections are passed separated by commas, i.e. /ccda/persist?section=dicom,goals,findings.
create-docref
true | false
Default: false
Specifies if a DocumentReference resource is needed to store original XML document.
tenant-id
ID of Tenant resource Default: none
sections
Comma-separated list of section aliases to process. By default all sections are processed.
Below is the list of section aliases and their corresponding OIDs. Section aliases are used to configure C-CDA endpoints to specify a list of sections to process.
dicom
2.16.840.1.113883.10.20.6.1.1
findings
2.16.840.1.113883.10.20.6.1.2
assesment
2.16.840.1.113883.10.20.22.2.8
goals
2.16.840.1.113883.10.20.22.2.60
problems
2.16.840.1.113883.10.20.22.2.5.1
health-concerns
2.16.840.1.113883.10.20.22.2.58
medications
2.16.840.1.113883.10.20.22.2.1.1
medical-equipment
2.16.840.1.113883.10.20.22.2.23
immunizations
2.16.840.1.113883.10.20.22.2.2
2.16.840.1.113883.10.20.22.2.2.1
2.16.840.1.113883.10.20.22.4.52
payers
2.16.840.1.113883.10.20.22.2.18
vital-signs
2.16.840.1.113883.10.20.22.2.4.1
social-history
2.16.840.1.113883.10.20.22.2.17
procedures
2.16.840.1.113883.10.20.22.2.7.1
encounters
2.16.840.1.113883.10.20.22.2.22.1
notes
2.16.840.1.113883.10.20.22.2.65
1.3.6.1.4.1.19376.1.5.3.1.3.5
plan-of-treatment
2.16.840.1.113883.10.20.22.2.10
careteam
2.16.840.1.113883.10.20.22.2.500
allergies
2.16.840.1.113883.10.20.22.2.6.1
results
2.16.840.1.113883.10.20.22.2.3.1
Aidbox provides an endpoint to check correctness of C-CDA document. Despite the fact that C-CDA to FHIR conversion can be performed even on invalid C-CDA document (with undefined result), there are some use cases when you want to validate C-CDA document first. For instance, you can use this endpoint to check user-submitted document and reject if it's not valid.
There are two stages of C-CDA validation:
Structural validation (XSD) which checks that XML tree is properly formed
Schematron validation that checks the presence of data elements required by C-CDA specification
By default both stages are performed.
The following example demonstrates how to use validation endpoint:
If validation was successful, you will get the following response:
In case of failed validation endpoint will return a list of errors and warnings:
Options are passed as query-string parameters, i.e. /ccda/validate?option1=value1&option2=value2.
method
xsd | schematron | both
Default: both
Type of validation to perform.
If conversion was successful, you'll get a as a result. Accordingly to the FHIR Documents specification, the first resource in the resulting bundle is containing document header information as well as the list of document sections.
Please note that this endpoint doesn't persist any populated FHIR data to Aidbox database. This endpoint is read-only and it performs a stateless conversion of the document from one format to another. To persist FHIR data extracted from a C-DDA document proceed to the section.
of resulting FHIR document. It's FHIR by default.
Proceed to the table to find all possible values. Default: all
If you wish to store C-CDA to FHIR conversion results in the Aidbox database, use /ccda/persist endpoint. After converting C-CDA document to FHIR document, this endpoint produces to create or update existing resources. According to its transactional nature, any single failure in this transaction bundle will rollback a whole transaction and nothing will be saved. The following example demonstrates how to use /ccda/persist endpoint.
Additionally to the FHIR resources converted from C-CDA data, this endpoint will create resource which will contain references to all resources created or updated during single /ccda/persist call. It's useful to have such list to get all FHIR resources related to the specific C-CDA document. For instance, to wipe them out from the database.
Also, if create-docref option is provided, this endpoint will create a resource which will contain a base64-encoded copy of the original C-CDA XML document in it's content attribute. It's useful when you want to store original document in the Aidbox database for various rare use-cases. By default, create-docref option is set to false, so no DocumentReference resource is created.
For users only. Assigns Tenant to all populated resources.
Proceed to the table to find all possible values. Default: all
On only XSD validation is performed. Uploaded XML file will be highlighted with green color if the document is valid, red otherwise.