IBM FHIR Server 4.11.0

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

This release drops support for Java 8, adds support for the system and type-level history interactions, introduces resource payload offloading to Azure Blob Storage, and includes a large number of bug fixes and Java API changes.

The release packages OpenLiberty 22.0.0.3. This version enables users to configure unauthenticated access to protected resources (#1020). However, it also includes a known issue that affects the OpenAPI UI: https://www.ibm.com/support/pages/apar/PH44666

Added

• Database space usage tool
• Resource payload offload support for Azure Blob Storage
• Reconciliation service to keep azure-blob container in sync with RDBMS
• Experimental payload persistence offloading for Cassandra
  • not supported in the default server image; requires manual packaging work
• Spec-compliant whole-system history
• type-level history and support for the _type param on whole-system history
• Advertise system and type-level history in CapabilityStatement
• Allow clients to request search results without resource contents
• AuthzPolicyEnforcement handling for history and search with 'Prefer: return=minimal'
• _excludeTransactionTimeoutWindow param for whole-system history
• history-system and history-type endpoints to the openapi / swagger
• $export and $everything operations to generated swagger / openapi
• drive fhir-bucket from a local directory
• allow fhir-bucket to bootstrap FHIRBUCKET schema
• the $versions operation
  • in prep for FHIR R4B (4.3.0)

Changed

• The underlying relational database schema version is now V0025
• Dependency updates
• Avoid storing the resource contents in the case of a soft delete
• Bundle transaction processing should replace all local references, not just ones that start with "urn:"
• Extract compartment search parameters regardless of search parameter configuration
• Set serverRegistryResourceProviderEnabled to false in the default fhir-server-config
• Update request/response logging in fhir-client
• Update schema diagram/description in documentation
• Warn and skip update-schema when deployed version > new version
• Add deleted array to Bulk Data Export PollingLocationResponse
• Support repeated _type parameter instances in all system-level interactions (search, history, $everything, and $export)
• Improve performance of system-level searches with _type parameter and global params
• Omit expression and detail elements from OperationOutcome issues with no meaningful value
• Update Da Vinci Health Record Exchange (HRex) to STU1
• Update Implementation Guide Da Vinci Payer Data Exchange (PDex) 2.0.0 ballot (Feb 20 revision)
• BulkData 2.0.0: Update the OperationDefinitions and CapabilityStatement
• Support $import OperationOutcomes written when a Success
• Enhance the $everything operation to add support for Practitioners and Organizations
• add warning info to $healthcheck OperationOutcome when deployment update required
• Batch bundle request should lead to one audit event per entry
• Notification Service operationType should match Audit action
• Patched faulty fhirpath expressions in US Core 4.0.0
• Package expanded flavor of value set 'http://hl7.org/fhir/us/core/ValueSet/us-core-usps-state' for US Core 4.0.0
• Clarify fallback behavior for fhirServer/resources config
• Support bundle-local reference resolution from the FHIRPath resolve function
• Modify fhir-smart behavior for "user/" scope requests
• Report "undelete" action as a 'create' in the system and type-level history interactions

Deprecated

• fhirServer/search/enableLegacyWholeSystemSearchParams

Removed

• Support for Java 8
• Deprecated methods from FHIRPersistence interface
• fhirServer/search/useStoredCompartmentParam
• Export to parquet feature
  • point to blog post on converting from NDJSON to Parquet via Spark

Fixed

• search index not updating properly when a versioned reference is updated to a different versioned reference
• _history after $erase version returns FHIRPersistenceException: convertResourceDTO returned no resource
• No longer able to map unauthenticated users to the FHIRUsers security-role
• Error when canceling request to metadata endpoint
• componentIp in AuditLogEntry null if fhirServer/audit/ip is not configured.
• NullPointerException when deleting resource with fhir-smart enabled.
• /Patient/_search doesn't work for SMART App Launch enabled FHIR deployment
• $import allows adding Resources of multiple types in the same ndjson which could include unsupported resources.
• Misleading completed bundle request message
• Build fails in 2022 due to test data violating current year constraint
• $submit-data operation fails
• Warning statement should be issued when an explicitly-configured search parameter doesn't exist
• Whole system interactions should honor resources config when open=false
• $everything operation fails when certain resources / search parameters are filtering out in fhir-server-config
• fhir-smart Patient/$export assumes no _type filtering leading
• Instance-level history fullUrl is wrong when resource id begins with resource type name
• when querying _history with _since we are not using fhir search parsing rules for the timestamp
• C4BB-ExplanationOfBenefit warning received - constraint not generated
• Error when trying to evaluate cql when us-core ig jar also loaded
• ArrayIndexOutOfBoundsException during startup
• Clean up fhir-persistence-schematool usage info
• Clean up fhir-bucket CLI args to make it easier to run reindex
• Error Message for Bad StorageProvider Configuration is unintentionally opaque
• Erroneous reporting of Pending Outcome in Audit
• Large Bundles with lots of new CodeSystems and Ids hits JDBC Parameter Limit
• reason for $cql evaluation failure should be returned to the end user
• null pointer exception exercising operations $collect-data and $evaluate-measure
• Use of Resource.id in CQL fails due to type mismatch with modelinfo
• MemberMatch improperly generates date formats which are spec invalid
• $member-match should throw FHIROperationException instead of rewrapping the exception
• Bundle Change impacted the member-match behavior.
• Encode the datetime values in the bundle.Link.URL in the resource
• invalid sort parameter value leads to 500 server error
• Drop schema does not remove metadata from FHIR_ADMIN.TENANTS
• PostgreSQL invalid SQL generated for FHIR Search with prefer=minimal
• Prefer header processing uses ';' instead of ',' and should support multiple Prefer headers
• PostgreSQL create schema does not grant required permissions on schema itself
• using fhirserver id for bulk data it needs more authority than given by schema tool
• Bulk Data import fails when disableOperationOutcomes is false
• $import of file that does not exist fails with 500
• ImportPartitionAnalyzer not reporting infly rate on threshold
• Audit log entry id and versionId should match the created record but don't for resources imported with missing "id"
• bulkdata preflight checks should verify output provider config

Security

• AuthzPolicyEnforcement should prevent access to the whole-system history api

Migration Considerations

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

1. Analyze configuration changes and prepare for the upgrade
   • The value of fhirServer/core/serverRegistryResourceProvider in the default fhir-server-config.json is changed from true to false; false is the recommended value for performance-sensitive workloads.
   • fhirServer/search/useStoredCompartmentParam is removed; compartment inclusion criteria are always extracted now (#2886)
   • fhirServer/search/enableLegacyWholeSystemSearchParams is deprecated; this property should only be used during migration from versions prior to 4.9.0
   • fhirServer/resources processing is updated (#3536); now configurations with fhirServer/resources/open set to false will need to either list cross-resource search parameters like _id and _lastUpdated in each resource config or explicitly include an entry for "Resource"
   • connectionManager defaults have been updated in a number of configDropins (#3445, #3546)
2. Stop the server (or otherwise prevent write requests).
3. Perform a database back up.
4. Run the fhir-persistence-schema-4.11.0-cli.jar --update-schema command. If using a non-admin user (recommended), also perform the --grant-to action.
5. Deploy the new server.
6. Perform re-indexing of Patient, Practitioner, PractitionerRole and Encounter resource types.
   • The IBM FHIR Server now adds a resource instance to its own compartment, but for previously-ingested resources this requires reindexing.

Special considerations for upgrading to 4.11.0:

• "Undelete" actions (an update--PUT--of a resource after it has been deleted) are now passed to FHIRPersistenceInterceptor implementations as a "create".
• This release includes updated stored procedure logic that results in a different "action" code in the CHANGE_LOG table. There is no data migration step to change the value for previous interactions and so resource updates performed with previous versions of the FHIR Server will continue to result in the previous behavior in the history-system and history-type interactions (#3507).
• There is no support for migrating from the standard "resource payload in the DB" configuration to the new "resource payload in Azure Blob storage" feature.

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

• 4.10.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://hub.docker.com/r/ibmcom/ibm-fhir-server or download fhir-install-4.11.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.11.0-cli.jar
• fhir-swagger-generator-4.11.0-cli.jar
• fhir-bucket-4.11.0-cli.jar
• fhir-path-4.11.0-cli.jar

Usage is documented in the corresponding README files:

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

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