Seamless Interoperability: Dynamic Loading of FHIR Implementation Guides

In the world of FHIR, an Implementation Guide (IG) is the source of truth for your data models. It defines the profiles, value sets, and search parameters that your system must support. Traditionally, updating an IG meant rebuilding your server or at least a restart.

In a production environment where 24/7 availability is critical, this downtime is unacceptable. In this post, we’ll explore the dynamic IG management lifecycle.

The Challenge

FHIR profiles evolve. A new version of US Core or a local pathology IG might be released, and your server needs to adapt. If you have to cycle your server for every profile tweak, you’re introducing risk and downtime.

The Solution: Dynamic IG Installation

Our HAPI FHIR Groovy server supports the $install operation on the ImplementationGuide resource. This allows you to upload a compiled IG package (package.tgz) while the system is running.

Tutorial: Installing an IG Dynamically

Step 1: Enable Runtime Uploads

First, ensure your server is configured to allow dynamic IG management in application.yaml:

hapi:
  fhir:
    ig_runtime_upload_enabled: true

Step 2: Prepare your IG

Export your IG from Simplifier or the FHIR IG Publisher as a .tgz file.

Step 3: Trigger the Installation

You can use a simple POST request to the server, passing the base64-encoded NPM package.

POST /ImplementationGuide/$install
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "npmContent",
      "valueBase64Binary": "H4sIAAAAAAAAA+..."
    }
  ]
}

Tutorial: Using Utility Scripts

To make life easier for DevOps engineers, I’ve provided shell scripts in the utils folder that automate this process.

Installing a Local File

./install.sh --type local --url http://localhost:8080 --file profiles-r4.tgz

Uninstalling an IG

If you need to retract a specific version of an IG:

./uninstall.sh --url http://localhost:8080 --ig_name fhir.example.ig --version 1.0.0

Behind the Scenes: What Happens?

When you install an IG dynamically:

1. Validation: The server parses the package to ensure it’s a valid FHIR NPM package.
2. Persistence: The profiles and value sets are stored in the database.
3. Cache Invalidation: The validation engine and search parameter caches are cleared so that the new rules take effect immediately.

The Architect’s Check: Search Parameter Reindexing

When you install an IG dynamically, you may introduce new SearchParameter resources. Simply installing the IG is step one. Step two is Reindexing.

• Small Datasets: The server handles this automatically for existing resources if configured.
• Large Datasets: You should trigger a background Reindexing job (see our post on Background Jobs) to ensure the new search parameters are indexed for all historical data. This prevents “partial search results” during the transition.

The Architect’s Verdict

By decoupling IG management from the deployment cycle, you allow clinical modelers and developers to iterate on data structures independently. It transforms your FHIR server into a truly living platform that can adapt to changing clinical requirements without skipping a beat.

Deep dive into the docs: doc/ig.md.