IBM FHIR Server 4.9.2

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

This release includes important dependency updates and focuses on mostly bug fixes.

Changed

• FHIRPathSpecTest update and related changes to the FHIRPath engine
• Mark janusgraph-cql and janusgraph-es as provided
  • Users of fhir-term-graph with the cassandra backend / elasticsearch index will now need to package these themselves; the berkelydb+lucene option is still included in the default image.
• Better error messages for bad conditional references
• Enforce OperationDefinition affectsState

Fixed

• fhir-bucket process should exit after reindex failure
• BulkData: Delete Job
• Calling DELETE on $bulkdata-status for a running job produces strange results
• fhir-persistence-schema CLI drop-admin does not clear out the fhir_admin schema
• Using fhir-persistence-schema CLI tool to drop schema gives an error
• Drop schema options don't work for Oauth and JBatch schemas
• WARNING: An illegal reflective access operation has occurred

Security

• Update to the latest janusgraph and gremlin
  • These are only used when the FHIRTermGraph provider is enabled.
• Numerous minor dependency updates

Migration Considerations

Under issue #2757 we removed janusgraph-cql and janusgraph-es from our default packaging. Users of the fhir-term-graph module with an Apache Cassandra backend or an ElasticSearch index will need to package these dependencies themselves.

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

• 4.9.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.9.2.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.9.2-cli.jar
• fhir-swagger-generator-4.9.2-cli.jar
• fhir-bucket-4.9.2-cli.jar
• fhir-path-4.9.2-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.9.2.

IBM FHIR Server 4.9.1

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

This release includes important dependency updates and focuses on fixing bugs and improving canonical reference search.

Added

• Support for deploying via Helm chart
  • the helm chart source is at https://github.com/Alvearie/alvearie-helm and we've published a helm repo and registered it at https://artifacthub.io/packages/helm/alvearie/ibm-fhir-server
• Support for searching via canonical references

Changed

• Performance enhancement: retrieve uncached COMMON_TOKEN_VALUE_IDs in a single request
• $bulkdata-status needs to indicate when no data was exported
• FHIRNotificationService should emit event for patch update
• FHIRPath cli output should indicate field names and hierarchy
• Make 'requiresAccessToken' configurable in the Bulk Export Status Report
  • This change introduces config parameter fhirServer/bulkdata/storageProviders/" + provider + "/requiresAccessToken
• Bulk Export Status should contain the required "error" field

Deprecated

• Old fhir-persistence-jdbc caches and related methods

Fixed

• Threading issue using static Calendar with JDBC ResultSet.getTimestamp
• System-only search of chained token parms and global _profile, _tag, and _security parms results in unexpected errors
• Bulkdata Enable Parquet uses old style configuration and fails upon Parquet usage
• Bulkdata with parquet results in stackoverflow
• CodeSystem/$validate-code causes and NPE when display is not present in the data
• NPE when sending an invalid content with an invalid operationdefinition on Translate
• Composition/$document reports a 500 when it's a bad user request.
• JSON Patch test operation should not result in a new resource version
• On a patch passing in a unsuported operator causes errror
• BulkData: Delete Job

Security

• Update ibm cos dependencies
• Update azure dependencies

Migration Considerations

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

1. Analyze configuration changes and prepare for the upgrade
   • Config parameter fhirServer/bulkdata/storageProviders/" + provider + "/requiresAccessToken was added for #2714
2. Deploy the new server.
3. Perform re-indexing.
   • Re-indexing is required to take advantage of the new canonical search behavior added in #772

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

• 4.9.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.9.1.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.9.1-cli.jar
• fhir-swagger-generator-4.9.1-cli.jar
• fhir-bucket-4.9.1-cli.jar
• fhir-path-4.9.1-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.9.1.

IBM FHIR Server 4.9.0

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

This release focuses on whole-system search and reindex performance.

Added

• Dedicated tables for whole-system-search parameters _security, _profile, and _tag
  • see migration considerations for info on populating the new tables for existing resources
