$convert-data FAQ
What's the difference between $convert-data and the FHIR converter?
The FHIR® converter (preview) is a stand-alone API decoupled from the FHIR service and packaged as a container (Docker) image. 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.
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. 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 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.
Important
The purpose of this template is to help you get started with an ETL pipeline. Any steps in this pipeline can be removed, added, edited, or customized to fit your needs.
In a scenario with batch processing of HL7v2 messages, this template doesn't take sequencing into account. Post processing is needed if sequencing is a requirement.
How can I persist the converted data into the FHIR service by using Postman?
You can use the FHIR service's APIs to persist the converted data into the FHIR service by using POST {{fhirUrl}}/{{FHIR resource type}} with the request body containing the FHIR resource to be persisted in JSON format.
For more information, see Access the FHIR service in Azure Health Data Services by using Postman.
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 is similar for both Azure API for FHIR and the FHIR service in Azure Health Data Services. The only difference exists 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 allows displaying data in a template. Liquid has constructs such as output, logic, loops, and deals with variables. Liquid files are a mixture of HTML and Liquid code, and 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
$validateoperation.
Can I customize a default Liquid template?
Yes. You can 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 are currently not 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. It’s possible to store and reference custom templates. For more information, see Configure settings for $convert-data by using the Azure portal.
Why are my dates being converted when transforming JSON data?
It's possible for dates supplied within JSON data to be returned in a different format than what was supplied. During deserialization of the JSON payload, strings that are identified as dates get converted into .NET DateTime objects. These objects then get converted back to strings before going through the Liquid template engine. This conversion can cause the date value to be reformatted and represented in the local timezone of the FHIR service.
The coercion of strings to .NET DateTime objects can be disabled using the boolean parameter jsonDeserializationTreatDatesAsStrings. When set to true, the supplied data is treated as a string and won't be 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-dataoperation.Open a support request for the FHIR service in Azure Health Data Service FHIR Services version of the
$convert-dataoperation.Leave a comment on the GitHub repository for the open source version of the FHIR converter.
Next steps
Configure settings for $convert-data using the Azure portal
Note
FHIR® is a registered trademark of HL7 and is used with the permission of HL7.