IBM FHIR Server 4.6.0

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

This release moves datasource connection properties from fhir-server-config.json to Liberty server configDropins, completely revamps the bulkdata section of the fhir-server-config.json, introduces a high-speed whole-system "changes feed", modifies the IBM FHIR Server schema to handle composite search parameters more efficiently, and more.

For users upgrading from a previous release, please review the Migration Considerations before attempting the upgrade.

Added

• Support resource change tracking via whole-system history changes feed
• Support token modifier ':not'
• Support for ":missing" modifiers on chained parameters and whole-system search parameters
• bootstrap.sh entrypoint for the ibmcom/ibm-fhir-server image
  • bootstrap a derby database for the default tenant's default datastore by setting BOOTSTRAP_DB=true
• FHIRNotificationService should emit event for delete
• Tenant id and datastore id on FHIRNotificationEvent
• Support PATCH as part of a bundled request (batch and transaction)
• Narrative.EMPTY constant for 'empty' narrative text
• Bulk Data Audit Logging
• Bulk import/export from the local filesystem
• Use COS/S3 presign-url for download URLs of bulkdata export results
  • only supported when using HMAC authentication with an S3-compatible storageProvider

Changed

• Refactoring of the fhirServer/bulkdata configuration
  • Note: bulkdata jobs created prior to 4.6.0 will no longer run and must be re-created
  • See Migration Considerations below for information on adapting fhir-server-config.json from a previous version
• Retire the fhirProxyDatasource in favor of Liberty JDBC datasource configuration
  • Note: with this change, we no longer package fhir-persistence-proxy (or its dependencies) under the Liberty shared resources directory
  • See Migration Considerations below for information on adapting fhir-server-config.json from a previous version
• Change current Branch Naming to Main
• Upgrade liberty, postgresql, db2, and cxf
• Upgrade Pom.xml to latest versions of Dependencies
• Regenerated default certificates for client and server
  • the old certificates expire in April of 2021; the new certificates are valid for 30 years
  • these certificates should still be replaced in production deployments of the IBM FHIR Server
• fhir-audit: Ensure HOSTNAME is obtained correctly and consistently
• Do not log full stack trace for a simple 404 not found
• Normalize token values used for composite parameters
• fhir-persistence-schema --update-schema action now performs --refresh-tenants for associated tenants

Removed

• Support for FHIRProxyXADataSource
  • Users of the FHIRProxyXADataSource must move their db connection information to Liberty configDropins as described at https://ibm.github.io/FHIR/guides/FHIRServerUsersGuide#331-the-jdbc-persistence-layer
• Derby DB bootstrapping during server startup
  • This was replaced by a custom entrypoint script in the docker image. See https://hub.docker.com/r/ibmcom/ibm-fhir-server for more information.
  • For FHIR Server developers using non-Docker servers, we delivered a bash script which accomplishes the same thing as the old bootstrap process...useful for preparing your environment for executing fhir-server-test.

Fixed

• Getting FHIR notifications for all resources including those not listed in the 'includeResourceTypes' field
• Duplicate Job Parameters fhir.dataSourcesInfo are created
• Link urls are wrong when originalRequestUriHeader contains unencoded pipe
• FullUrl of whole-system search response bundle entries improperly contain query parameters
• PostgreSQL poor search performance with multiple search parameters on a Compartment Search
• Auditing work performed when auditing is turned off for the fhir-server
• ConfigDropins for Bulkdata.xml is specified incorrectly for db2
• AuthzPolicyEnforcement interceptor returns 500 for select client errors
• Schema name case normalization is not working as expected
• fhir-persistence-schema cli contains unnecessary dependencies
• Relative References with the Same Logical Identifier should throw an error
• Bulk Data Client Fails with Fault on ReflectionUtil
• Bulkdata - Timeouts on Derby/Db2
• NullPointer in ImportJobListener.afterJob
• Fast export implementation fails to close GZIPInputStream

Security

• CVE-2020-28491: com.fasterxml.jackson.dataformat:jackson-dataformat-cbor:jar:2.10.0:compile is used in fhir-bucket and fhir-bulkimportexport-webapp

Migration Considerations

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

1. Analyze configuration changes and prepare for the upgrade
   • remove persistence/jdbc/enableProxyDatasource from fhir-server-config.json
   • remove persistence/jdbc/dataSourceJndiName from fhir-server-config.json
   • remove persistence/datasources/<dsid>/connectionProperties and put the connection information into a configDropin as documented in the User's Guide
   • ensure there are no references to the com.ibm.fhir.persistence.proxy.FHIRProxyXADataSource jdbcDriver in your server.xml or configDropins (this used to be in our default server.xml but was removed along with the implementation)
   • for bulkdata users, the bulkdata configuration section of fhir-server-config.json has been totally reworked; please see the User's Guide for updated configuration information
2. Stop the server (or otherwise prevent write requests).
3. Perform a database back up.
4. Run the fhir-persistence-schema --update-schema command. If using a non-admin user (recommended), also perform the --grant-to action. Note: it is no longer necessary to separately invoke --refresh-tenants.
5. Deploy the new server.
6. Perform re-indexing. Note that this step is only required for resources with composite search values.

Covered in these steps are one-time special considerations for upgrading to 4.6.0:

• For #1955, we introduced a new table named RESOURCE_CHANGE_LOG which stores all resource changes (creates, updates, and deletes) and serves the new whole-system history interaction. If (and only if) this table is empty, the --update-schema action will auto-populate this table with historical data from the database.
• For #1929, we introduced a new index. This can take a while to populate (~1000s on our test DB with ~10M resources).
• For #1958 and #2011, we introduced IS_DELETED and LAST_UPDATED columns to the x_LOGICAL_RESOURCES tables. These columns are automatically populated from the database as part of the --update-schema action.
• For #1683, we removed the x_COMPOSITES tables from the database and added a new composite_id column to the x_y_VALUES tables in its stead. Populating these new column values is what requires the re-index and so this step can be skipped for resource types that have no search parameters of type composite.

Using the Release

Run or extend the Docker image from https://hub.docker.com/r/ibmcom/ibm-fhir-server or download fhir-server-distribution.zip and install as described at https://ibm.github.io/FHIR/guides/FHIRServerUsersGuide.

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

• fhir-persistence-schema-4.6.0-cli.jar
• fhir-swagger-generator-4.6.0-cli.jar
• fhir-bucket-4.6.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

For Maven users, all project binaries are posted to BinTray with a version of 4.6.0.

Please note as of 2021-MAY-01, JCenter is shutting down BinTray. The libraries, as of that date, are no longer available on BinTray. Please download the release-repo-4.6.0.zip to cache your repository locally.