Configure settings for $convert-data by using the Azure portal

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.

This article illustrates how to configure settings for $convert-data using the Azure portal to convert health data into FHIR® R4.

Default templates

Microsoft publishes a set of predefined sample Liquid templates from the FHIR Converter project to support FHIR data conversion. These templates are only provided to help get you started with your data conversion workflow. We recommend that you customize and host your own templates that support your own data conversion requirements. For information on customized templates, see Customize templates.

The default templates are hosted in a public container registry and require no further configurations or settings for your FHIR service. To access and use the default templates for your conversion requests, ensure that when invoking the $convert-data operation, the templateCollectionReference request parameter has the appropriate value based on the type of data input.

• HL7v2 templates
• C-CDA templates
• JSON templates
• FHIR STU3 templates

Warning

Default templates are released under the MIT License and are not supported by Microsoft Support.

The default templates are provided 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.

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

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

Customize templates

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.

Note

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.

The provided default templates can be used as a starting point if needed, on top of which your customizations can be added. When making updates to the templates, consider following these guidelines to avoid unintended conversion results.

The template should be authored in a way such that it yields a valid structure for a FHIR bundle resource.

For instance, the Liquid templates should have a format such as the following code:

<liquid assignment line 1 >
<liquid assignment line 2 >
.
.
<liquid assignment line n >	          
{
    "resourceType": "Bundle",
    "type": "xxx",
    <...liquid code...>
    "identifier":
    {
        "value":"xxxxx",
    },
    "id":"xxxx",
    "entry": [
	<...liquid code...>
   ]
}

The overall template follows the structure and expectations for a FHIR bundle resource, with the FHIR bundle JSON being at the root of the file. If you choose to add custom fields to the template that aren’t part of the FHIR specification for a bundle resource, the conversion request could. However, the converted result could potentially have unexpected output, and wouldn't yield a valid FHIR bundle resource that can be persisted in the FHIR service as is.

For example, consider the following code:

<liquid assignment line 1 >
<liquid assignment line 2 >
.
.
<liquid assignment line n >	          
{
   “customfield_message”: “I will have a message here”,
    “customfield_data”: {
      "resourceType": "Bundle",
      "type": "xxx",
      <...liquid code...>
      "identifier":
      {
        "value":"xxxxx",
      },
       "id":"xxxx",
       "entry": [
	  <...liquid code...>
    ]
  }
}

In the example code, two example custom fields customfield_message and customfield_data aren't FHIR properties per the specification, and the FHIR bundle resource seem to be nested under customfield_data (that is, the FHIR bundle JSON isn't at the root of the file). This template doesn’t align with the expected structure around a FHIR bundle resource. The conversion request might succeed using the provided template. However, the returned converted result could potentially have unexpected output (due to certain post conversion processing steps being skipped). It wouldn't be considered a valid FHIR bundle (since it's nested and has non FHIR specification properties) and attempting to persist the result in your FHIR service fails.

Host your own templates

We recommend that you host your own copy of templates in an Azure Container Registry (ACR) instance. ACR can be used to host your custom templates and support with versioning.

Hosting your own templates and using them for $convert-data operations involves the following seven steps.

1. Create an Azure Container Registry instance
2. Push the templates to your Azure Container Registry instance
3. Enable Azure Managed identity in your FHIR service instance
4. Provide Azure Container Registry access to the FHIR service managed identity
5. Register the Azure Container Registry server in the FHIR service
6. Configure the Azure Container Registry firewall for secure access
7. Verify the $convert-data operation

Step 1: Create an Azure Container Registry instance

Read the Introduction to container registries in Azure and follow the instructions for creating your own ACR instance. We recommend that you place your ACR instance in the same resource group as your FHIR service.

Step 2: Push the templates to your Azure Container Registry instance

After you create an ACR instance, you can use the FHIR Converter: Push Templates command in the FHIR Converter extension to push your custom templates to your ACR instance. Alternatively, you can use the Template Management CLI tool for this purpose.

To maintain different versions of custom templates in your Azure Container Registry, you can push the image containing your custom templates into your ACR instance with different image tags.

• For more information about ACR registries, repositories, and artifacts, see About registries, repositories, and artifacts.
• For more information about image tag best practices, see Recommendations for tagging and versioning container images.

To reference specific template versions in the API, be sure to use the exact image name and tag that contains the versioned template to be used. For the API parameter templateCollectionReference, use the appropriate image name + tag (for example: <RegistryServer>/<imageName>:<imageTag>).

Step 3: Enable Azure Managed identity in your FHIR service instance

1. Go to your instance of the FHIR service in the Azure portal, and then select the Identity option.

2. Change the Status to On and select Save to enable the system-managed identity in the FHIR service.

Step 4: Provide Azure Container Registry access to the FHIR service managed identity

1. In your resource group, go to your Container Registry instance, and then select the Access control (IAM) tab.

2. Select Add > Add role assignment. If the Add role assignment option is unavailable, ask your Azure administrator to grant you the permissions for performing this task.

   

3. On the Role pane, select the AcrPull role.

   

4. On the Members tab, select Managed identity, and then Select members.

5. Select your Azure subscription.

6. Select System-assigned managed identity, and then select the FHIR service you're working with.

7. On the Review + assign tab, select Review + assign to assign the role.

For more information about assigning roles in the Azure portal, see Azure built-in roles.

Step 5: Register the Azure Container Registry server in the FHIR service

You can register the ACR server by using the Azure portal.

To use the Azure portal:

1. In your FHIR service instance, under Transfer and transform data, select Artifacts. A list of currently registered Azure Container Registry servers is displayed.
2. Select Add and then, in the dropdown list, select your registry server.
3. Select Save.

You can register up to 20 ACR servers in the FHIR service.

Note

It might take a few minutes for the registration to take effect.

Step 6: Configure the Azure Container Registry firewall for secure access

There are many methods for securing ACR using the built-in firewall depending on your particular use case.

• Connect privately to an Azure container registry using Azure Private Link
• Configure public IP network rules
• Azure Container Registry mitigating data exfiltration with dedicated data endpoints
• Restrict access to a container registry using a service endpoint in an Azure virtual network
• Configure rules to access an Azure container registry behind a firewall
• Azure IP Ranges and Service Tags – Public Cloud

Step 7: Verify the $convert-data operation

Make a call to the $convert-data operation by specifying your template reference in the templateCollectionReference parameter:

<RegistryServer>/<imageName>@<imageDigest>.

You should receive a bundle response that contains the health data converted into the FHIR format.

Next steps

Overview of $convert-data

Troubleshoot $convert-data

$convert-data FAQ

Note

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