$convert-data FAQ for the FHIR service

Use this FAQ to find answers about $convert-data conversion setup, ETL pipeline usage, template customization, and troubleshooting.

What's the difference between $convert-data and the FHIR converter?

The FHIR® converter (preview) is a standalone API that's decoupled from the FHIR service and packaged as a container image. In addition to enabling you to convert data from the source of record to FHIR R4 bundles, the FHIR converter offers many 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.

Does your service create and manage the entire ETL pipeline for me?

You can 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. You can create an ETL pipeline for a complete workflow as you convert your health data. 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 the data for persistence in the FHIR service.

However, the $convert-data operation itself isn't an ETL pipeline.

Where can I find an example of an ETL pipeline?

There's an example published in the Azure Data Factory template gallery named Transform HL7v2 health data to FHIR R4 format and write to ADLS Gen2. This template transforms HL7v2 messages read from an Azure Data Lake Storage (ADLS) Gen2 or an Azure Blob Storage account into the FHIR R4 format. It then persists the transformed FHIR bundle JSON file into an ADLS Gen2 or a Blob Storage account. When you’re in the Azure Data Factory template gallery, you can search for the template.

How can I persist the converted data into the FHIR service?

Use the FHIR service APIs to persist the converted data into the FHIR service. Use POST {{fhirUrl}}/{{FHIR resource type}} with the request body containing the FHIR resource to persist in JSON format.

For more information, see Access the FHIR service in Azure Health Data Services by using REST Client.

What's the difference between the $convert-data endpoint in Azure API for FHIR versus the FHIR service in Azure Health Data Services?

The experience and core $convert-data operation functionality are similar for both Azure API for FHIR and the FHIR service in Azure Health Data Services. The only difference is in the setup for the Azure API for FHIR version of the $convert-data operation, which requires assigning permissions to the right resources.

Learn more:

Azure API for FHIR: Data conversion for Azure API for FHIR

FHIR service in Azure Health Data Services: Overview of $convert-data

I'm not familiar with Liquid templates. Where do I start?

Liquid is a template language engine that you can use to display data in a template. Liquid has constructs such as output, logic, loops, and it deals with variables. Liquid files are a mixture of HTML and Liquid code, and they have the .liquid file extension. The open source FHIR Converter comes with a few ready-to-use Liquid templates and custom filters for the supported conversion formats to help you get started.

The conversion succeeded. Does this mean I have a valid FHIR bundle?

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.

Can I customize a default Liquid template?

Yes. Use the FHIR Converter Visual Studio Code extension to customize templates according to your specific requirements. The extension provides an interactive editing experience and makes it easy to download Microsoft-published templates and sample data. The FHIR Converter extension for Visual Studio Code is available for HL7v2, C-CDA, and JSON Liquid templates. FHIR STU3 to FHIR R4 Liquid templates aren't currently supported. For more information, see Configure settings for $convert-data using the Azure portal.

After I customize a template, can I reference and store various versions?

Yes. You can store and reference custom templates. For more information, see Configure settings for $convert-data by using the Azure portal.

Why are my dates converted when transforming JSON data?

Dates that you supply within JSON data can appear in a different format than what you originally provided. During deserialization of the JSON payload, the system converts strings that it identifies as dates into .NET DateTime objects. The system then converts these objects back to strings before the data goes through the Liquid template engine. This conversion can reformat the date value and represent it in the local timezone of the FHIR service.

You can disable the coercion of strings to .NET DateTime objects by using the boolean parameter jsonDeserializationTreatDatesAsStrings. When set to true, the supplied data is treated as a string and isn't modified before being supplied to the Liquid engine.

If I need support with troubleshooting, where can I go?

Depending on the version of $convert-data you're using, you can:

• Use the troubleshooting guide for the FHIR service in Azure Health Data Services version of the $convert-data operation.

• Open a support request for the FHIR service in Azure Health Data Service FHIR Services version of the $convert-data operation.

• Leave a comment on the GitHub repository for the open source version of the FHIR converter.

Next steps

Overview of $convert-data

Configure settings for $convert-data using the Azure portal

Troubleshoot $convert-data