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.3.1, August 11th, 2025

Fixes

  1. We updated dependencies of the Elasticsearch sink to fix a security vulnerability in a dependency of the Elastic.Serilog.Sinks package. The updated version is now 8.18.2. See the release notes for more information.

  2. We fixed a bug where FSI would take a long time to start up when the MongoDb target database would contain a large number of resources. This was caused by FSI trying to perform a count on the target database, which would take a long time when there were many resources.

Release 6.3.0, July 22th, 2025

Features

  1. We introduced the AdvisorRules setting for the validator for CMS and Scale licenses. The implementation of the Advisor Rules system allows users to customize validation behaviour on a more granular level by setting filters with which the outcome of validation or the validation itself can be modified. Note that this feature is still in beta. For meore information see Filter validation outcome based on advisor rules.

  2. The validator will now create extensions on validation errors pointing to the profile that caused the error in the http://hl7.org/fhir/StructureDefinition/operationoutcome-issue-source extension. These issues will also be annotated with line numbers in the http://hl7.org/fhir/StructureDefinition/operationoutcome-issue-col and http://hl7.org/fhir/StructureDefinition/operationoutcome-issue-line extension.

Release 6.2.0, July 15th, 2025

Improvements

  1. Updated Serilog ApplicationInsights sink configuration to use Connection String instead of the deprecated Instrumentation Key. Azure no longer supports Instrumentation Keys, so one should use connectionString in the ApplicationInsights sink configuration. The connection string can also be configured via ApplicationInsights:ConnectionString in appsettings.json. See Application Insights for more information.

  2. Updated search anonymization to work across multiple Firely Server instances. This also changed the configuration, see: Search Anonymization on how to configure the search anonymization.

  3. It is now possible for Firely Server to pick up appsettings.json files during startup by specifying the file location in the environment variable VONK_PATH_TO_SETTINGS. See Providing settings in a different folder. Before, the configuration was only loaded from appsettings.instance.json.

  4. We improved the behavior of license checks upon startup so that users will no longer see warnings for unlicensed plugins that are not enabled in the pipeline.

  5. We made some improvements to Firely Server Ingest (FSI):

    • We have improved the efficiency of FSI with regard to memory usage/CPU when generating the final usage statistics after a run. This could lead previously to excessive memory consumption and crashes.

    • FSI will now show a warning if it is unable to connect to a source database.

