# Translating between CDA and FHIR

<u>**Clinical Document Architecture**</u> (<u>**CDA**</u>) is a common HL7 standard, based on XML. It’s used for exchanging general clinical documents, including discharge summaries, visit summaries, or other documents with a patient’s history or treatment. [Read about CDA](https://redoxengine.com/blog/ccd-cda/). 

However, FHIR is a modern, adaptable, and quick way to exchange general clinical data ([learn about the Redox FHIR API](/basics/redox-fhir-api)). Sometimes you need data to go back and forth between these two useful healthcare standards. Redox can support you by translating data in either direction with the FHIR `Composition` resource. 

> **Key takeaways**
>
> - Redox translates data in both directions between CDA (XML-based documents) and FHIR (modern, resource-based).
> - You can handle translation with the Redox FHIR `Composition` resource.
>   - **CDA to FHIR:** Use the `Composition$convert` operation to turn a CDA document into a FHIR bundle.
>   - **FHIR to CDA:** Use the `Composition$convert-to-cda` operation to turn a FHIR bundle into a CDA document.
> - _Limitation:_ CDA and FHIR translation isn’t supported with <u>**data on demand**</u>.

## Who needs to translate between CDA and FHIR

CDA and FHIR translation is helpful for these use cases: 

- Providers establishing a new patient’s history before providing treatment.
- Providers supporting a document-based business process (e.g., generating PDFs). 
- Providers exchanging data over clinical networks, where both FHIR and CDA are possible. 
- Vendors consuming patient data for service within their app.
- Payers wanting data for member engagement to recommend preventative care or more cost-effective services.
- Payers tracking a patient’s treatments for billing purposes (e.g., services included in a hospital stay). 

## How translation works

<details>
<summary>Translating CDA to FHIR</summary>

_For vendors_: Either you or your connection sends CDA documents to a Redox FHIR endpoint for translation using the `Composition$convert` operation. We return a FHIR bundle of resources either to your system or a cloud for storage (e.g., Google Cloud FHIR server).

_For providers_: You send CDA documents to a Redox FHIR endpoint for translation using the `Composition$convert` operation. We return a FHIR bundle of resources to your system. Alternatively, you can retrieve CDA data from a FHIR cloud vendor first, and then we translate the CDA data to FHIR afterwards.

For either use case, Redox allows you to retrieve clinical data directly from healthcare organizations or from clinical networks with <u>Network Onramps</u>. Redox returns a bundle of resources (30+ possible) with the normalized data so that you can accomplish your unique workflow.

When retrieving clinical documents, you generally have two options:

1. Retrieve the embedded XML document using the `DocumentReference` resource. [Refer to the `DocumentReference` schema](https://docs.redoxengine.com/permalink/99e94927-8ac9-55e0-aa05-a1c6dc20d58d-search-type).
2. (_Recommended_) Retrieve discrete, usable data by translating CDA to FHIR using the `Composition` resource. [Refer to the `Composition$convert` schema](https://docs.redoxengine.com/permalink/5cc651df-5a55-56be-bce7-e634243b64b9-$convert).

With the Redox FHIR API, you can retrieve discrete data (option #2) in a consistent, modern way.

> **Supported with Network Onramps**
>
> If using <u>Network Onramps,</u> you can retrieve CDA documents from clinical networks to translate to FHIR. Sometimes the clinical network may only return embedded files and not support retrieving discrete data. In this case, we return a `DocumentReference` payload instead of a FHIR bundle (as described in option #1). If discrete data is available, we support retrieving and translating CDAs from the clinical network just like with a direct connection (as described in option #2).

> **Not supported with data on demand**
>
> You can retrieve an embedded XML document, but we don’t currently support translating CDA to FHIR with <u>data on demand</u>. [Learn about what data on demand supports](/basics/data-exchange-with-redox/data-on-demand).

</details>

<details>
<summary>Translating FHIR to CDA</summary>

Either you or your connection sends a FHIR bundle to Redox using the `Composition$convert-to-cda` operation. [Refer to the `Composition$convert-to-cda` schema](https://docs.redoxengine.com/permalink/5cc651df-5a55-56be-bce7-e634243b64b9-$convert-to-cda).

With the `Composition` resource, you organize the FHIR resources into the CDA sections you expect back. _If you don’t include the relevant CDA section to map to, it won’t be returned._

Redox returns the specified CDA sections to your system. Review the mappings section in this article to see which FHIR resources we support translating into CDA sections.

> **Not supported with data on demand**
>
> You can retrieve a FHIR resource, but we don’t currently support translating FHIR to CDA with <u>data on demand</u>. [Learn about what data on demand supports](/basics/data-exchange-with-redox/data-on-demand).

</details>

## Mappings between CDA and FHIR

#### CDA to FHIR

We convert CDA sections into a bundle of the best-fitting FHIR resources. Check out some examples below.

| **CDA section** | **FHIR resource(s)** |
| --- | --- |
| Allergies | `AllergyIntolerance` |
| Assessment Health conditions Problems Reason for visit Resolved problems | `Condition` |
| Discharge medications Medications | `MedicationRequest` and/or `MedicationStatement` |
| Encounters | `Encounter` |
| Family history | `FamilyHistory` |
| Functional status | `Observation` and `SupplyRequest` |
| Health concerns | `Condition` |
| Insurances | `Coverage` |
| MedicalEquipment | `DeviceRequest` |
| Results | `DiagnosticReport` |
| Vital signs | `Observation` |

#### FHIR to CDA 

We can produce an XML document for you based on the FHIR resources you provide. You can organize your FHIR resources into these CDA sections.

> **Related resources**
>
> Generally speaking, each section has a “core” FHIR resource that drives the mapping, which can then pull in other resources like:
>
> - `Practitioner`
> - `PractitionerRole`
> - `Organization`
> - `RelatedPerson`

| **FHIR resource** | **CDA section** |
| --- | --- |
| `AllergyIntolerance` | Allergies |
| `Appointment` `MedicationRequest` `ServiceRequest` `SupplyRequest` | Plan of treatment |
| `Condition` | Problems |
| `DiagnosticReport` `Observation` | Results |
| `Encounter` | Encounters |
| `Immunization` | Immunization |
| `MedicationRequest` | Medications |
| `Observation` | Vital signs Social history |
| `Procedure` | Procedure |

#### Field mapping

Ultimately, Redox converts CDA-specific aspects into FHIR standards while maintaining accuracy. See some general examples you might come across in most FHIR resources: 

| **General CDA data** | **FHIR field or value** | **Notes** |
| --- | --- | --- |
| `nullFlavor` | `data-absent-reason` extension | There might be sections of a CDA document that use `nullFlavor`. Refer to these guides for more details: (a) [Section 5.1.5 of this CDA companion guide](http://www.hl7.org/ccdasearch/pdfs/Companion_Guide.pdf#%255B%257B%2522num%2522%253A301%252C%2522gen%2522%253A0%257D%252C%257B%2522name%2522%253A%2522XYZ%2522%257D%252C70%252C385%252C0%255D); or (b) [Section 3.6 of this CDA implementation guide](http://www.hl7.org/ccdasearch/pdfs/CCDA_Volume_One.pdf#%255B%257B%2522num%2522%253A13%252C%2522gen%2522%253A0%257D%252C%257B%2522name%2522%253A%2522XYZ%2522%257D%252C70%252C248%252C0%255D). We convert this to a data absent reason in FHIR. |
| Terminology Object IDs (OIDs) | FHIR terminology | We use the OID from the code system and/or implied value set of a coded value in CDA to look up the appropriate FHIR Terminology system. [Review FHIR Terminology](https://terminology.hl7.org/). |
| `patientRole` | Reference to `Patient` resource | CDAs must include the patient info, which translates into a FHIR reference to the related `Patient` resource.  For example, `ClinicalDocument.recordTarget.patientRole` would translate to `AllergyIntolerance.patient`. |
| `effectiveTime` | Any of these:  (a) `date` (b) `dateTime` (c) `instant` (d) `period` (e) `onsetDateTime` | Different FHIR resources have different expressions of time, all depending on the context. The `effectiveTime` converts to the most applicable FHIR time field. |
| `section.code` | General CDA data | The CDA section identifier helps us map the data within that section to the most appropriate FHIR resource.  For example, if we have `section.code=48765-2` then we map the data to the `AllergyIntolerance` resource. |
| `section.entry.reference` | Relevant FHIR resource | This is a reference to a FHIR resource in the FHIR bundle that can be translated to a given CDA section. |

> **FHIR mappings**
>
> If you want more granular technical details, check out HL7’s and CDA’s recommended mappings for individual resources. 
>
> As an example, review these recommended mappings for `AllergyIntolerance`:
>
> - [HL7 mappings](https://www.hl7.org/fhir/allergyintolerance-mappings.html#rim)
> - [CDA mappings](https://www.hl7.org/ccdasearch/templates/2.16.840.1.113883.10.20.22.2.6.1.html)
>
> We don’t follow every recommendation, but these can at least give you an idea of how mappings between FHIR and CDA can work.