DOCSEARCHbyAlgolia
Submit Docs

FHIR Converter

repository·main·Indexed 19 days ago

https://github.com/microsoft/fhir-converter

An open-source tool built on the .NET runtime that uses Liquid templates to convert health data between legacy formats and FHIR resources. Supported conversions include HL7v2 to FHIR, C-CDA to FHIR, JSON to FHIR, FHIR STU3 to R4, and FHIR to HL7v2 (Preview). The tool provides REST-based endpoints for conversion requests and supports custom template management via Azure Storage.

Tokens
52.7K
Snippets
52
Records
178
Agent score
67%

What's inside FHIR Converter

  1. Overview of FHIR Converter capabilities

    main

    FHIR Converter is an open-source tool built on the .NET runtime that uses the Liquid template language to convert health data between legacy formats and FHIR.

    Supported conversions include:

    • HL7v2 to FHIR
    • C-CDA to FHIR
    • JSON to FHIR
    • FHIR STU3 to R4
    • FHIR to HL7v2 (Preview)

    Mappings are defined via Liquid templates which can utilize custom filters. The project provides ready-to-use templates, but users can create or modify them to meet specific requirements (e.g., supporting HL7 versions other than v2.8).

  2. Understand FHIR converter deployment settings

    main

    When deploying the FHIR converter service in Azure, you can choose between a quickstart version with default configurations or a customized deployment.

    Default Settings

    • Security: API endpoint security is disabled by default. It is strongly recommended to enable it for production.
    • Template store integration: Disabled by default. This means no Storage Account is provisioned, and the service only has access to default templates (no custom templates).
    • Application Insights: Enabled by default to provide application logs and metrics for debugging and monitoring.

    Updating Configuration

    You can update the service configuration post-deployment by performing a redeployment with updated settings.

  4. Using Base IDs to reduce ID collisions

    main

    The Converter uses the concept of a base resource/base ID. Base resources are independent entities (e.g., Patient, Organization, Device) whose IDs are defined as a baseId.

    To reduce the risk of ID collisions, you can use a baseId as part of the hash input for related resources. For example, when generating an AllergyIntolerance ID, you can include the Patient ID as the baseId to enrich the hash seed.

  5. Configure Virtual Network and Subnet address blocks

    main

    When deploying with network isolation, you must specify CIDR address spaces for the Virtual Network and its subnets. If you are integrating with an existing organizational network, avoid using default values to prevent routing conflicts.

    Key constraints and requirements:

    • No Overlap: The Virtual Network address space must not overlap with other organizational network ranges.
    • Subnet Hierarchy: Subnet address spaces must be within the Virtual Network address space.
    • Exclusivity: The subnet must be dedicated exclusively to the Container Apps environment.
    • Minimum Size: The minimum subnet size is /23.
    • Reserved Ranges: Subnet address spaces must not overlap with:
      • 169.254.0.0/16
      • 172.30.0.0/16
      • 172.31.0.0/16
      • 192.0.2.0/24
    • Immutability: The subnet size cannot be modified after the Container Apps environment has been created.

  6. Understand resource mapping differences from STU3 to R4

    main

    When using the FHIR Converter to migrate data from STU3 to R4, be aware of changes in resource naming, removals, and additions.

    Renamed Resources

    The following resources have changed names between versions:

    • BodySite is now BodyStructure
    • EligibilityRequest is now CoverageEligibilityRequest
    • EligibilityResponse is now CoverageEligibilityResponse
    • Sequence is now MolecularSequence

    Removed Resources

    The following STU3 resources are not present in R4 and will not have a direct mapping:

    • DataElement
    • DeviceComponent
    • ExpansionProfile
    • ImagingManifest
    • ProcedureRequest
    • ProcessRequest
    • ProcessResponse
    • ReferralRequest
    • ServiceDefinition

  7. Understand ADT_A29 resource deletion behavior

    main

    When processing an ADT_A29 message, the converter uses the DELETE method in the template to remove specific FHIR resources (e.g., Patient, Encounter, Account) from a bundle.

    Important Constraints:

    • It only deletes resources whose IDs match the ones identified in the ADT_A29 message.
    • It will not delete resources (e.g., Observation, Medication) that were created by other message types (like ADT_A01 or ADT_A28) even if they are related.

  8. Understand Template Management CLI and OCI Images

    main

    The Template Management CLI is used to pull, push, and manage Liquid templates stored as OCI (Open Container Initiative) images in an Azure Container Registry (ACR).

    Image Structure

    Template OCI images use a layer-based structure (similar to Docker) using overlayfs. For custom templates, the tool uses a two-layer structure:

    1. Base Layer: Contains Microsoft-published templates.
    2. User Layer: Contains user-modified templates.

    When pushing, each layer is compressed into a *.tar.gz file. When pulling, a hidden .image/ folder is created in your output directory containing metadata and layer information. Do not modify the .image/ folder, as it can cause unexpected results.

  9. How HL7v2 Extensions are handled

    main

    When HL7v2 fields cannot be mapped directly to standard FHIR elements, the converter uses Liquid templates to create FHIR Extensions. These extensions are organized by the FHIR resource type they belong to, such as:

    • Patient resource extensions
    • Encounter extensions
    • Observation extensions
    • etc.

  10. Transform FHIR to HL7v2 using Liquid

    main

    When transforming from FHIR to HL7v2, your Liquid template must output a JSON representation of an HL7v2 message. When the /convertToHl7v2 API is called, the service takes this JSON and converts it into the standard HL7v2 format (with line breaks) before returning it.

    JSON HL7v2 Structure

    The JSON representation uses a messageDefinition key, which is an ordered array of HL7v2 segment objects. Each segment object uses the segment name as the key, and the HL7v2 field numbers as keys for the field values.

    Example JSON Structure:

    {
  "messageDefinition": [
    {
      "MSH": {
        "3": "TestSystem"
      },
      "PID": {
        "3": "12345"
      }
    }
  ]
}
    {
  "messageDefinition": [
    {
      "MSH": {
        "fieldNumber": "data resolution code"
      },
      "PID": {
        "fieldNumber": "data resolution code",
        "fieldNumber": "data resolution code",
        "fieldNumber": "data resolution code"
      },
      "PV1": {
        "fieldNumber": "data resolution code"
      }
    }
  ]
}

  11. Provenance resource generation from MSH and EVN

    main

    The converter generates two separate Provenance resources to capture different types of activity:

    1. From MSH segment: Captures message creation activity.
    2. From EVN segment: Captures real-world event data.

    The specific values captured depend on the mapping defined in the Provenance Liquid template.

  12. What are Snippets in FHIR Converter

    main

    Snippets are reusable "snippets of templates" used when creating templates for the FHIR Converter. They allow you to reference common logic or data structures without rewriting them, promoting modularity and reducing errors.

    There are seven primary types of released snippets:

    • Resources: Create specific FHIR resources (e.g., Patient, Encounter).
    • References: Create links between related resources to maintain context.
    • Data Type: Define the contents of specific data fields (e.g., mapping HL7 v2 attributes to FHIR attributes).
    • Code Systems: Map common codes from HL7 v2 to FHIR (e.g., mapping 'F' to 'female').
    • Sections: Map C-CDA document sections to FHIR resources.
    • Value Set: Map C-CDA value sets to FHIR value sets and code systems.
    • Utils: Provide utility functions for specific implementations (e.g., mapping a C-CDA section to a FHIR resource type).