FHIRFLARE IG Toolkit

Helm chart for deploying the fhirflare-ig-toolkit application

View the Project on GitHub

FHIRFLARE IG Toolkit

FHIRFLARE Logo

Overview

The FHIRFLARE IG Toolkit is a Flask-based web application designed to streamline the management, processing, validation, and deployment of FHIR Implementation Guides (IGs) and test data. It offers a user-friendly interface for importing IG packages, extracting metadata, validating FHIR resources or bundles, pushing IGs to FHIR servers, converting FHIR resources to FHIR Shorthand (FSH), uploading complex test data sets with dependency management, and retrieving/splitting FHIR bundles. The toolkit includes live consoles for real-time feedback, making it an essential tool for FHIR developers and implementers.

The application can run in two modes:

Installation Modes (Lite vs. Standalone)

This toolkit offers two primary installation modes to suit different needs:

Features

Technology Stack

Prerequisites

Setup Instructions

Running Pre-built Images (General Users)

This is the easiest way to get started without needing Git or Maven. Choose the version you need:

Lite Version (No local HAPI FHIR):

# Pull the latest Lite image
docker pull ghcr.io/sudo-jhare/fhirflare-ig-toolkit-lite:latest

# Run the Lite version (maps port 5000 for the UI)
# You'll need to create local directories for persistent data first:
# mkdir instance logs static static/uploads instance/hapi-h2-data
docker run -d \
  -p 5000:5000 \
  -v ./instance:/app/instance \
  -v ./static/uploads:/app/static/uploads \
  -v ./instance/hapi-h2-data:/app/h2-data \
  -v ./logs:/app/logs \
  --name fhirflare-lite \
  ghcr.io/sudo-jhare/fhirflare-ig-toolkit-lite:latest
Standalone Version (Includes local HAPI FHIR):

Bash

# Pull the latest Standalone image
docker pull ghcr.io/sudo-jhare/fhirflare-ig-toolkit-standalone:latest

# Run the Standalone version (maps ports 5000 and 8080)
# You'll need to create local directories for persistent data first:
# mkdir instance logs static static/uploads instance/hapi-h2-data
docker run -d \
  -p 5000:5000 \
  -p 8080:8080 \
  -v ./instance:/app/instance \
  -v ./static/uploads:/app/static/uploads \
  -v ./instance/hapi-h2-data:/app/h2-data \
  -v ./logs:/app/logs \
  --name fhirflare-standalone \
  ghcr.io/sudo-jhare/fhirflare-ig-toolkit-standalone:latest

Building from Source (Developers) Using Windows .bat Scripts (Standalone Version Only):

First Time Setup:

Run Build and Run for first time.bat:

Code snippet

