Packages - Ferrum

Implementation Features

Feature	Support	Notes
Package Installation	Full	From registry or filesystem
Dependency Resolution	Full	Automatic dependency installation
Resource Filtering	Full	Include/exclude specific resource types
Example Resources	Full	Optional installation of example resources
Package Tracking	Full	Database tracking of installed packages
Internal Packages	Full	Support for server-provided packages
Startup Installation	Full	Automatic installation from config
Async Installation	Full	Job queue for long-running installations
Package Listing	Full	List installed packages and resources

Package Sources

Ferrum supports packages from two sources:

1. Registry Packages

Packages from the official FHIR registry (registry.fhir.org):

Core FHIR packages: hl7.fhir.r4.core, hl7.fhir.r4b.core, etc.
Extension packages: hl7.fhir.r4.extensions
Terminology packages: hl7.fhir.r4.terminology
Implementation Guides: hl7.fhir.us.core, hl7.fhir.uv.ips, etc.

2. Internal Packages

Packages bundled with the server (from fhir_packages/ directory):

Server-specific OperationDefinitions
Custom conformance resources
Pre-configured profiles and extensions

Package Installation

Installation Methods

Packages can be installed via:

Admin API (recommended for runtime installation)
$install-package Operation (FHIR-compliant)
Startup Configuration (automatic on server start)

Admin API Installation

Install packages using the admin API:

# Install US Core package
curl -X POST "http://localhost:8080/admin/packages/install" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hl7.fhir.us.core",
    "version": "6.0.0",
    "includeDependencies": true,
    "includeExamples": false
  }'

Response:

{
  "jobId": "pkg-install-12345",
  "status": "accepted"
}

Operation-Based Installation

Install packages using the FHIR $install-package operation:

curl -X POST "http://localhost:8080/fhir/\$install-package" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Parameters",
    "parameter": [
      {"name": "name", "valueString": "hl7.fhir.us.core"},
      {"name": "version", "valueString": "6.0.0"},
      {"name": "include-dependencies", "valueBoolean": true},
      {"name": "include-examples", "valueBoolean": false}
    ]
  }'

Installation Options

Option	Type	Default	Description
`name`	string	required	Package name (e.g., `hl7.fhir.us.core`)
`version`	string	latest	Package version (e.g., `6.0.0`)
`includeDependencies`	boolean	`true`	Install dependent packages
`includeExamples`	boolean	`false`	Include example resources
`includeResourceTypes`	string[]	all	Only install specific resource types
`excludeResourceTypes`	string[]	none	Exclude specific resource types

Resource Type Filtering

Control which resources are installed:

# Install only StructureDefinitions and ValueSets
curl -X POST "http://localhost:8080/admin/packages/install" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hl7.fhir.us.core",
    "version": "6.0.0",
    "includeResourceTypes": ["StructureDefinition", "ValueSet"]
  }'

# Exclude example resources
curl -X POST "http://localhost:8080/admin/packages/install" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hl7.fhir.us.core",
    "version": "6.0.0",
    "excludeResourceTypes": ["Patient", "Observation", "Encounter"]
  }'

Package Management

List Installed Packages

List all installed packages:

# List all packages
curl "http://localhost:8080/admin/packages"

# Filter by status
curl "http://localhost:8080/admin/packages?status=loaded"

# Pagination
curl "http://localhost:8080/admin/packages?limit=10&offset=0"

Response:

{
  "packages": [
    {
      "id": 1,
      "name": "hl7.fhir.r4.core",
      "version": "4.0.1",
      "status": "loaded",
      "loadedAt": "2024-01-15T10:30:00Z",
      "resourceCount": 1234
    },
    {
      "id": 2,
      "name": "hl7.fhir.us.core",
      "version": "6.0.0",
      "status": "loading",
      "loadedAt": "2024-01-15T11:00:00Z",
      "resourceCount": 0
    }
  ],
  "total": 2,
  "limit": 100,
  "offset": 0
}

Get Package Details

Get detailed information about a specific package:

curl "http://localhost:8080/admin/packages/1"

Response:

{
  "id": 1,
  "name": "hl7.fhir.r4.core",
  "version": "4.0.1",
  "status": "loaded",
  "loadedAt": "2024-01-15T10:30:00Z",
  "resourceCount": 1234,
  "errorMessage": null
}

List Package Resources

List all resources installed from a package:

# List all resources
curl "http://localhost:8080/admin/packages/1/resources"

# Pagination
curl "http://localhost:8080/admin/packages/1/resources?limit=50&offset=0"

Response:

{
  "packageId": 1,
  "resources": [
    {
      "resourceType": "StructureDefinition",
      "id": "Patient",
      "url": "http://hl7.org/fhir/StructureDefinition/Patient",
      "version": "4.0.1"
    },
    {
      "resourceType": "ValueSet",
      "id": "administrative-gender",
      "url": "http://hl7.org/fhir/ValueSet/administrative-gender",
      "version": "4.0.1"
    }
  ],
  "total": 1234,
  "limit": 50,
  "offset": 0
}

Configuration

Startup Package Installation

Configure packages to install automatically at server startup:

fhir:
  version: "r4"
  
  # Default packages (core, extensions, terminology)
  default_packages:
    core: true
    extensions: true
    terminology: true
  
  # Custom packages to install
  packages:
    - name: "hl7.fhir.us.core"
      version: "6.0.0"
      install_examples: false
      filter:
        include_resource_types:
          - "StructureDefinition"
          - "ValueSet"
          - "SearchParameter"
    
    - name: "hl7.fhir.uv.ips"
      version: "1.0.0"
      install_examples: true
  
  # Registry configuration
  registry_url: "https://registry.fhir.org"  # Optional, defaults to official registry
  
  # Internal packages
  install_internal_packages: true
  internal_packages_dir: "./fhir_packages"  # Optional, defaults to ./fhir_packages

Package Categories

Default packages are categorized:

Core: Base FHIR specification (StructureDefinitions, etc.)
Extensions: FHIR extensions
Terminology: CodeSystems and ValueSets
Custom: User-configured packages

Installation Process

Installation Flow

Package Discovery: Load package manifest from registry or filesystem
Dependency Resolution: Recursively load dependent packages
Resource Collection: Gather conformance resources (and optionally examples)
Filtering: Apply resource type filters
Batch Processing: Install resources using FHIR batch operations
Indexing: Index SearchParameters and other indexed resources
Completion: Update package status and resource counts

Installation Status

Packages have the following statuses:

loading: Installation in progress
loaded: Successfully installed
failed: Installation failed (check errorMessage)

Duplicate Detection

Ferrum automatically detects if a package is already installed:

Same name and version → Returns existing package ID
Different version → Installs as new package
Partial installation → Continues from where it left off

Asynchronous Installation

Package installation runs asynchronously via the job queue:

# 1. Submit installation request
curl -X POST "http://localhost:8080/admin/packages/install" \
  -H "Content-Type: application/json" \
  -d '{"name": "hl7.fhir.us.core", "version": "6.0.0"}'

# Response: {"jobId": "pkg-install-12345", "status": "accepted"}

# 2. Check installation status
curl "http://localhost:8080/admin/jobs/pkg-install-12345"

# 3. Monitor progress
# Job status updates as installation progresses

Job Status

Package installation jobs provide progress updates:

{
  "id": "pkg-install-12345",
  "type": "install_package",
  "status": "running",
  "progress": {
    "current": 500,
    "total": 1000,
    "message": "Installing resources..."
  },
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:05:00Z"
}

Package Resources

Conformance Resources

Packages typically contain:

StructureDefinition: Resource and data type definitions
ValueSet: Code value sets
CodeSystem: Code systems
SearchParameter: Search parameter definitions
OperationDefinition: Operation definitions
CapabilityStatement: Server capabilities
CompartmentDefinition: Compartment definitions
ImplementationGuide: Implementation guide metadata

Resource Installation

Resources are installed using FHIR batch operations:

PUT semantics: Resources preserve their IDs
Version handling: Resources are versioned per FHIR spec
Indexing: SearchParameters are automatically indexed
Hooks: Resource hooks process installed resources (e.g., CompartmentDefinition)

Internal Packages

Server-Provided Packages

Ferrum can include internal packages:

Location: fhir_packages/ directory (configurable)
Format: Standard FHIR package structure
Purpose: Server-specific OperationDefinitions, custom profiles

Example structure:

fhir_packages/
  Ferrum.fhir.server#1.0.0/
    package/
      package.json
      StructureDefinition-*.json
      OperationDefinition-*.json

Internal Package Installation

Internal packages are installed automatically at startup (if enabled):

fhir:
  install_internal_packages: true
  internal_packages_dir: "./fhir_packages"

Best Practices

Package Selection

Start with core: Always install core FHIR package first
Add incrementally: Install packages as needed
Version pinning: Pin specific versions for reproducibility
Filter resources: Exclude unnecessary resource types to reduce storage

Performance

Async installation: Use async installation for large packages
Resource filtering: Filter to only needed resource types
Skip examples: Don’t install examples unless needed for testing
Dependency management: Let server handle dependencies automatically

Maintenance

Monitor status: Check package installation status regularly
Review resources: List package resources to verify installation
Error handling: Check errorMessage for failed installations
Cleanup: Remove unused packages if needed

Error Handling

Common Errors

# Package not found
curl -X POST "http://localhost:8080/admin/packages/install" \
  -d '{"name": "nonexistent.package"}'
# Returns: 400 Bad Request - Package not found in registry

# Invalid version
curl -X POST "http://localhost:8080/admin/packages/install" \
  -d '{"name": "hl7.fhir.us.core", "version": "999.0.0"}'
# Returns: 400 Bad Request - Version not found

# Invalid filter
curl -X POST "http://localhost:8080/admin/packages/install" \
  -d '{
    "name": "hl7.fhir.us.core",
    "includeResourceTypes": ["InvalidType"]
  }'
# Returns: 400 Bad Request - Invalid resource type filter

Installation Failures

Failed installations include error details:

{
  "id": 2,
  "name": "hl7.fhir.us.core",
  "version": "6.0.0",
  "status": "failed",
  "errorMessage": "Failed to install 5 resources: Validation errors",
  "resourceCount": 100
}

Limitations

No Package Removal: Currently no API to remove installed packages
Version Conflicts: Multiple versions of same package can coexist
Resource Updates: Updating resources requires re-installing package
Registry Dependency: Requires internet access for registry packages

​Implementation Features

​Package Sources

​1. Registry Packages

​2. Internal Packages

​Package Installation

​Installation Methods

​Admin API Installation

​Operation-Based Installation

​Installation Options

​Resource Type Filtering

​Package Management

​List Installed Packages

​Get Package Details

​List Package Resources

​Configuration

​Startup Package Installation

​Package Categories

​Installation Process

​Installation Flow

​Installation Status

​Duplicate Detection

​Asynchronous Installation

​Job Status

​Package Resources

​Conformance Resources

​Resource Installation

​Internal Packages

​Server-Provided Packages

​Internal Package Installation

​Best Practices

​Package Selection

​Performance

​Maintenance

​Error Handling

​Common Errors

​Installation Failures

​Limitations

​Related Documentation

Implementation Features

Package Sources

1. Registry Packages

2. Internal Packages

Package Installation

Installation Methods

Admin API Installation

Operation-Based Installation

Installation Options

Resource Type Filtering

Package Management

List Installed Packages

Get Package Details

List Package Resources

Configuration

Startup Package Installation

Package Categories

Installation Process

Installation Flow

Installation Status

Duplicate Detection

Asynchronous Installation

Job Status

Package Resources

Conformance Resources

Resource Installation

Internal Packages

Server-Provided Packages

Internal Package Installation

Best Practices

Package Selection

Performance

Maintenance

Error Handling

Common Errors

Installation Failures

Limitations

Related Documentation