IBM FHIR Server 4.10.0

This version of the IBM FHIR Server supports HL7 FHIR Specification version v4.0.1.

This release reduces the default initial heap size and introduces experimental CQL support, a $member-match implementation framework with a simplistic default strategy, and numerous other enhancements and fixes.
With this release, we now package multiple versions of the US Core (3.1.1 and 4.0.0) and CARIN for BlueButton (1.0.0 and 1.1.0) implementation guides and we've introduced new configuration options for controlling which profile versions are used for validation and which parameter versions are used for search.

Added

• Support conditional create-on-update via If-None-Match
• Overloaded fhir-model setters that take native Java objects
• Support SMART authz policy enforcement for bulkdata operations
  • requires fhir-smart to be included in the userlib
• Support for deleting rows from FHIR_ADMIN.VERSION_HISTORY during drop-schema
• Experimental support for $cql and clinical quality measure evaluation
  • requires manual packaging in userlib
• Experimental Da Vinci HRex: $member-match operation
• CARIN Consumer Directed Payer Data Exchange (CARIN IG for Blue Button®) - 1.1.0 - STU1 Update
• Update fhir-ig-us-core to US-Core STU4
• Configure default profile versions for validation
  • This change introduces fhirServer/resources/<resourceType>/profiles/defaultVersions
• Configure profiles that are not allowed to be used for validation
  • This change introduces fhirServer/resources/<resourceType>/profiles/notAllowed
• support resources//profiles properties from $validation when mode is set
• Version-aware SearchParameter filtering / configuration
• Search configuration caching
  • With this change, tenant-specific search parameters provided via extension-search-parameters.json will no longer be picked up dynamically
• A fhir-bucket docker image
  • https://hub.docker.com/r/ibmcom/ibm-fhir-bucket-tool
• A fhir-term-graph-loader docker image
  • https://hub.docker.com/r/ibmcom/ibm-fhir-term-loader
• Init method hook for FHIRRegistryResourceProvider implementations to avoid circular dependencies

Changed

• Schema version is now V0022
• Dependency updates
• Reduce the default min heap size and remove the default max heap size
• Write the "whole schema" version after successful update and check that version in $healthcheck
• Protect from concurrent update schema commands
• Revamped bundle processing for improved reference resolution and prep for storing resource payloads outside of the RDBMS
• Set CapabilityStatement.rest.resource.versioning to versioned-update
• Improve design for configuring profile conformance checking
  • This change introduces fhirServer/resources/<resourceType>/profiles/allowUnknown which used to be inferred from the presence of fhirServer/resources/<resourceType>/profiles/atLeastOne
• Split out the Term Graph Loaders
• Adjust PostgreSQL fillfactor for tables involving updates
• Avoid redundant read in the case of create-on-update
• Reject FHIR resources with the null char \u0000 or similar control chars
  • This changeset includes new validation code for ascii control characters within string values. To opt out of this new validation, set fhirServer/core/checkControlCharacters to false.
• Avoid creating unnecessary tables for Resource and DomainResource resource types
• Audit record for PUTs should not always use "Update"
• Handle null values in fhir-server-config and throw for exceptional case
• Remove jwt lib dependency from fhir-smart
• Replace narrative text in packaged IG jars with minimal text placeholder
• Condense packaged JSON resources during the build phase via profile
• Split the server SPI interfaces and related classes into their own module
• performance improvement for ModelSupport.getElementInfoMap

Deprecated

• FHIRPersistenceInterceptorException, FHIRPersistenceInterceptor, and FHIRPersistenceInterceptorMgr in the fhir-persistence module
  • These have been moved to the new fhir-server-spi module and thus the package name is now different.

Removed

• deprecated ValueSet enums and related methods
• the legacy query builder code
• deprecated FHIRUtil members
• FHIRParser.PROPERTY_IGNORE_UNRECOGNIZED_ELEMENTS
• Unnecessary tables for the abstract Resource and DomainResource resource types

Fixed

• Reference within a bundle could not be resolved with entry request conditional update
• search parameter extraction leads to registry lookup for implicit systems
• FHIR server $validate accepts resource json with duplicate keys
• Deadlock creating code_systems in Derby
• Preload parameter_names with all parameters to avoid deadlocks in Derby
• Incorrect query being generated for radius-based location (near) search
• NewLastUpdatedParmBehaviorUtil.buildNotEqualsRangeClause generates invalid query data
• ByteInputStream does not implement mark/reset
• incompatibility between 3.9.x and 4.1.3 in the FHIR Term Graph.
• Bundle-level constraints are not being checked against the Bundle
• Location URI is wrong when resource id begins with resource type name
• Stop swallowing exceptions in the $everything operation

Security

• Global caches in ProfileSupport should be tenant-specific

Migration Considerations

To migrate from a prior version of the IBM FHIR Server to version 4.10.0:

1. Analyze configuration changes and prepare for the upgrade
   • fhirServer/core/checkControlCharacters defaults to true
   • fhirServer/resources/<resourceType>/profiles/allowUnknown default to true; set to false for backwards compatibility if (and only if) you were using fhirServer/resources/<resourceType>/profiles/atLeastOne
   • fhirServer/resources/<resourceType>/profiles/notAllowed; default is allow all
   • fhirServer/resources/<resourceType>/profiles/defaultVersions; if you were previously using US Core 3.1.1 or CARIN for BlueButton 1.0.0 then be sure to set those versions as the default for each relevant profile to ensure backwards-compatibility
2. Stop the server (or otherwise prevent write requests).
3. Perform a database back up.
4. Run the fhir-persistence-schema-4.10.0-cli.jar --update-schema command. If using a non-admin user (recommended), also perform the --grant-to action.
   • Write the "whole schema" version after successful update
   • Add "lease" mechanism to protect from concurrent update schema commands
   • Remove tables for the abstract Resource and DomainResource resource types
   • Return the conflicting resource versionId from add_any_resource stored proc
5. Deploy the new server.
6. Re-indexing should not be required except for rare circumstances related to updated case-sensitivity logic for token search parameters that target code values.

Special considerations for upgrading to 4.10.0:

• This release includes a backwards-breaking change for users that have extended the IBM FHIR Server with custom operations and/or interceptors. Specifically, the FHIRPersistenceInterceptor and FHIROperation SPI classes have moved to the new fhir-server-spi module (from fhir-persistence and fhir-server respectively) and therefor the package names have changed as well. Extenders must rename their META-INF/services files accordingly:
  • com.ibm.fhir.server.operation.spi.FHIROperation -> com.ibm.fhir.server.spi.operation.FHIROperation
  • com.ibm.fhir.persistence.interceptor.FHIRPersistenceInterceptor -> com.ibm.fhir.server.spi.interceptor.FHIRPersistenceInterceptor

Using the Release

Run or extend the Docker image from https://hub.docker.com/r/ibmcom/ibm-fhir-server or download fhir-install-4.10.0.zip and install as described at https://ibm.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-4.10.0-cli.jar
• fhir-swagger-generator-4.10.0-cli.jar
• fhir-bucket-4.10.0-cli.jar
• fhir-path-4.10.0-cli.jar

Usage is documented in the corresponding README files:

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

For Maven users, all project binaries are posted to Maven Central with a version of 4.10.0.