cd "<project folder>"
git clone [https://github.com/hapifhir/hapi-fhir-jpaserver-starter.git](https://github.com/hapifhir/hapi-fhir-jpaserver-starter.git) hapi-fhir-jpaserver
copy .\\hapi-fhir-Setup\\target\\classes\\application.yaml .\\hapi-fhir-jpaserver\\target\\classes\\application.yaml
mvn clean package -DskipTests=true -Pboot
docker-compose build --no-cache
docker-compose up -d

This clones the HAPI FHIR server, copies configuration, builds the project, and starts the containers.

Subsequent Runs:

Run Run.bat:

Code snippet

cd "<project folder>"
docker-compose up -d

This starts the Flask app (port 5000) and HAPI FHIR server (port 8080).

Access the Application:

Preparation (Standalone Version Only):

cd <project folder>
git clone [https://github.com/hapifhir/hapi-fhir-jpaserver-starter.git](https://github.com/hapifhir/hapi-fhir-jpaserver-starter.git) hapi-fhir-jpaserver
cp ./hapi-fhir-Setup/target/classes/application.yaml ./hapi-fhir-jpaserver/target/classes/application.yaml

Build:

# Build HAPI FHIR (Standalone Version Only)
mvn clean package -DskipTests=true -Pboot

# Build Docker Image (Specify APP_MODE=lite in docker-compose.yml for Lite version)
docker-compose build --no-cache

Run:

docker-compose up -d
Access the Application:

Clone the Repository:

git clone [https://github.com/Sudo-JHare/FHIRFLARE-IG-Toolkit.git](https://github.com/Sudo-JHare/FHIRFLARE-IG-Toolkit.git)
cd FHIRFLARE-IG-Toolkit

Install Dependencies:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Install Node.js, GoFSH, and SUSHI (for FSH Converter):

# Example for Debian/Ubuntu
curl -fsSL [https://deb.nodesource.com/setup_18.x](https://deb.nodesource.com/setup_18.x) | sudo bash -
sudo apt-get install -y nodejs
# Install globally
npm install -g gofsh fsh-sushi
Set Environment Variables:

export FLASK_SECRET_KEY='your-secure-secret-key'
export API_KEY='your-api-key'
# Optional: Set APP_MODE to 'lite' if desired
# export APP_MODE='lite'

Initialize Directories:

mkdir -p instance static/uploads logs
# Ensure write permissions if needed
# chmod -R 777 instance static/uploads logs

Run the Application:

export FLASK_APP=app.py
flask run

Access at http://localhost:5000.

Usage Import an IG

Search, View Details, and Import Packages

Navigate to Search and Import Packages (/search-and-import).

  1. The page will load a list of available FHIR Implementation Guide packages from a local cache or by fetching from configured registries.
    • A loading animation and progress messages are shown if fetching from registries.
    • The timestamp of the last cache update is displayed.
  2. Use the search bar to filter packages by name or author.
  3. Packages are paginated for easier Browse.
  4. For each package, you can:
    • View its latest official and absolute versions.
    • Click on the package name to navigate to a detailed view (/package-details/<name>) showing:
      • Comprehensive metadata (author, FHIR version, canonical URL, description).
      • A full list of available versions with publication dates.
      • Declared dependencies.
      • Other packages that depend on it (dependents).
      • Version history (logs).
    • Directly import a specific version using the “Import” button on the search page or the details page.
  5. Cache Management:
    • A “Clear & Refresh Cache” button is available to trigger a background task (/api/refresh-cache-task) that clears the local database and in-memory cache and fetches the latest package information from all configured registries. Progress is shown via a live log.

Manage IGs Go to Manage FHIR Packages (/view-igs) to view downloaded and processed IGs.

Actions:

Duplicates are highlighted for resolution.

View Processed IGs

After processing, view IG details (/view-ig/), including:

Interactive StructureDefinition viewer (Differential, Snapshot, Must Support, Key Elements, Constraints, Terminology, Search Params).

Select a package (e.g., hl7.fhir.au.core#1.1.0-preview).

Select a downloaded package.

Convert FHIR to FSH

Optionally select a package for context (e.g., hl7.fhir.au.core#1.1.0-preview). Choose input mode: Upload File: Upload a FHIR JSON/XML file. Paste Text: Paste FHIR JSON/XML content. Configure options: Output Style: file-per-definition, group-by-fsh-type, group-by-profile, single-file. Log Level: error, warn, info, debug. FHIR Version: R4, R4B, R5, or auto-detect. Fishing Trip: Enable round-trip validation with SUSHI, generating a comparison report. Dependencies: Specify additional packages (e.g., hl7.fhir.us.core@6.1.0, one per line). Indent Rules: Enable context path indentation for readable FSH. Meta Profile: Choose only-one, first, or none for meta.profile handling. Alias File: Upload an FSH file with aliases (e.g., $MyAlias = http://example.org). No Alias: Disable automatic alias generation. Click Convert to FSH to generate and display FSH output, with a waiting spinner (light/dark theme) during processing. If Fishing Trip is enabled, view the comparison report via the “Click here for SUSHI Validation” badge button. Download the result as a .fsh file. Retrieve and Split Bundles Navigate to Retrieve/Split Data (/retrieve-split-data).

Retrieve Bundles from Server:

Split Uploaded Bundles:

Toggle between local HAPI (/fhir) or a custom FHIR server.

Configure Embedded HAPI FHIR Server (Standalone Mode)

For users running the Standalone version, which includes an embedded HAPI FHIR server.

  1. Navigate to Configure HAPI FHIR (/config-hapi).
  2. The page displays the content of the HAPI FHIR server’s application.yaml file.
  3. You can edit the configuration directly in the text area.
    • Caution: Incorrect modifications can break the HAPI FHIR server.
  4. Click Save Configuration to apply your changes to the application.yaml file.
  5. Click Restart Tomcat to restart the HAPI FHIR server and load the new configuration. The restart process may take a few moments.

API Usage Import IG Bash

curl -X POST http://localhost:5000/api/import-ig
-H “Content-Type: application/json”
-H “X-API-Key: your-api-key”
-d ‘{“package_name”: “hl7.fhir.au.core”, “version”: “1.1.0-preview”, “dependency_mode”: “recursive”}’ Returns complies_with_profiles, imposed_profiles, and duplicate_packages_present info.

Refresh Package Cache (Background Task)

curl -X POST http://localhost:5000/api/refresh-cache-task \
-H "X-API-Key: your-api-key"

Push IG Bash

curl -X POST http://localhost:5000/api/push-ig \
-H "Content-Type: application/json" \
-H "Accept: application/x-ndjson" \
-H "X-API-Key: your-api-key" \
-d '{
      "package_name": "hl7.fhir.au.core",
      "version": "1.1.0-preview",
      "fhir_server_url": "http://localhost:8080/fhir",
      "include_dependencies": true,
      "force_upload": false,
      "dry_run": false,
      "verbose": false,
      "auth_type": "none"
    }'

Returns a streaming NDJSON response with progress and final summary.

Upload Test Data Bash

curl -X POST http://localhost:5000/api/upload-test-data \
-H "X-API-Key: your-api-key" \
-H "Accept: application/x-ndjson" \
-F "fhir_server_url=http://your-fhir-server/fhir" \
-F "auth_type=bearerToken" \
-F "auth_token=YOUR_TOKEN" \
-F "upload_mode=individual" \
-F "error_handling=continue" \
-F "validate_before_upload=true" \
-F "validation_package_id=hl7.fhir.r4.core#4.0.1" \
-F "use_conditional_uploads=true" \
-F "test_data_files=@/path/to/your/patient.json" \
-F "test_data_files=@/path/to/your/observations.zip"

Returns a streaming NDJSON response with progress and final summary. Uses multipart/form-data for file uploads.

Retrieve Bundles Bash

curl -X POST http://localhost:5000/api/retrieve-bundles \
-H "X-API-Key: your-api-key" \
-H "Accept: application/x-ndjson" \
-F "fhir_server_url=http://your-fhir-server/fhir" \
-F "resources=Patient" \
-F "resources=Observation" \
-F "validate_references=true" \
-F "fetch_reference_bundles=false"

Returns a streaming NDJSON response with progress. The X-Zip-Path header in the final response part will contain the path to download the ZIP archive (e.g., /tmp/retrieved_bundles_datetime.zip).

Split Bundles Bash

curl -X POST http://localhost:5000/api/split-bundles \
-H "X-API-Key: your-api-key" \
-H "Accept: application/x-ndjson" \
-F "split_bundle_zip_path=@/path/to/your/bundles.zip"

Returns a streaming NDJSON response. The X-Zip-Path header in the final response part will contain the path to download the ZIP archive of split resources.

Validate Resource/Bundle Not yet exposed via API; use the UI at /validate-sample.

Configuration Options Located in app.py:

Get HAPI FHIR Configuration (Standalone Mode)

curl -X GET http://localhost:5000/api/config \
-H "X-API-Key: your-api-key"

Save HAPI FHIR Configuration:

curl -X POST http://localhost:5000/api/config \
-H "Content-Type: application/json" \
-H "X-API-Key: your-api-key" \
-d '{"your_yaml_key": "your_value", ...}' # Send the full YAML content as JSON

Restart HAPI FHIR Server:

curl -X POST http://localhost:5000/api/restart-tomcat \
-H "X-API-Key: your-api-key"

Testing The project includes a test suite covering UI, API, database, file operations, and security.

Test Prerequisites:

pytest: For running tests. pytest-mock: For mocking dependencies. Install: pip install pytest pytest-mock Running Tests:

Bash

cd <project folder>
pytest tests/test_app.py -v

Test Coverage:

Development Notes

Background

The toolkit addresses the need for a comprehensive FHIR IG management tool, with recent enhancements for resource validation, FSH conversion with advanced GoFSH features, flexible versioning, improved IG pushing, dependency-aware test data uploading, and bundle retrieval/splitting, making it a versatile platform for FHIR developers.

Technical Decisions

Recent Updates

Future Improvements

Completed Items

Directory Structure

FHIRFLARE-IG-Toolkit/
├── app.py                              # Main Flask application
├── Build and Run for first time.bat    # Windows script for first-time Docker setup
├── docker-compose.yml                  # Docker Compose configuration
├── Dockerfile                          # Docker configuration
├── forms.py                            # Form definitions
├── LICENSE.md                          # Apache 2.0 License
├── README.md                           # Project documentation
├── requirements.txt                    # Python dependencies
├── Run.bat                             # Windows script for running Docker
├── services.py                         # Logic for IG import, processing, validation, pushing, FSH conversion, test data upload, retrieve/split
├── supervisord.conf                    # Supervisor configuration
├── hapi-fhir-Setup/
│   ├── README.md                       # HAPI FHIR setup instructions
│   └── target/
│       └── classes/
│           └── application.yaml        # HAPI FHIR configuration
├── instance/
│   ├── fhir_ig.db                      # SQLite database
│   ├── fhir_ig.db.old                  # Database backup
│   └── fhir_packages/                  # Stored IG packages and metadata
│       ├── ... (example packages) ...
├── logs/
│   ├── flask.log                       # Flask application logs
│   ├── flask_err.log                   # Flask error logs
│   ├── supervisord.log                 # Supervisor logs
│   ├── supervisord.pid                 # Supervisor PID file
│   ├── tomcat.log                      # Tomcat logs for HAPI FHIR
│   └── tomcat_err.log                  # Tomcat error logs
├── static/
│   ├── animations/
│   │   ├── loading-dark.json           # Dark theme spinner animation
│   │   └── loading-light.json          # Light theme spinner animation
│   ├── favicon.ico                     # Application favicon
│   ├── FHIRFLARE.png                   # Application logo
│   ├── js/
│   │   └── lottie-web.min.js           # Lottie library for spinner
│   └── uploads/
│       ├── output.fsh                  # Generated FSH output (temp location)
│       └── fsh_output/                 # GoFSH output directory
│           ├── ... (example GoFSH output) ...
├── templates/
│   ├── base.html                       # Base template
│   ├── cp_downloaded_igs.html          # UI for managing IGs
│   ├── cp_push_igs.html                # UI for pushing IGs
│   ├── cp_view_processed_ig.html       # UI for viewing processed IGs
│   ├── fhir_ui.html                    # UI for FHIR API explorer
│   ├── fhir_ui_operations.html         # UI for FHIR server operations
│   ├── fsh_converter.html              # UI for FSH conversion
│   ├── import_ig.html                  # UI for importing IGs
│   ├── index.html                      # Homepage
│   ├── retrieve_split_data.html        # UI for Retrieve and Split Data
│   ├── upload_test_data.html           # UI for Uploading Test Data
│   ├── validate_sample.html            # UI for validating resources/bundles
│   ├── config_hapi.html                # UI for HAPI FHIR Configuration
│   └── _form_helpers.html              # Form helper macros
├── tests/
│   └── test_app.py                     # Test suite
└── hapi-fhir-jpaserver/                # HAPI FHIR server resources (if Standalone)

Contributing

  1. Fork the repository.
  2. Create a feature branch (git checkout -b feature/your-feature).
  3. Commit changes (git commit -m “Add your feature”).
  4. Push to your branch (git push origin feature/your-feature).
  5. Open a Pull Request.
  6. Ensure code follows PEP 8 and includes tests in tests/test_app.py.

Troubleshooting

License

Licensed under the Apache 2.0 License. See LICENSE.md for details.