$convert-data in the FHIR service

Article
13/05/2024

Note

In May 2024 we released a stand-alone FHIR® converter API decoupled from the FHIR service and packaged as a container (Docker) image for preview. In addition to enabling you to convert data from the source of record to FHIR R4 bundles, the FHIR converter offers many net new capabilities, such as:

Bidirectional data conversion from source of record to FHIR R4 bundles and back. For example, the FHIR converter can convert data from FHIR R4 format back to HL7v2 format.
Improved experience for customization of default Liquid templates.
Samples that demonstrate how to create an ETL (extract, transform, load) pipeline with Azure Data Factory (ADF).

To implement the FHIR converter container image, see the FHIR converter GitHub project.

The $convert-data operation in the FHIR® service enables you to convert health data from various formats into FHIR R4 data. The $convert-data operation uses Liquid templates from the FHIR Converter project for FHIR data conversion. You can customize these conversion templates as needed.

The $convert-data operation supports four types of data conversion:

HL7v2 to FHIR R4
C-CDA to FHIR R4
JSON to FHIR R4 (intended for custom conversion mappings)
FHIR STU3 to FHIR R4

Use the $convert-data endpoint

Use the $convert-data endpoint as a component within an ETL (extract, transform, and load) pipeline for the conversion of health data from various formats (for example: HL7v2, CCDA, JSON, and FHIR STU3) into the FHIR format. Create an ETL pipeline for a complete workflow as you convert your health data. We recommend that you use an ETL engine based on Azure Logic Apps or Azure Data Factory. For example, a workflow might include data ingestion, performing $convert-data operations, validation, data pre- and post-processing, data enrichment, data deduplication, and loading data for persistence in the FHIR service.

The $convert-data operation is integrated into the FHIR service as a REST API action. You can call the $convert-data endpoint as follows:

POST {{fhirurl}}/$convert-data

The health data for conversion is delivered to the FHIR service in the body of the $convert-data request. If the request is successful, the FHIR service returns a FHIR bundle response with the data converted to FHIR R4.

Parameters

A $convert-data operation call packages the health data for conversion inside JSON-formatted parameters in the body of the request. The parameters are described in the following table.

Parameter name	Description	Accepted values
inputData	Data payload to be converted to FHIR.	For `Hl7v2`: string For `Ccda`: XML For `Json`: JSON For `FHIR STU3`: JSON
inputDataType	Type of data input.	`Hl7v2`, `Ccda`, `Json`, `Fhir`
templateCollectionReference	Reference to an OCI image template collection in Azure Container Registry. The reference is to an image that contains Liquid templates to use for conversion. It can refer either to default templates or to a custom template image registered within the FHIR service. The following sections cover customizing the templates, hosting them on Azure Container Registry, and registering to the FHIR service.	For default/sample templates: HL7v2 templates: `microsofthealth/fhirconverter:default` `microsofthealth/hl7v2templates:default` C-CDA templates: `microsofthealth/ccdatemplates:default` JSON templates: `microsofthealth/jsontemplates:default` FHIR STU3 templates: `microsofthealth/stu3tor4templates:default` For custom templates: `<RegistryServer>/<imageName>@<imageDigest>`, `<RegistryServer>/<imageName>:<imageTag>`
rootTemplate	The root template to use while transforming the data.	For HL7v2: ADT_A01, ADT_A02, ADT_A03, ADT_A04, ADT_A05, ADT_A08, ADT_A11, ADT_A13, ADT_A14, ADT_A15, ADT_A16, ADT_A25, ADT_A26, ADT_A27, ADT_A28, ADT_A29, ADT_A31, ADT_A47, ADT_A60, OML_O21, ORU_R01, ORM_O01, VXU_V04, SIU_S12, SIU_S13, SIU_S14, SIU_S15, SIU_S16, SIU_S17, SIU_S26, MDM_T01, MDM_T02 For C-CDA: CCD, ConsultationNote, DischargeSummary, HistoryandPhysical, OperativeNote, ProcedureNote, ProgressNote, ReferralNote, TransferSummary For JSON: ExamplePatient, Stu3ChargeItem For FHIR STU3: FHIR STU3 resource name (for example: Patient, Observation, Organization)

