Current Firely Server release notes (v6.x)

Note

For information on how to upgrade, please have a look at our documentation on Upgrading Firely Server. You can download the binaries of the latest version from this site, or pull the latest docker image:

docker pull firely/server:latest

Release 6.0.0, April 15th, 2025

Firely is proud to announce a new major version of Firely Server. This release represents a significant step forward in our commitment to providing a reliable, compliant, and easy to use FHIR server. With this new version, we’ve focused on delivering:

support for Sharding with MongoDB (see MongoDB Sharding)
zero-downtime migrations with MongoDB (see Zero-downtime Migration)
detailed insights into Firely Server deployments based on OpenTelemetry metrics and traces (see OpenTelemetry)
improved integration into existing infrastructures with Kafka support for Firely Server PubSub (see Configuration)
out-of-the-box compliance with more HL7 DaVinci Implementation Guides, e.g. by providing support for the HRex $member-match operation (see Da Vinci - Da Vinci Payer Data Exchange)
flexibility for deployments requiring multi-tenancy (see Multi-tenancy)

Please study the release notes carefully as they contain breaking changes to the behavior of Firely Server, as well as the configuration of the server. Our support team is happy to provide assistance in the upgrade and can be reached at server@fire.ly or through the support desk. Need hands-on support with your upgrade? Our expert consultants are here to help. Explore our Upgrade Support Package to get started.

Note

With the release of Firely Server 6.0, we will officially stop support for Firely Server v4.x. We will continue supporting customers that run Firely Server v5.x.

Security

