LinuxForHealth FHIR Server 5.0.0

The first release of the LinuxForHealth FHIR Server (formerly the IBM FHIR Server)!

This version of the LinuxForHealth FHIR Server supports HL7 FHIR versions 4.0.1 and 4.3.0.

This release introduces support for HL7 FHIR version 4.3 (sometimes called "R4B") and removes support for select 4.0 resource types that have been removed in the specification.

It also introduces experimental support for:

1. the Citus distributed PostgreSQL backend for scale-out scenarios; and
2. asynchronous search parameter indexing for improved ingestion performance

Both of these experimental features have important limitations to be aware of:

1. Citus search limitations
2. Async indexing impacts data consistency

Added

• Support for HL7 FHIR 4.3.0
  • regenerate the model from R4B (4.3.0) spec artifacts
  • update the fhir-examples and tests to cover the R4B resources
  • split FHIR 4.0.1 conformance artifacts into separate module and exclude by default
  • honor fhirVersion parameter when serving CapabilityStatement
  • honor fhirVersion parameter when computing the set of resource types for whole-system interactions
  • [fhir-client] support setting the fhirVersion mime-type parameter on requests
  • support memberOf check against new CodeableReference datatype
  • warn about deprecated tables for resources removed in R4B
  • fail the schema-update if there are existing Evidence or EvidenceVariable resource instances
• Experimental support for Citus (distributed PostgreSQL)
• Experimental support for asynchronous remote indexing
• Support for US Core 5.0.1
• Support for PDex PlanNet 1.1.0
• Support for PDex Drug Formulary 1.1.0
• Support for the FHIRPath repeat function
• Schema tool option to grant only SELECT to support read-only access
• fhir-bucket reindex driver support for --force
• Support specifying the Azure Blob serviceVersion
• Support removal of primitive values in FHIRPath

Changed

• BREAKING: Update groupId and package names from com.ibm.fhir to org.linuxforhealth.fhir
• BREAKING: Release docker images to github packages (ghcr.io)
• The database schema version is now V0030
• Dependency updates
• Reference values are now stored in new LOGICAL_RESOURCE_IDENT table
• DB locking is now performed on LOGICAL_RESOURCE_IDENT instead of LOGICAL_RESOURCES
• Validate extensions against the version referenced in a profile instead of the latest version
• Ensure lastUpdated increases with versionId in a distributed environment
• Populate "path" property in FHIRPathNode implementations representing system values
• Allow Interceptors to modify data before returning it to the caller
• fhir-smart should allow read access to Patient resources in compartment of the patient context
• Make skippable updates the default
• Refactor parameter persistence to use fhir-remote-index backend
• Refined processing for instance-level $validate
• Improve reindex throughput by using batch-based processing
• Avoid storing duplicate search parameter values for a single resource
• Smart app launch and $everything operation should handle 403 error better
• Avoid needless whitespace handling in String.split
• Avoid implicit narrowing conversion
• Replace AES encryption with Hashids
  • We also renamed the corresponding config property from batchIdEncryptionKey to batchIdEncodingKey

Removed

• Support for Db2

Fixed

• ResourceFingerprintVisitor fails to account for integer values
• $validate operation returns 200 OK when it should return a 500 Server Error
• reindex operation should lock logical_resources_ident with select for update
• Conditional PATCH returns NullPointerException
• FHIRPath evaluator should throw when string function is invoked on non-string
• there is no search "parameters" contents on the swagger part in fhir-swagger-generator-4.10.0-cli.jar
• ConstraintGenerator should handle versioned extension canonicals
• Coding display validation should consider all possible designations
• Azure blob offload cannot connect to older instance of azurite
• Bulk export fails when payload offloading is configured
• Possible NullPointerException in ProfileSupport.java
• With logLevel=FINE, CommonUtil can throw ClassCastException
• Schema size report does not correctly filter schemas
• Strange behavior when working with Element.id from FHIRPath

Security

• Validate tenant id and datastore id before using
• Disable ACCESS_EXTERNAL_DTD and ACCESS_EXTERNAL_STYLESHEET when building Transformer

Migration Considerations

To migrate from a prior version to version 5.0.0:

1. Analyze configuration changes and prepare for the upgrade
   • Due to the package rename (com.ibm -> org.linuxforhealth), fhirServer/persistence/factoryClassname and fhirServer/audit/serviceClassName values must be updated in each fhir-server-config.json
   • fhirServer/bulkdata/core/batchIdEncryptionKey was renamed to fhirServer/bulkdata/core/batchIdEncodingKey
2. Stop the server (or otherwise prevent write requests).
3. Perform a database back up.
4. Run the fhir-persistence-schema-5.0.0-cli.jar --update-schema command.
5. Deploy the new server.
6. Perform a complete re-indexing.
   • #3683 changes how reference search parameters are stored
   • #3763 removes redundant search parameter values
   • internal search parameters have been renamed (including compartment membership)

Special considerations for upgrading to 5.0.0:

• Due to the package rename (com.ibm -> org.linuxforhealth), all META-INF/service files must be renamed. This impacts all FHIRRegistryResourceProvider (e.g. packaging for IGs) and FHIRPersistenceInterceptor implementations.
• There is no support for migrating data from an existing (single-node) PostgreSQL installation to a distributed Citus backend.
• fhir-persistence-schema: Prior to LinuxForHealth FHIR Server version 5.0.0, the default value for --db-type was db2. As of version 5.0.0, there is no longer a default value and --db-type must be specified every time.

If upgrading from a version prior to 4.11.0, be sure to review the applicable migration considerations:

• 4.11.0 migration considerations

Note: for schema migrations, only the latest version of the fhir-persistence-schema tool must be run.

Using the Release

Run or extend the Docker image from https://github.com/LinuxForHealth/FHIR/pkgs/container/fhir-server or download fhir-install-5.0.0.zip and install as described at https://linuxforhealth.github.io/FHIR/guides/FHIRServerUsersGuide.

Executable jar files for the fhir-persistence-schema, fhir-swagger-generator, fhir-bucket, and fhir-path projects are also available:

• fhir-persistence-schema-5.0.0-cli.jar
• fhir-swagger-generator-5.0.0-cli.jar
• fhir-bucket-5.0.0-cli.jar
• fhir-path-5.0.0-cli.jar

Usage is documented in the corresponding README files:

• https://github.com/LinuxForHealth/FHIR/tree/main/fhir-persistence-schema
• https://github.com/LinuxForHealth/FHIR/tree/main/fhir-swagger-generator
• https://github.com/LinuxForHealth/FHIR/tree/main/fhir-bucket
• https://github.com/LinuxForHealth/FHIR/tree/main/fhir-path

For Maven users, all project binaries are posted to Maven Central with a groupId of org.linuxforhealth.fhir and a version of 5.0.0.