README.md
FHIR Converter
FHIR converter is an open source project that enables conversion of health data from legacy formats to and from FHIR. The FHIR converter uses the Liquid template language and the .NET runtime.
The FHIR converter supports the following conversions: HL7v2 to FHIR, C-CDA to FHIR, JSON to FHIR, FHIR STU3 to R4, and FHIR to HL7v2 (Preview).
The converter uses templates that define mappings between these different data formats. The templates are written in Liquid templating language and make use of custom filters.
The converter comes with a few ready-to-use templates. If needed, you can create a new template, or modify existing templates to meet your specific conversion requirements. The provided templates are based off of HL7 v2.8. Other versions may require you to make modifications to these templates on your own. See Templates & Authoring for specifics.
What's New?
The latest iteration of the Preview FHIR converter makes some significant changes over previous versions.
Some of the changes include:
- Containerized API
- Support Azure Storage for customer templates.
- Removal of Azure Container repository dependency for custom templates.
- Support for FHIR to HL7v2 conversion.
All the documentation for the new preview FHIR converter API can be found in the How to Guides folder.
Architecture
The FHIR converter API preview provides REST based APIs to perform conversion requests.
The FHIR converter APIs are offered as a container artifact in Microsoft Container Registry. This image can be downloaded and run as a web service on a container hosting platform in your Azure tenant; that clients can target for conversion requests.
Templates & Authoring
The FHIR converter API comes with several pre-built templates you can use as reference as to create your own.
| Conversion | Notes |
|---|---|
| HL7v2 to FHIR | Important points to note for HL7v2 to FHIR conversion: see here Common FHIR Validator errors/warning you might run into, and their explanations: see here |
| C-CDA to FHIR | |
| JSON to FHIR | |
| FHIR STU3 to R4 | Differences between STU3 & R4 |
| FHIR to HL7v2 (Preview) |
Concepts
In addition to the example templates provided there are several important concepts to review and consider when creating your own templates, including:
To use your custom templates, the FHIR converter API offers robust support for storing and retrieving your templates from Azure storage. For more information see: Template Store Integration.
Deployment
You can deploy the FHIR converter API using the instructions found here. The default deployment will deploy the FHIR Conventer API container hosted on Azure Container Apps.
API
The conversion APIs process the provided input data of the specified format and use the specified Liquid template (default or custom) and return the converted result as per the transformations in the template.
Complete details on the FHIR converter APIs and examples can be found here.
Troubleshooting
Some key concepts to consider:
- Processing time is related to both the input message size, template, and logic contained in the template. If your template is taking a long time to execute make sure you don't have any unnecessary loops.
- The output of the template is expected to be JSON when the target is FHIR.
- When converting data to FHIR, post processing is performed. If you are seeing unexpected results, double check the post processing logic.
- If you want a deeper understanding on how data is converted, look at the functional tests found here
Detailed troubleshooting options for your deployed FHIR converter API can be found here.
Previous Versions
Detailed documentation of prior Converter release is covered in the table below.
| Version | Summary |
|---|---|
| 5.x Liquid | Liquid engine release covers: 1. HL7v2, CCDA, and JSON to FHIR transformations. 2. Command Line utility. 3. VS Code authoring extension. 4. FHIR Service $convert integration. 5. ACR template storage. |
| 3.x Handlebars | Previous handlebars base solution. No longer supported. See full comparision here. |
External resources
Contributing
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit the CLA site.
When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.