Skip to content

Interoperability Engine

The HealthChain Interop Engine provides a robust and customizable framework for converting between different HL7 healthcare data formats, including:

  • FHIR
  • CDA
  • HL7v2 (Coming soon)

Architecture

The interoperability module is built around a central InteropEngine that coordinates format conversion through specialized parsers and generators:

                    ┌───────────────┐
                    │ InteropEngine │
                    └───────┬───────┘
                            │
          ┌─────────────────┼─────────────────┐
          │                 │                 │
┌─────────▼─────────┐ ┌─────▼─────┐ ┌─────────▼─────────┐
│      Parsers      │ │ Templates │ │     Generators    │
└─────────┬─────────┘ └─────┬─────┘ └─────────┬─────────┘
          │                 │                 │
┌─────────▼─────────┐ ┌─────▼─────┐ ┌─────────▼─────────┐
│   - CDA Parser    │ │ Registry  │ │   - CDA Generator │
│   - HL7v2 Parser  │ │ Renderer  │ │  - FHIR Generator │
└───────────────────┘ └───────────┘ │ - HL7v2 Generator │
                                    └───────────────────┘

Key Components

Component Description
InteropEngine Core engine that manages the conversion process
Templates Liquid-based template system for customizing output syntactic generation
Mappings Mappings between different terminology systems
Configuration Configuration system for controlling engine behavior and template variations
Parsers Components for parsing different healthcare formats
Generators Components for generating output in different formats

Basic Usage

FHIR serves as the de facto data standard in HealthChain (and in the world of healthcare more broadly, ideally), therefore everything converts to and from FHIR resources.

The main conversion methods are (hold on to your hats):

  • .to_fhir() - Convert a source format to FHIR resources
  • .from_fhir() - Convert FHIR resources to a destination format
from healthchain.interop import create_engine, FormatType

# Create an interoperability engine
engine = create_engine()

# Convert CDA XML to FHIR resources
with open('patient_ccd.xml', 'r') as f:
    cda_xml = f.read()

fhir_resources = engine.to_fhir(cda_xml, src_format="cda")

# Convert FHIR resources back to CDA
cda_document = engine.from_fhir(fhir_resources, dest_format="cda")

Customization Points

The interoperability module is designed with extensibility at its core. You can customize and extend the framework in several ways:

Custom Parsers

Parsers convert source formats (CDA or HL7v2) into mapped dictionaries that can be processed by generators:

# Register a custom parser with the engine
engine.register_parser(FormatType.CDA, CustomCDAParser(engine.config))

For detailed implementation examples, see Creating a Custom Parser.

Custom Generators

Generators transform mapped dictionaries into target formats:

# Register a custom generator with the engine
engine.register_generator(FormatType.CDA,
                         CustomCDAGenerator(engine.config, engine.template_registry))

For detailed implementation examples, see Creating a Custom Generator.

Environment Configuration

You can customize the engine's behavior for different environments:

# Create an engine with specific environment settings
engine = create_engine(
    config_dir=Path("/path/to/custom/configs"),
    validation_level="warn",  # Options: strict, warn, ignore
    environment="production"  # Options: development, testing, production
)

# Change environment settings after creation
engine.config.set_environment("testing")
engine.config.set_validation_level("strict")

# Access environment-specific configuration
id_prefix = engine.config.get_config_value("defaults.common.id_prefix")

Environment-specific configurations are loaded from the environments/ directory and can override default settings for different deployment scenarios.

Template Customization

The template system uses Liquid templates to generate output formats. You can:

  1. Override existing templates by placing custom versions in the configured template directory
  2. Add new templates for custom formats or content types
  3. Extend the template system with custom logic via filters

For more details on extending the system, check out the Templates and Configuration pages.