• Drive reindex using client side checkpointing for improved throughput
• Support for Pattern Value Constraint with $this in the Path
• Support for slice-specific constraints
• Quantity search now considers the quantity comparator field
• Support revocation of tenant keys (Db2)
• Custom operations for clearing terminology caches
• Export to Azure Blob storage
• Configurable "fail fast" validation
• fhir-smart support for user/ scopes
  • The interceptor now allows interactions with resource types covered by user/<resourceType>.<permission> scopes in the access token, but operators will still want to add their own permissions model on top.
• Support static configuration of external FHIR base URL (in favor of originalRequestUriHeader)
  • This introduces config property fhirServer/core/externalBaseUrl for statically setting the server's base url

Changed

• Improve reindex performance by skipping resources with no search parameter changes
• whole-system-search: use global parameter tables in whole system search join
• expand support for $reindex to the Type and Instance levels
• token search for |<code> should only match codes with no systems
• improve error handling for remote term service poor responses
• replace Java Streams with conventional loop in FHIRPathEvaluator for improved perf
• improve performance for date range searches
• fhir-notification: special handling for resources over 1M
• Use the "skippableUpdate" optimization during bulk import
• Make schema drop idempotent
• Upgrade to the latest SPL snapshot
• Dockerfile should ensure directories are writable by root group (gid=0)

Deprecated

• the old query builder
• the (base)/Resource and (base)/DomainResource endpoints

Removed

• fhir-cli
• the exportPublic + ACL-based approach to exported object expiry

Fixed

• Strange behavior with lt and gt prefixes when searching by date / partial dateTime
• _sort not working correctly with id value
• Whole-system search using _id parameter performs poorly
• poor performance for whole-system search with _lastUpdated
• Concurrency issue during apply FHIRPathPatchReplace
• reindex process slows after some hours when Postgres vacuuming falls behind
  • this change includes a postgresql-only schema change that makes autovacuuming more aggressive for tables that are heavily updated during reindex
• OperationDefinition.name and OperationDefinition.code inconsistent between FHIRRestHelpers and FHIROperationRegistry
• NPE thrown in FHIRPathUtil.getResourceNodes(FHIRPathTree tree, FHIRPathNode node) when FHIRPathNode is not in FHIRPathTree
• FHIRPath conformsTo loops can lead to StackOverflow
• Reindex Returns 500 when the Client sends a bad timestamp
• Vanity URLs with AWS result in bucket NOT_FOUND on $import
• When multiple tenants exist, Drop Tenant Results in an incorrect FHIRDATA.PARAMETER_NAMES association and drop.
• $import Exit Status on Matrixed Resources results in NPE
• fhir-bucket ignores --schema-name when running scan and load
• fhir-persistance-schema-cli update-schema not updating functions.
• Under certain conditions, the root cause of a BundledRequestException is never logged
• Discriminator incorrectly generated for profile constraints
• When using _total=none, a "next" link is generated when there isn't a "next" page
• non-fast bulk export writes to many files instead of honoring settings
• file based export resulting in multiple files is not reported correctly by $bulkdata-status

Security

• fhir-smart interceptor should enforce scope permissions up front

Migration Considerations

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

1. Analyze configuration changes and prepare for the upgrade
   • fhirServer/core/externalBaseUrl is introduced as an alternative to constructing the baseUrl from the value of the configured "originalRequestUriHeaderName"
   • fhirServer/bulkdata/storageProviders/(source)/exportPublic has been removed
   • fhirServer/notifications/common/maxNotificationSizeBytes and fhirServer/notifications/common/maxNotificationSizeBehavior were introduced for controlling the notification behavior for large messages
   • fhirServer/validation/failFast was introduced to make it possible to ask the validator to fail on the first error
   • fhirServer/search/enableLegacyWholeSystemSearchParams was introduced to allow whole-system param queries to continue working after migration and before a complete reindex. This parameter should be added and set to true before migration.
2. Stop the server (or otherwise prevent write requests).
3. Perform a database back up.
4. Run the fhir-persistence-schema-4.9.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.
   • Needed for #264. See special considerations for more info.
7. Remove fhirServer/search/enableLegacyWholeSystemSearchParams (or explicitly set it to false)

Special considerations for upgrading to 4.9.0:

• The schema migration for 4.9.0 adds columns to the whole-system logical_resources table and populates these columns for each resource in the database. This can be a lengthy process (9 hours on our PostgreSQL database with ~80 million resources). We have tested on-line migration (serving read-only requests while the update is live) and encountered no issue, but care should be taken to avoid potential impact to end users.
• Starting in 4.9.0, the $reindex operation will skip resources with no search parameter changes. However, this is driven by a new column in the database that stores the hash of the parameter values and so the first reindex after upgrading will populate that column for all resources.
• The location of _security, _tag, and _profile search parameter values is updated in 4.9.0. To ensure that queries continue to work as expected during migration, please use the newly introduced fhirServer/search/enableLegacyWholeSystemSearchParams parameter. When set to true, ingestion and reindexing will extract the value to both locations and searches will look in the old location. When set to false (the default), ingestion and reindexing and search will use only the new location which is expected to yield improved performance for select queries.

Using the Release

Run or extend the Docker image from https://hub.docker.com/r/ibmcom/ibm-fhir-server or download fhir-install-4.9.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.9.0-cli.jar
• [fhir-swagger-generator-4.9.0-cli.jar](https://github.com/IBM/FHIR/rele...

IBM FHIR Server 4.8.3

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

This release focuses on fixing bugs, improving performance, and adding support for customizable compartment definitions.

Added

• Support for non-validating builders / parsers
• Support for MIME-type parameter fhirVersion
• Ability to configure headers in RemoteTermServiceProvider configuration
• Support customizable compartment definitions

Changed

• Skip "parse validation" while reading resources from the database
  • we expect this change to be a noticeable performance improvement for read, vread, history, and update interactions
• Avoid redundant reads during update interaction
• resolve function in FHIRPATH expression
  • introduced fhirServer/core/serverResolveFunctionEnabled (default=false) for controlling whether the server should resolve references from the database when evaluating FHIRPath expressions
• The default fhir-server-config file-based bulk storageProvider should point to an existing directory
• Set more specific batch bundle action in audit event when possible
• Add warning to fhir-persistence-schema about the plan to remove the Resource and DomainResource table groups

Deprecated

• FHIRParser.PROPERTY_IGNORE_UNRECOGNIZED_ELEMENTS
  • use FHIRParser.setIgnoringUnrecognizedElements(boolean) instead
• fhirServer/search/useStoredCompartmentParam
  • we already changed the default from false to true in 4.6.1; this is a notice that we plan to remove this config option in the future
• All of the following schema tables

  DOMAINRESOURCE_DATE_VALUES
  DOMAINRESOURCE_LATLNG_VALUES
  DOMAINRESOURCE_LOGICAL_RESOURCES
  DOMAINRESOURCE_NUMBER_VALUES
  DOMAINRESOURCE_QUANTITY_VALUES
  DOMAINRESOURCE_RESOURCE_TOKEN_REFS
  DOMAINRESOURCE_RESOURCES
  DOMAINRESOURCE_STR_VALUES
  RESOURCE_DATE_VALUES
  RESOURCE_LATLNG_VALUES
  RESOURCE_LOGICAL_RESOURCES
  RESOURCE_NUMBER_VALUES
  RESOURCE_QUANTITY_VALUES
  RESOURCE_RESOURCE_TOKEN_REFS
  RESOURCE_RESOURCES
  RESOURCE_STR_VALUES
  

• The fhir-server-distribution.zip name (deprecated in 4.8.0)

Fixed

• IBM FHIR Server CapabilityStatement is invalid
• Trouble with the Liberty OpenAPI feature
• Deadlock during concurrent updates on Derby
• XAER_OUTSIDE when BulkData Export on Patient is run twice
• Error on bulk data status call where import did not import anything.
• Missing identifier modifier in FHIRParameters.Modifier enum
• FHIRClient.getWebTarget(String baseURL) throws NPE
• FHIR Persistence schema updateSchema has a second call to the updateProc which shouldn't be necessary.
• Unable to disambiguate inherited fields in fhir-model
• CARIN BB service-date doesn't search on ExplanationOfBenefit.item.servicedDate
  • this fix requires a reindex of previously-ingested ExplanationOfBenefit resources in order to take affect
• CARIN BB Institutional EOB 'adjudication-has-amount-type-slice' constraints are not specified correctly

Migration Considerations

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

1. Analyze configuration changes and prepare for the upgrade:
   • #2296 introduces fhirServer/core/serverResolveFunctionEnabled (default=false) for controlling whether the server should resolve references from the database when evaluating FHIRPath expressions (e.g. for constraint evaluation)
   • Derby and Db2 dataSource elements should now have isolationLevel="TRANSACTION_READ_COMMITTED"
     • This setting is not needed for PostgreSQL dataSources
2. Deploy the new server.
3. If using the CARIN for BlueButton implementation guide, a reindex of ExplanationOfBenefit resources is required for #2460.

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

• 4.8.2 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.8.3.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.8.3-cli.jar
• fhir-swagger-generator-4.8.3-cli.jar
• fhir-bucket-4.8.3-cli.jar
• fhir-path-4.8.3-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, project binaries are posted to Maven Central with a version of 4.8.3.

4.8.3 is the first release in which we've decided not to re-release the fhir-examples module (as there are no updates since 4.8.2). We will likely split this module into a separate repo with its own release cadence at some point in the future.

IBM FHIR Server 4.8.2

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

This release contains select fixes on top of 4.8.1.

Fixed

• Concurrent updates to the same resource can result in lost updates
  • This fix includes updates to the stored procedures for both PostgreSQL and IBM Db2. See migration considerations for information on deploying these updates.
• Patient/$everything without a patientId results in a Null response.
• Erase operation is repeated many times in the CapabilityStatement

Deprecated

• The fhir-server-distribution.zip name (deprecated in 4.8.0)

Migration Considerations

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

1. Stop the server (or otherwise prevent write requests).
2. Optional: Perform a database back up.
3. Run the fhir-persistence-schema-4.8.2-cli.jar --update-schema command. If using a non-admin user (recommended), also perform the --grant-to action.
4. Deploy the new server.

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

• 4.8.1 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.8.2.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.8.2-cli.jar
• fhir-swagger-generator-4.8.2-cli.jar
• fhir-bucket-4.8.2-cli.jar
• fhir-path-4.8.2-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.8.2.

IBM FHIR Server 4.8.1

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

This release includes dependency updates, validation support for canonical pattern constraints (needed for the next revision of CARIN for BlueButton), and other minor changes as described below.

Added

• Validation support for Pattern Value Constraint with $this in the Path
• Provide configurable properties for max page size and max number of included resources on search results
• Support different default bulkdata storageProviders for import vs export

Changed

• Allow persistence interceptors to modify the incoming resource
• Load compartment definitions from the registry

Deprecated

• exportPublic + ACL-based approach to exported object expiry
• The fhir-server-distribution.zip name (deprecated in 4.8.0)

Fixed

• FetchResourcePayloadsDAO hits an error condition under debug without _since parameter

Security

• Update dependencies per Sonatype Lift CVE Report

Migration Considerations

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

1. Analyze configuration changes and prepare for the upgrade
   • The bulkdata configuration in fhir-server-config.json now supports designating a default storageProvider for import and export.
   • The bulkdata exportPublic property is now deprecated. All bulk export users relying on S3 ACL-based expiry should move to presigned URLs as described in the User's Guide.
   • #1868 introduces fhirServer/core/maxPageSize and fhirServer/core/maxPageIncludeCount for overriding the default max page size (1000) and max number of resources to include on a single page (1000).
   • #2296 introduces fhirServer/core/serverResolveFunctionEnabled (default=false) for controlling whether the server should resolve resources from the database (or not); for example during validation while evaluating fhirpath constraints.
2. Deploy the new server.

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

• 4.8.0 migration considerations

Using the Release

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

IBM FHIR Server 4.8.0

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

This release introduces a custom operation for the hard deletion of resources ($erase) and focuses on improving search query performance and fixing bugs.

Added

• $erase operation for the hard deletion of a resource (or a specific resource version)
  • This change introduces a new stored procedure and therefor requires a schema update.
  • This change also introduces a new configuration section under fhirServer/operations/erase.
  • See the migration considerations for more detail.
• Expand support of X-FHIR-UPDATE-IF-MODIFIED to batch/transaction entries
• Resolve conditional references while processing transaction bundles
• A new JDBC query builder
  • Set fhirServer/search/enableOptQueryBuilder to false to opt out of the new query builder and continue using the legacy query builder instead.
• Experimental support for the Structured Product Labeling (SPL) Implementation Guide
• Support generating constraints from slices with the "profile" discriminator type
• Documentation on how to use Keycloak with FHIR
• Support for searching a token by codesystem, irrespective of the value ([system]|)
• Support for the TerminologyCapabilities resource via the capabilities interaction
• Support for designating the default version of registry resources

Changed

• Use the new is_deleted and last_updated columns from xx_LOGICAL_RESOURCES to eliminate joins
• Rework search queries to avoid DISTINCT
• Conflicting search parameters messages should note the full URL of the conflict code
• Make quantity values searchable even without unit or code
• Rename fhir-model code subtype nested classes from ValueSet to Value
• Populate Bundle.entry.response.outcome with validation warnings
• Ensure bundle requests with DELETE entries behave similarly to non-bundle DELETEs
• FHIR primitive static factory helpers should throw appropriate exception when null is passed
• trustDefaultCerts=true by default in liberty configuration (server.xml)
• Trim whitespace from values in schema tool property files
• Bundles with all GET requests can use a single transaction for better performance
• Update Capabilities.java to use fhir-cache

Deprecated

• The fhir-server-distribution.zip name
  • When we moved from Bintray to Maven Central, we noticed that our zip installer reverted back to the default maven name (fhir-install-VERSION.zip) and we plan to publish only this versioned name for the zip installer going forward.
• fhir-model nested ValueSet enum (and related helpers) in code subtypes
  • use the new nested enum named Value instead

Fixed

• Token search should be case-insensitive when the system being searched is case-insensitive
• Implicit base not picked up for the patient search parameter
• Out of shared memory error while dropping fhir schema using ibm cloud databases for postgresql
• With the transaction timeout set unreasonably low, the resulting error does not reflect a timeout
• Equivalency check for X-FHIR-UPDATE-IF-MODIFIED fails to account for identifier updates
• Null pointer on custom operations invoked at the resource-type level for resource types that don't exist
• Search with both '_total=none' and '_include' or '_revinclude' parameter fails with FHIRPersistenceDataAccessException
• Allocate Tenant without TenantKey Fails in the ibm-fhir-schematool on db2
• Unexpected IllegalArgumentException --schema-name 'TEST1' argument does not match tenant schema: 'TEST1 '
• Empty Schema and Missing version Table results in Exception for list-tenants
• Misleading error message during $lookup for non-existent CodeSystem
• Conditional delete operation outcome has nulls in issue details

Migration Considerations

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

1. Analyze configuration changes and prepare for the upgrade:
   • #2326 introduces fhirServer/search/enableOptQueryBuilder for controlling whether or not to use the optimized query builder (default=true)
   • #850 introduces new properties enabled (default=false) and allowedRoles (default=all) under fhirServer/operations/erase.
2. Stop the server (or otherwise prevent write requests).
3. Optional: perform a database back up
4. Run the fhir-persistence-schema-4.8.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.
   • needed to support searching quantity values without a unit or code
   • needed to support searching on token parameters (with a system) where the system is known and marked as case-sensitive

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

• 4.7.1 migration considerations

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, fhir-bucket, and fhir-path projects are also available:

• fhir-persistence-schema-4.8.0-cli.jar
• fhir-swagger-generator-4.8.0-cli.jar
• fhir-bucket-4.8.0-cli.jar
• fhir-path-4.8.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.8.0

IBM FHIR Server 4.7.1

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

This release introduces support for integration with external terminology servers, fixes caching-related issues in terminology support, and adds support for skipping unnecessary update interactions.

Added

• Support client opt-in for skipping the update if a resource hasn't changed
  • Clients can now pass the header X-FHIR-UPDATE-IF-MODIFIED with a value of true to ask the server to skip the update when the proposed resource matches the existing resource.
• Remote terminology service provider using a REST client
• Support opt-in to warnings when search parameters are ignored

Changed

• AuthzPolicyEnforcement changes
  • The compartment-based authorization decision will now match our compartment-based search behavior, meaning that inclusion criteria with a versioned reference or absolute reference that matches the base server url will now be considered to be in the referenced compartment.
• Optionally reject references without explicit resource type
  • This tightens the validation of relative literal references to flag a common error we've seen. Set the existing fhirServer/core/checkReferenceTypes property to false to opt out of this enhanced validation.
• Ensure all OperationDefinition resources are pulled from FHIRRegistry for specification-defined operations

Fixed

• opd-0 warnings during startup
• Global caches in CodeSystemSupport and ValueSetSupport should be tenant-specific
• ServerRegistryResourceProvider cache invalidation is problematic in multi-server environments
• Failure acquiring local host IP address results in 400 errors but should be 500s
• $apply operation error when specifying practitioner
• fhir-provider tries to use httpHeaders and uriInfo in client mode
  • This change enables the fhir-provider to be used as a generic JAX-RS provider for FHIR resources.

Migration Considerations

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

1. Analyze configuration changes and prepare for the upgrade
   • This release adds support for configuring multiple graphTermServiceProviders. The fhirServer/term/remoteTermServiceProvider property is now fhirServer/term/remoteTermServiceProviders and it is now an array of objects instead of a single object.
   • This release introduces numerous properties under fhirServer/term/remoteTermServiceProviders. See the Terminology guide for more information.
2. Deploy the new server.

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

• 4.7.0 migration considerations

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, fhir-bucket, and fhir-path projects are also available:

• fhir-persistence-schema-4.7.1-cli.jar
• fhir-swagger-generator-4.7.1-cli.jar
• fhir-bucket-4.7.1-cli.jar
• fhir-path-4.7.1-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.7.1.

IBM FHIR Server 4.7.0

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

This release expands search behavior, introduces a new experimental fhir-term-graph module, includes numerous dependency updates, and makes significant changes to the ibmcom/ibm-fhir-server docker image.

Per JFrog, BinTray is being sunset. The IBM FHIR Server team has transitioned to Open Source Repository Hosting by Sonatype, and sychronizes to Maven Central. To reference any dependency in this project, please remove any existing references to Bintray in the <repositories> tag of your pom.xml, and recompile with the latest version.

Added

• Maturity level annotations and javadoc to the fhir-model resource classes
• Support _total with _include and _revinclude
• Support _sort with _include and _revinclude
• Support token modifier ':text'
  • Reindex is required to take advantage of this feature
• Support token modifiers ':in' and ':not-in'
• Support token modifiers ':above' and ':below'
• FHIR Search Feature: _include:iterate
• Support compartment search via POST
• Configurable expiration time for exported objects
  • This change introduces fhirServer/bulkdata/core/cos/presignedExpiry for controlling the expiry (in seconds) of bulk data download urls (when using S3/COS storage provider with HMAC authentication and presign set to true).
• Introduce fhir-term-graph module
• Support for implicit value sets
• Javadoc and convenience methods for Base64Binary
• FHIRPath CLI
• Compartment search variants to generated swagger / openapi
• POST [base]/[type]/_search to generated swagger / openapi
• Configuration option to control the default page size
  • This change introduces fhirServer/core/defaultPageSize

Changed

• Upgrade to liberty 21.0.0.3
• Make it more obvious how to obtain primitive values from FHIRPathSystemValue
• Refactor fhir-term module
• More efficiently handle closure operation requests that have more than one coding
• Improve the docker image
  • We changed the liberty server name from fhir-server to defaultServer and modified how the image gets built; build times are longer but startup time is roughly 3x faster. We also moved from the Java 8 version of liberty to the Java 11 version.
• JSON Schema Clarification on required and minItems Validation Keywords
• Throw an exception when a value set include filter cannot be applied or a concept filter cannot be created
• Return an empty body when the healthcheck passes
• Construction of empty resource objects is now allowed
• Patient/$everything enabled by default

Deprecated

• list variants of ValidationSupport.requireNonEmpty and ValidationSupport.requireNonNull
• ValidationSupport.requireChildren

Removed

• commit() and rollback() methods from FHIRPersistenceTransaction
• LocalResourceReferenceRec (no longer used)
• fhir-persistence-proxy from the project build

Fixed

• Patch Replaces Can Save Invalid Types
  • This change also modifies the response code for FHIRPath errors during a FHIRPath Patch from HTTP 500 (Sever Error) to HTTP 400 (Bad Request)
• Everything Operation doesn't respond correctly to deleted resources
• Fast export impl 'txTimeoutMillis' should be set relative to the configured transaction timeout
  • This change introduces fhirServer/bulkdata/core/maxChunkReadTime for setting the amount of time to read resources from the persistence layer before we checkpoint, which must be less than the configured transaction timeout.
• Avoid 'stream was already closed' when the client hangs up early
• Avoid the useless warning for jaxb-core,jaxb-api not found
• Add missing definitions to the metatadata swagger
• Dropping admin schema fails with: ERROR: syntax error at or near "VARIABLE"
• fhir-bucket: Drive Reindex Operation thread should exit after error
• FHIROpenApiGenerator generates invalid discriminator for OpenAPI 3

Migration Considerations

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

1. Analyze configuration changes and prepare for the upgrade
   • This release introduces fhirServer/bulkdata/core/cos/presignedExpiry, fhirServer/core/defaultPageSize, and fhirServer/bulkdata/core/maxChunkReadTime as described above.
   • This release introduces numerous new properties under fhirServer/term/graphTermServiceProvider for new, experimental, Graph-based terminology provider.
   • For users of the ibmcom/ibm-fhir-server docker image, the liberty server name has changed from fhir-server to defaultServer. All absolute path references to the server's location within the image must be updated.
2. Deploy the new server.
3. Perform re-indexing.
   • Needed to enable support for token modifier ':text'

There are no database schema updates associated with this release, but fhir-persistence-schema-4.7.0-cli.jar --update-schema will be required for upgrading from versions prior to 4.6.1

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

• 4.6.1 migration considerations
• 4.6.0 migration considerations

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.7.0-cli.jar
• fhir-swagger-generator-4.7.0-cli.jar
• fhir-bucket-4.7.0-cli.jar
• fhir-path-4.7.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.7.0.

IBM FHIR Server 4.6.1

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

This release focuses on fixing bulk import/export bugs, adding additional search options, and introduces an initial implementation of the Patient/$everything operation.

Added

• VERSION to the xx_LOGICAL_RESOURCES
  • this sets us up to reduce the number of joins in select queries (#1385)
  • see migration considerations
• $everything operation
  • note that this operation is not yet included in the default fhir server installer / docker image; add the jar to the server's userlib directory to enable it
• Support _total parameter in search requests
• Support for searching references by identifier
  • requires reindex, per migration considerations
• Support token modifier ':of-type'
  • requires reindex, per migration considerations

Changed

• Make useStoredCompartmentParam the default
  • when migrating from versions prior to 4.5.1, a reindex will be required for proper compartment search behavior (unless useStoredCompartmentParam is explicitly set to false)
  • see migration considerations for additional reindex information
• File-based export should start writing earlier
• File-based exports should be organized by subdirectory
• Replace ByteArrayInputStream and ByteArrayOutputStream usage with more efficient solution
• Use the internal patient compartment search parameter during Patient/Group export

Fixed

• Reindex on Db2 doesn't execute with MT_ID flag
• fhir-persistence-schema doesn't drop schemas as expected on postgres
• Under certain conditions, $reindex attempts to index a deleted resource
• Under certain conditions, bulk import fails to acquire a db connection
• Patient Export without Type results in a failed export
• References in Patient Export are not honored
• Patient Export Results in duplicate data included in the Write.
• Patient resources are is not exported when asked for during Group Export
• File-based export writes empty files
• $import is skipping the first entry in the import file
• Overall total and importRate metrics are wrong after bulk data import

Security

• Relative path enables malicious content to be imported or /dev/null

Migration Considerations

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

1. Analyze configuration changes and prepare for the upgrade
   • See #2111 for a change in the default value of fhirServer/search/useStoredCompartmentParam
2. Stop the server (or otherwise prevent write requests).
3. Perform a database back up.
4. Run the fhir-persistence-schema-4.6.1-cli.jar --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.
   • Needed for #773 and #1323

Special considerations for upgrading to 4.6.1:

• For #2109 we added a column to the xx_LOGICAL_RESOURCES tables. The --update-schema action will automatically fill in the data, but the execution time will be dependent on the number of resources to backfill.

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.1-cli.jar
• fhir-swagger-generator-4.6.1-cli.jar
• fhir-bucket-4.6.1-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.1.