Releases: LinuxForHealth/FHIR
LinuxForHealth FHIR Server 5.1.1
This version of the LinuxForHealth FHIR Server supports HL7 FHIR versions 4.0.1 and 4.3.0.
This release includes dependency updates and important changes to the fhir-smart AuthzPolicyEnforcement interceptor.
Changed
- Dependency updates
- Including a bump from Liberty 2022.0.0.10 to 2022.0.0.12
- Remove the "batch" section from audit event messages for batch bundle entries
Fixed
Security
Migration Considerations
If upgrading from a version prior to 5.1.0, be sure to review the applicable 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.1.1.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.1.1-cli.jar
- fhir-swagger-generator-5.1.1-cli.jar
- fhir-bucket-5.1.1-cli.jar
- fhir-path-5.1.1-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.1.1
.
LinuxForHealth FHIR Server 5.1.0
This version of the LinuxForHealth FHIR Server supports HL7 FHIR versions 4.0.1 and 4.3.0.
This release fixes a 5.0.0 regression for resource types with long searchable strings and includes updates to validation and search paging.
Added
- DaVinci Payer Data Exchange (PDex) US Drug Formulary STU2
- Support for inheritance in FHIRPath is and as operators
- Validator support for pattern value constraints on FHIR Strings
- OperationOutcome warning to search response bundles when pages have shifted
Changed
- Upgrade to liberty 22.0.0.10
- Other dependency updates
- Avoid CodeQL warning by flipping logic around tenant config lookup
- With this change, we will no longer dynamically pick up new tenants from the filesystem. All tenants must have their config files in place prior to starting the server. Updates to existing tenant config will still be discovered dynamically.
- Replace IBM FHIR Server in /metadata CapabilityStatement
- Reduce the default initial heap size
- Refresh fhir-persistence-schema parameter-names.properties
Fixed
Security
Migration Considerations
To migrate from a prior version to version 5.1.0:
- Analyze configuration changes and prepare for the upgrade
- #3716 introduces
fhirServer/security/validateSecurityContext
; currently it only affects fhir-smart behavior
- #3716 introduces
- Deploy the new server.
If upgrading from a version prior to 5.0.0, be sure to review the applicable 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.1.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.1.0-cli.jar
- fhir-swagger-generator-5.1.0-cli.jar
- fhir-bucket-5.1.0-cli.jar
- fhir-path-5.1.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.1.0
.
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:
- the Citus distributed PostgreSQL backend for scale-out scenarios; and
- asynchronous search parameter indexing for improved ingestion performance
Both of these experimental features have important limitations to be aware of:
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
tobatchIdEncodingKey
- We also renamed the corresponding config property from
Removed
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:
- Analyze configuration changes and prepare for the upgrade
- Due to the package rename (
com.ibm
->org.linuxforhealth
),fhirServer/persistence/factoryClassname
andfhirServer/audit/serviceClassName
values must be updated in each fhir-server-config.json fhirServer/bulkdata/core/batchIdEncryptionKey
was renamed tofhirServer/bulkdata/core/batchIdEncodingKey
- Due to the package rename (
- Stop the server (or otherwise prevent write requests).
- Perform a database back up.
- Run the fhir-persistence-schema-5.0.0-cli.jar --update-schema command.
- Deploy the new server.
- 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
wasdb2
. 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:
Note: for schema migrations, ...
LinuxForHealth FHIR Server 5.0.0 RC2
The second release candidate 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 fixes minor issues found in the first release candidate.
The full release notes for this release candidate have been merged into the official 5.0.0 Release.
LinuxForHealth FHIR Server 5.0.0 RC1
The first release candidate 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:
- the Citus distributed PostgreSQL backend for scale-out scenarios; and
- asynchronous search parameter indexing for improved ingestion performance
Both of these experimental features have important limitations to be aware of:
The full release notes for this release candidate have been merged into the official 5.0.0 Release.
IBM FHIR Server 4.11.1
This version of the IBM FHIR Server supports HL7 FHIR Specification version v4.0.1.
Changed
- Dependency updates
- docker run should support control+c to exit process
- Establish process/procedure for rebuilding old images
Fixed
- Liberty openapi ui is missing style / unusable
- POST requests without an ID cause a NPE with fhir-smart enabled
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.1.zip and install as described at https://ibm.github.io/FHIR/guides/FHIRServerUsersGuide.
Note: starting with version 4.11.0, we will periodically rebuild our docker images in an attempt to keep vulnerabilities out of the base image.
If upgrading from a version prior to 4.11.0, be sure to review the applicable migration considerations:
Note: for schema migrations, only the latest version of the fhir-persistence-schema tool must be run.
Check the Assets section for downloads.
For Maven users, all project binaries are posted to Maven Central with a version of 4.11.1
.
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
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 ...
IBM FHIR Server 4.10.2
This version of the IBM FHIR Server supports HL7 FHIR Specification version v4.0.1.
Changed
- Dependency updates
- Perf improvement - guard FHIRPath evaluation during search interaction
- Reduce severity of failed membership checks for extensible and preferred bindings
Removed
Fixed
- FHIRGeneratorException when serializing
<div>
element in FHIR XML with custom TransformerFactory - Search response contains duplicate Element.id in certain cases
- Use of valid code from profile's extended binding results in misleading warning
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.2.zip and install as described at https://ibm.github.io/FHIR/guides/FHIRServerUsersGuide.
If upgrading from a version prior to 4.10.0, be sure to review the applicable migration considerations:
Note: for schema migrations, only the latest version of the fhir-persistence-schema tool must be run.
Check the Assets section for downloads.
For Maven users, all project binaries are posted to Maven Central with a version of 4.10.2
.
IBM FHIR Server 4.10.1
This version of the IBM FHIR Server supports HL7 FHIR Specification version v4.0.1.
This release bumps to OpenLiberty 21.0.0.11 to fix an intermittent NullPointerException we were seeing on IBM FHIR Server 4.10.0 with OpenLiberty 21.0.0.9.
Changed
Fixed
Using the Release
If upgrading from a version prior to 4.10.0, be sure to review the applicable migration considerations:
Note: for schema migrations, only the latest version of the fhir-persistence-schema tool must be run.
For Maven users, all project binaries are posted to Maven Central with a version of 4.10.1
.
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
- requires
- 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
- This change introduces
- Configure profiles that are not allowed to be used for validation
- This change introduces
fhirServer/resources/<resourceType>/profiles/notAllowed
- This change introduces
- 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
- A fhir-term-graph-loader docker image
- 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 offhirServer/resources/<resourceType>/profiles/atLeastOne
- This change introduces
- 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.
- This changeset includes new validation code for ascii control characters within string values. To opt out of this new validation, set
- 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.
- These have been moved to the new
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
Migration Considerations
To migrate from a prior version of the IBM FHIR Server to version 4.10.0:
- Analyze configuration changes and prepare for the upgrade
fhirServer/core/checkControlCharacters
defaults to truefhirServer/resources/<resourceType>/profiles/allowUnknown
default to true; set to false for backwards compatibility if (and only if) you were usingfhirServer/resources/<resourceType>/profiles/atLeastOne
fhirServer/resources/<resourceType>/profiles/notAllowed
; default is allow allfhirServer/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
- Stop the server (or otherwise prevent write requests).
- Perform a database back up.
- 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.
- Deploy the new server.
- 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 c...