To avoid accidentally granting access to AccessPolicies, AccessPolicy resources cannot be accessed by a resource wildcard scope. E.g. system/*.* should be replaced with - system/AccessPolicy.* to be able to access AccessPolicy resources.
The $lastN operation can now be used with in combination with permissions defined in an AccessPolicy resource.
Intreractions with system-level scopes where the token is bound to a fhirUser of type Device will be rejected if no matching AccessPolicy can be found.

Database

Raised the minimum supported version of MongoDB to 6.0 to enable sharding.
Sharding is now natively supported by Firely Server when using MongoDB as the database backend (see MongoDB Sharding). Sharding improves the read/write performance of Firely Server. A new license token is required for this feature. Please contact us for an updated license.
Virtual multi-tenancy can now be enabled to logically separate stored resources in the database. The tenant identifier can be retrieved either from an HTTP header value or from a token claim (see Multi-tenancy).
Firely Server Ingest can now auto-provision the target database to facilitate zero-downtime migrations (see Zero-downtime Migration). A new license token is required for this feature. Please contact us for an updated license.

Attention

Firely Server requires a schema upgrade to version v28 of the database. This is only required for MongoDB database backends. The migration MUST be done using the zero-downtime migration process.

Features

Firely Server now implements the $member-match operation to find members of a health plan based on demographic information. See HRex Member Match - $member-match for more information.
Traces and ASP .NET metrics based on OpenTelemetry can now be exported to OTLP-enabled backends. See OpenTelemetry for more information.
memberOf() expressions are now supported in FHIRPath constraints when validating resources.
Added support for validating MIME types (bcp:13) and language codes (bcp:47).
Firely Server has a new homepage featuring a refreshed and modern UI.
$realworldtesting can now be executed using a POST request.
It is now possible to disable the create-on-update feature with a new setting in the FhirCapabilities section of the app settings. See FHIR Capabilities for more information.
With this release Update with no changes (No-Op) is enabled by default. For more information about the plugin see Update with no changes.
The NoOp plugin now also works in combination with transaction bundles.
Added support for reading messages from a Kafka topic when using Firely Server PubSub.
We have updated the validator api that is used by Firely Server for improved validation.
Added support for JWT-based authentication against remote terminology services. See Options for more information.
Expose port option in PubSub for RabbitMQ. See Configuration for more information.
Performance counters are now exported via OpenTelemetry when ingesting data via Firely Server Ingest.
Enable use of AuditEvent output parameters (e.g. IP address) for regular logging.

Attention

With the introduction of the new validator it is no longer allowed to use id fields containing underscores (_) in the resource id.

Programming API changes and plugins

Upgraded the Firely .NET SDK to v5.11.4, see its release notes.
Upgraded to v2.0 of the firely-validator-api for validation and removed the legacy validator previous used. This applies to all validation within Firely Server.
ISearchRepository programming API has been changed to prevent unintended unauthorized access. It is required to explicitly set SearchOptions.Authorization when calling search, or use one of the extension methods for ISearchRepository, e.g.: GetByKeyWithFullAccess or SearchCurrentWithFullAccess. SearchOptions authorization can be configured using one of the extension methods: WithAuthorization, WithFullAccess.
ISearchRepository extension methods that were not accepting SearchOptions as a parameter: GetByKey and SearchCurrent - are replaced with GetByKeyWithFullAccess and SearchCurrentWithFullAccess respectively.
SearchOptions is now an immutable record type, which might be a breaking change for some plugin code.
Extended the base class RelationalQueryFactory with support for the ResourceTypesNotValue (see IFilterValue implementations) and methods to express a predicate that is AlwaysFalse() or AlwaysTrue().
The VonkConfigurationAttribute no longer supports the deprecated isLicensedAs property.
The deprecated VonkConstants.MediaType values XmlR3, JsonR3 and TurtleR3 have been removed. Use FhirXml, FhirJson and FhirTurtle instead.
The deprecated method Check.HasValue() has been removed. Use Check.NotNull() instead.
Added documentation for ICapabilityStatementBuilder and related methods, see Capability Statement Management.
Starting from this release the Vonk.Smart and Vonk.Plugin.SoFv2 plugins are no longer supported and have been removed. They are replaced by the Vonk.Plugin.Smart plugin. For more information see SMART on FHIR Configuration. It is necessary to adjust the pipeline options accordingly.
Removed plugin Vonk.Plugins.TerminologyIntegration. Vonk.Pluigins.Terminology should be used instead.
Removed ISpecificationZipLocator from the public API.

Adjustments and Fixes

“This is an open FHIR endpoint for testing and educational purposes only. Uploading real personal data is strictly prohibited.” will no longer be shown on the homepage when running in production mode.
Improved transaction handling for MongoDB to avoid duplicate key exceptions during the ingestion of resources.
SearchParameters of type Reference without a target are no longer logged as errors; they are now logged as warnings.
Improved handling of invalid resources within batch bundles. Firely Server now returns HTTP 200 - OK with individual OperationOutcomes when resources in the bundle are invalid.
Improved handling of large Bulk exports for MongoDB.
Fixed pre-validation when a pipe character (|) and a version are used within a canonical in meta.profile.
Improved handling of Patch exceptions.
Fixed FormatException when using $versions with an invalid MIME type.
Limited recursive Group-level Bulk exports to skip other Group resources that are transitively included.
Authorization endpoints listed in AdditionalIssuersInToken were previously accepted as the only valid issuers when the setting was used. Now, the authority is also accepted as a valid issuer of tokens.
Fixed indexing of elements of type url for URI search parameters.
Improved debug logging for the reindex operation to allow tracking the progress of long-running operations.
Administration APIs reset, reindex/all, reindex/searchparameters, preload and importResources are now $reset, $reindex-all, $reindex, $preload and $import-resources to conform with the naming rules for custom operations.
SMART on FHIR v2 scopes can include search arguments. Upon writing resources (create, update, delete) Firely Server used to only evaluate those for patient/ scopes. Now, they are also evaluated for user/ and system/ scopes.

Configuration

Attention

Default behavior of Firely Server has been tweaked by changing configuration values. Make sure to reflect the desired behaviour by adjusting appsettings.instance.json or environment variables.

The use of other compartments then Patient in SMART on FHIR authorization is not well defined and potentially unsafe. So we redacted the Filters settings in SmartAuthorizationOptions. You can now only specify a filter on the Patient compartment. For more information see SMART on FHIR Configuration. If you configured just a Patient filter in the old format, Firely Server will interpret it in the new format and log a warning that you should update your settings. If you configured a filter on a different compartment, Firely Server will log an error and halt.
Evaluation of Subscriptions is now turned off by default. To enable - adjust SubscriptionEvaluatorOptions accordingly.
BundleOptions.DefaultTotal from now on has a default value of none for performance reasons. For available options see Search size.
TaskFileManagement.StoragePath was already marked as obsolete, and is now also no longer forward compatible. Use the TaskFileManagement.StorageService settings to provide the storage path, see Bulk Data Export for details.
SupportedInteractionOptions type has now been replaced by Operations<T> to accommodate for the requirements of a configuration revamp.
The configuration structure for operations has been completely revamped:
- SupportedInteractionOptions has been replaced by a new top-level Operations configuration section
- Administration.Security.OperationsToBeSecured has been replaced by per-operation NetworkProtected property
- SmartAuthorizationOptions.Protected has been replaced by per-operation RequireAuthorization property
- Each operation now has granular control over authorization, network protection, tenant requirements, etc.
- See configure_operations for detailed information about the new configuration structure and migration guide

Note

If MultiTenancy is enabled, the history and vread operations are blocked for all resources. This is to prevent the possibility of cross-tenant access to resources. The history and vread operations are not supported in a multi-tenant environment.