Convert - Update FHIR Version

POST /convert/v1/fhirDSTU2TofhirR4

POST /convert/v1/fhirSTU3TofhirR4

These operations can be used to convert FHIR bundles from an older version of FHIR (DSTU2 or STU3) to a newer version (R4).

Contents

Convert Basics
Inputs and Outputs
Processing Notes
- Conversion Limitations
- Embedded Binary Data
Error Handling
Example

Convert Basics

See the Programming Guide for general principles that apply to all Convert API operations.

Inputs and Outputs

The input is a FHIR DSTU2 or FHIR STU3 bundle for a single patient.

The output is a FHIR R4 Bundle containing the data parsed from the input, along with an OperationOutcome resource detailing the results (including warnings or errors) of the conversion process. See Output FHIR R4 Bundles for details.

Processing Notes

The following nuances should be considered when converting between FHIR versions:

Conversion Limitations

Older versions of FHIR (pre-R4) have no guarantee of forward compatibility with newer versions. Data may be mapped to different fields or resources, may be assigned new resource IDs in the converted output, and in rare cases may not be carried forward to the new version.

For more information, see the FHIR standard on version compatibility. The OperationOutcome resource will detail which elements were converted.

Embedded Binary Data

If a DiagnosticReport or DocumentReference resource has embedded binary data (based on its presentedForm field), Orchestrate will create a separate Binary resource in the output bundle containing that embedded data.

The Binary resource will have the same ID as the DocumentReference resource from which it is referenced.
The content_type field in the Binary resource contains MIME types, e.g., text/plain, application/pdf, etc.
The data field in the Binary resource contains base64 encoded data which must be decoded to view the contents (even if plain text).

Error Handling

If the input data is invalid (such as improperly-formatted FHIR data), the request will return an error response (see Using the API). However, in many cases the Convert service can continue processing even when there are issues with the input data, such as missing fields or unexpected data types. In such cases, the invalid data will be omitted from the finished bundle.

Example

Try It
Try out the operations, with examples, in the Developer Portal Sandbox.

FHIR bundles are verbose, and the differences between versions can be subtle. For example, in a STU3 Condition resource, the clinicalStatus field is a simple string with a specific list of possible values:

"clinicalStatus": "inactive",

In a R4 Condition resource, this field is a Codeable Concept. During the conversion, the system will map the original string to the appropriately coded value:

"clinicalStatus": {
    "coding": [
        {
            "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
            "code": "inactive"
        },
        {
            "system": "http://fhir.carevolution.com/codes/DemoNamespace/DiagnosisStatus",
            "code": "inactive",
            "userSelected": true
        }
    ]
},

For more examples, explore the sample bundles provided in the Developer Portal Sandbox.