Fixes

  1. Requests with a double slash (//) would lead to an uncaught exception. This will now lead to a 501 Not Implemented response in case the double slash is used within the URL and to a 404 Not Found response in case the double slash is at the end of the URL.

  2. We made some fixes to the Vonk.Facade.Starter kit to help developers on their way with building a facade.

    • It is now possible to create Observation resources again.

    • _total=none is now handled properly. Before this would lead to an error when doing a search.

Features

  1. It is now possible to validate QuestionnaireResponse resources against their original Questionnaire resource. See Advanced Validation for more information.

  2. Message brokers can now be used as a target for Firely Server Ingest. FSI will publish messages to the message broker upon ingesting resources, which can then be consumed by Firely Server. Currently, only Azure Service Bus and RabbitMQ can be configured as message brokers for FSI. The use of a MongoDb source is not supported if the target is set to a message broker, only ingestion from files/folders is supported. See Target (for PubSub) for more information.

  3. We upgraded the .Net SDK to v5.12.0. See the release notes for more information.

Release 6.1.0, May 23rd, 2025

Security

  1. AccessPolicy resources can now only be accessed or modified with system-level scopes (e.g., system/AccessPolicy.*). Patient-level scopes (patient/AccessPolicy.*) and user-level scopes (user/AccessPolicy.*) are not allowed and will be rejected with a 403 Forbidden response.

  2. TrustedProxyIPNetworks now has an additional setting AllowAnyNetworkOrigins to allow any network origins to be trusted. Before, this configuration was only allowed if ASPNETCORE_ENVIRONMENT was set to Development. Systems that used this environment variable to bypass the ip-range restrictions should switch to using this setting instead. This setting is disabled by default and should only be enabled if you are sure that your network is secure.

  3. We added a check to the SMART on FHIR settings to ensure that Authority is always configured.

  4. We added the ClockSkew setting to the SmartAuthorizationOptions. This setting is used to adjust the expiration time and validity of JWT tokens. Before, you could only adjust the expiration time of a JWT token in FA, and Firely server would add an additional window of 5 minutes to this expiration time where the token would still be valid. This window can now be adjusted with this setting. See SMART on FHIR Configuration for more information.

Improvements and Fixes

  1. We improved the behavior of AuditEvent generation in combination with $member-match. The AuditEvent will now capture the Patient ID and Identifier of the member after a successful match.

  2. We improved the performance of snapshot generation queries for Bulk Data Export against a SQL back-end.

  3. We fixed a bug for the Document Handling operation. Before, references of the posted document bundle could not always be resolved.

  4. We improved error messaging of Firely Server for SMART on FHIR reference tokens. Operation Outcomes indicating errors with regard to the token would only mention JWT tokens when a reference token was used. As this was misleading, we adjusted the error message to dynamically show the type of token that was used.

  5. We fixed a bug in the handling of the above modifier in search queries. Firely Server does not support the above modifier and would show a large stack trace when this modifier was used in queries. Error handling for the use of this modifier is now improved.

Features

  1. We added support for the use of the Claim Check pattern in PubSub. This features allows you to outsource the payload of a message to an Azure Blob Storage Account that can be referenced in the message, leading to smaller messages and improved performance. See Claim Check Pattern for more information.

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

  1. 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.

  2. The $lastN operation can now be used with in combination with permissions defined in an AccessPolicy resource.

  3. 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

  1. Raised the minimum supported version of MongoDB to 6.0 to enable sharding.

  2. 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.

  3. 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).

  4. 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

  1. 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.

  2. Traces and ASP .NET metrics based on OpenTelemetry can now be exported to OTLP-enabled backends. See OpenTelemetry for more information.

  3. memberOf() expressions are now supported in FHIRPath constraints when validating resources.

  4. Added support for validating MIME types (bcp:13) and language codes (bcp:47).

  5. Firely Server has a new homepage featuring a refreshed and modern UI.

  6. $realworldtesting can now be executed using a POST request.

  7. 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.

  8. With this release Update with no changes (No-Op) is enabled by default. For more information about the plugin see Update with no changes.

  9. The NoOp plugin now also works in combination with transaction bundles.

  10. Added support for reading messages from a Kafka topic when using Firely Server PubSub.

  11. We have updated the validator api that is used by Firely Server for improved validation.

  12. Added support for JWT-based authentication against remote terminology services. See Options for more information.

  13. Expose port option in PubSub for RabbitMQ. See Configuration for more information.

  14. Performance counters are now exported via OpenTelemetry when ingesting data via Firely Server Ingest.

  15. 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

  1. Upgraded the Firely .NET SDK to v5.11.4, see its release notes.

  2. 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.

  3. 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.

  4. ISearchRepository extension methods that were not accepting SearchOptions as a parameter: GetByKey and SearchCurrent - are replaced with GetByKeyWithFullAccess and SearchCurrentWithFullAccess respectively.

  5. SearchOptions is now an immutable record type, which might be a breaking change for some plugin code.

  6. Extended the base class RelationalQueryFactory with support for the ResourceTypesNotValue (see IFilterValue implementations) and methods to express a predicate that is AlwaysFalse() or AlwaysTrue().

  7. The VonkConfigurationAttribute no longer supports the deprecated isLicensedAs property.

  8. The deprecated VonkConstants.MediaType values XmlR3, JsonR3 and TurtleR3 have been removed. Use FhirXml, FhirJson and FhirTurtle instead.

  9. The deprecated method Check.HasValue() has been removed. Use Check.NotNull() instead.

  10. Added documentation for ICapabilityStatementBuilder and related methods, see Capability Statement Management.

  11. 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.

  12. Removed plugin Vonk.Plugins.TerminologyIntegration. Vonk.Pluigins.Terminology should be used instead.

  13. Removed ISpecificationZipLocator from the public API.

Adjustments and Fixes

  1. “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.

  2. Improved transaction handling for MongoDB to avoid duplicate key exceptions during the ingestion of resources.

  3. SearchParameters of type Reference without a target are no longer logged as errors; they are now logged as warnings.

  4. 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.

  5. Improved handling of large Bulk exports for MongoDB.

  6. Fixed pre-validation when a pipe character (|) and a version are used within a canonical in meta.profile.

  7. Improved handling of Patch exceptions.

  8. Fixed FormatException when using $versions with an invalid MIME type.

  9. Limited recursive Group-level Bulk exports to skip other Group resources that are transitively included.

  10. 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.

  11. Fixed indexing of elements of type url for URI search parameters.

  12. Improved debug logging for the reindex operation to allow tracking the progress of long-running operations.

  13. 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.

  14. 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.

  1. 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.

  2. Evaluation of Subscriptions is now turned off by default. To enable - adjust SubscriptionEvaluatorOptions accordingly.

  3. BundleOptions.DefaultTotal from now on has a default value of none for performance reasons. For available options see Search size.

  4. 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.

  5. SupportedInteractionOptions type has now been replaced by Operations<T> to accommodate for the requirements of a configuration revamp.

  6. 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.