Considerations

FHIR STU3 to FHIR R4 templates are Liquid templates that provide mappings of field differences only between a FHIR STU3 resource and its equivalent resource in the FHIR R4 specification. Some of the FHIR STU3 resources are renamed or removed from FHIR R4. For more information about the resource differences and constraints for FHIR STU3 to FHIR R4 conversion, see Resource differences and constraints for FHIR STU3 to FHIR R4 conversion.
JSON templates are sample templates for use in building your own conversion mappings. They aren't default templates that adhere to any predefined health data message types. JSON itself isn't specified as a health data format, unlike HL7v2 or C-CDA. As a result, instead of providing default JSON templates, we provide some sample JSON templates as a starting point for your own customized mappings.

Warning

Default templates are released under the MIT License and aren't supported by Microsoft.

The default templates are provided only to help you get started with your data conversion workflow. These default templates are not intended for production and might change when Microsoft releases updates for the FHIR service. To have consistent data conversion behavior across different versions of the FHIR service, you must do the following:

Host your own copy of the templates in an Azure Container Registry instance.
Register the templates to the FHIR service.
Use your registered templates in your API calls.
Verify that the conversion behavior meets your requirements.

For more information on hosting your own templates, see Host your own templates

Sample request

JSON

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "inputData",
            "valueString": "MSH|^~\\&|SIMHOSP|SFAC|RAPP|RFAC|20200508131015||ADT^A01|517|T|2.3|||AL||44|ASCII\nEVN|A01|20200508131015|||C005^Whittingham^Sylvia^^^Dr^^^DRNBR^D^^^ORGDR|\nPID|1|3735064194^^^SIMULATOR MRN^MRN|3735064194^^^SIMULATOR MRN^MRN~2021051528^^^NHSNBR^NHSNMBR||Kinmonth^Joanna^Chelsea^^Ms^^D||19870624000000|F|||89 Transaction House^Handmaiden Street^Wembley^^FV75 4GJ^GBR^HOME||020 3614 5541^PRN|||||||||C^White - Other^^^||||||||\nPD1|||FAMILY PRACTICE^^12345|\nPV1|1|I|OtherWard^MainRoom^Bed 183^Simulated Hospital^^BED^Main Building^4|28b|||C005^Whittingham^Sylvia^^^Dr^^^DRNBR^D^^^ORGDR|||CAR|||||||||16094728916771313876^^^^visitid||||||||||||||||||||||ARRIVED|||20200508131015||"
        },
        {
            "name": "inputDataType",
            "valueString": "Hl7v2"
        },
        {
            "name": "templateCollectionReference",
            "valueString": "microsofthealth/fhirconverter:default"
        },
        {
            "name": "rootTemplate",
            "valueString": "ADT_A01"
        }
    ]
}

Sample response

JSON

{
    "resourceType": "Bundle",
    "type": "batch",
    "entry": [
        {
            "fullUrl": "urn:uuid:9d697ec3-48c3-3e17-db6a-29a1765e22c6",
            "resource": {
                "resourceType": "Patient",
                "id": "9d697ec3-48c3-3e17-db6a-29a1765e22c6",
          ...
          ...
            },
            "request": {
                "method": "PUT",
                "url": "Location/50becdb5-ff56-56c6-40a1-6d554dca80f0"
            }
        }
    ]
}

The outcome of FHIR conversion is a FHIR bundle as a batch.

The FHIR bundle should align with the expectations of the FHIR R4 specification - Bundle - FHIR v4.0.1.
If you're trying to validate against a specific profile, you need to do some post processing by utilizing the FHIR $validate operation.

Next steps

Configure settings for $convert-data using the Azure portal

Troubleshoot $convert-data

$convert-data FAQ

Note

FHIR® is a registered trademark of HL7 and is used with the permission of HL7.

Share via