Old Firely Server release notes (v4.x)

Release 4.12.0, January 23nd, 2024

Security

  1. Updated the version of Microsoft.Data.SqlClient from 3.0.1 to 3.1.5 to include the vulnerability patch. See CVE-2024-0056 for more details.

Release 4.11.0, October 17th, 2023

Security

  1. Updated the version of the base docker image from Alpine 3.14 to Alpine 3.18.

  2. Introduced a setting SendServerHeader in the Hosting section to suppress the network service banner. By default, it is set to false, so the Kestrel Server header will be removed in the response of a request.

    Note

    The setting SendServerHeader is applied only for Kestrel. If Firely Server is hosted differently, in IIS for example, and you want to remove the Server header, you need to handle it by yourself.

Release 4.10.2, June 29th, 2023

Attention

This is a security related release which addresses a vulnerability in Firely Server which may lead to unauthorized access using the $everything operation. This update is highly recommended for all customers.

Security

  1. Fixed an issue where the $everything operation did not respect the patient launch parameter in the SMART on FHIR access token. This means that the user could have requested information belonging to a different patient than the one mentioned in the access token. This issue only happened when an access token used for $everything actually contained a patient launch context such as when allowing a patient to request its own record.

  2. Fixed an issue where $everything and $export operation would potentially return resources beloging to different users or patients when running the these operations on a MongoDB database. In case a Patient shared a common resources with annother Patient, e.g. a Group resource, all data would be returned even if it would be outside of the compartment of the Patient requesting the data.

Release 4.10.1, March 13th, 2023

Attention

This is a security related release which addresses a vulnerability in the C# MongoDB driver that Firely Server uses. This update is highly recommended for all customers that use MongoDB as a database or are planning to do so.

Security

  1. We upgraded our MongoDB drivers to fix a recently discovered security vulnerability. According to CVE-2022-48282 Firely Server is not vulnerable after the update.

Fix

  1. We fixed a bug where the self-link in a response Bundle was incorrect when using the SearchAnonymization feature.

Release 4.10.0, October 6th, 2022

Feature

  1. HealthCheck: We introduced endpoints for healthchecks, both liveness and readiness, see Liveness and readiness - $liveness, $readiness.

  2. Provenance: We added support for the X-Provenance header, see X-Provenance header.

    Note

    If you use this release as a facade implementation, you need to disable the provenance header configuration in the pipeline.

  3. Compartments: The reference searchparameter Binary.securityContext can now be used as a link for the Patient compartment. If SMART on FHIR is enabled and a “patient”-level scope is being used, Binary resources must now point to a Patient resource matching the “patient” claim in the access token. For facade and plugin implementations this change means that the ICompartment information is now available for requests on the Binary resource type.

  4. Audit on search: We enhanced audit logging by exposing the literal references of the current page of the results from a search request. For file logging, this information can be included by adding SearchResultSummary to the output template. In AuditEvent resources, each search result (reference) is included as an entity node, in addition to the entity node for the bundle with the query parameters.

  5. Search: We added support of :of-type search modifier for search parameters targeting Identifier elements (e.g. Patient.identifier). See the FHIR spec article on search for more information.

    Note

    After the update, all new resources containing Identifier elements will be automatically indexed and become searchable with the :of-type modifier. If you want to make discoverable the data you already have, you would need to re-index your data for some of the search parameters you want to use with the :of-type modifier.

  6. Search: Added support for the Prefer header when searching, with allowed values handling=strict or handling=lenient, as per the specification.

  7. Search: Added support for wildcards on _include=* and `_revinclude=*`, so you can (rev)include all linked resource at once, as specified with search.

  8. Search: Canonical references can now be searched using the :below modifier, that will match a prefix of the version, as specified for References and versions

  9. US Core: Added support for the $docref operation. Firely Server can retrieve all existing DocumentReferences for a Patient, but cannot yet generate a document. This operation is defined as part of the US Core implementation guide.

  10. Mimetype: If a request did not specify a mimetype in the Accept header, Firely Server would default to application/fhir+json. If you prefer XML, this default can now be set in the Response options.

  11. Preloading resources is updated and now works for all FHIR versions. Please note that this feature is still meant for limited amounts of (mainly example) data. For loading large amounts of data we recommend to use Bulk Import via Firely Server Ingest.

Database

  1. We introduced new optimizations for the MongoDB data schema and queries. These optimizations will improve search performance for elements of type dateTime and decimal. Please read below notes for the upgrade process.

    Attention

    The upgrade procedure for Firely Server running on MongoDb requires a mandatory migration. If your collection contains a lot of resources, this may take a very long time. Therefore, the MongoDb upgrade script has to be executed manually. The script can be found in mongodbFS_SchemaUpgrade_Data_v22_v23.js

    Here are some guidelines:

    • We tested it on a MongoDb collection with a size of 500GB. The upgrade script took around 24 hours to complete on a fairly powerful machine.

    • As always, make sure you have a backup of your database that has been tried and tested before you begin the upgrade.

    • Please make sure that Firely Server is shutdown before you execute the script.

    • If you encounter problems running the script, or need any assistance, please contact us.

    The update script will update the data that is stored in the database. Although Firely Server can be started as soon as the migration is finished, it will have decreased performance during the first day of operation. This is due to a change in indexes which requires them to be rebuilt in the background.

  2. We introduced user defined table types in SQL Server for an optimization in Firely Server Ingest 1.4.0. The update is in migration script FS_SchemaUpgrade_Data_v24_v25.sql and will be applied automatically when AutoUpdateDatabase=true in the settings.

Fix

  1. Administration: The order of loading knowledge and conformance resources has been fixed. We made sure that the definitions stored in the administration database take precedence over the definitions from the specification.zip file. Any custom implementations of IModelContributor are loaded after the database and before the ZIP file.

  2. Search: An erratum to the specification of R4 has been made, changing the type of search parameter Resource-profile from uri to reference (with target StructureDefinition). This was an ommision in R4 and has been fixed in R5. The change allows searching for _profile with the :above and :below modifier. To take advantage of it, the following steps must be taken:

    • Optionally but recommended: before upgrading, remove the current index data for Resource._profile (see re-indexing)

    • Upgrade Firely Server, execute the database migrations and start the server

    • Re-index Resource._profile (see re-indexing)

    Note

    If you have made manual changes to SearchParameter/Resource-profile-Fhir4.0 and want to search with the :above/:below modifier, you must update your definition to be of type reference with target StructureDefinition

  3. Search: Indexing has been fixed for search parameters of type reference that index resource elements of type uri. The following SearchParameters were affected by the bug: Consider re-indexing your database for these search parameters if you use them.

    • FHIR4: ConceptMap-source-uri, ConceptMap-target-uri, PlanDefinition-definition

    • STU3: ImplementationGuide-resource, Provenance-agent

    Note

    Please note that due to a mistake in the official STU3 specification, search parameters ConceptMap-source-uri, ConceptMap-target-uri still do not work as expected. The correct search parameter expressions would be ConceptMap.source.as(uri) and ConceptMap.target.as(uri) while the specification contains ConceptMap.source.as(Uri) and ConceptMap.target.as(Uri) respectively. The issue has been addressed in R4.

  4. SMART: With SMART on FHIR enabled, an update-on-create (creating a new resource with an update / PUT) was always denied. This is now fixed.

  5. Subscription: if the resthook url in a Subscription did not end with a slash (/), it would get shortened to the last slash in the url. This is now fixed, the whole url is used.

Plugin and Facade

  1. Facade: When building predicates in a Facade implementation of ISearchRepository / IRepoQueryFactory, exceptions where only translated to the OperationOutcome, but not logged. Now they are also logged.

  2. API: We will narrow the public programming API in the Vonk.Core package in the next major release. To alert you to that, we deprecated the parts that will be removed from the public API.

    Attention

    Please try to build your plugin or facade against Vonk.Core 4.10.0 to check if you use any of the deprecated parts. If you think some part should not be deprecated, please let us know with a support ticket.

Release 4.9.3, September 15th, 2022

Fix

  1. Starting with Firely Server v4.9.0, a specific search query could fail, with multiple includes on the same parameter, having different type modifier, e.g. Coverage?_include=Coverage:payor:Patient&_include=Coverage:payor:Organization. That is fixed.

Release 4.9.2, August 24th, 2022

Fix

  1. Starting with Firely Server v4.9.0, validation was only performed against the core specification even if the validation level was set to “Full” and resources sent to Firely Server contained a meta.profile claim.

Release 4.9.1, August 1th, 2022

Fix

  1. Fixed an issue with _include and _revinclude in case the (rev-)include link was pointing to an element of type “canonical” and not of type “reference”.

  2. “_total” was added as default parameter in the v4.9.0 release. Therefore it must be handled in a facade implementation. The Vonk.Facade.Relational package now handles the case of “_total=accurate”. All other argument values must still be handled in the ISearchRepository implementation.

  3. Reading the specification.zip file from a read-only disk caused an exception.

  4. Excluding the UrlMappingService from the pipeline configuration and executing a CRUD operation caused an exception.

Feature

  1. The exposed SMART capabilities in the .well-known/smart-configuration can now be configured in the appsettings. See SmartAuthorizationOptions.SmartCapabilities in section SMART Configuration.

Public Endpoint Announcement 8 July 2022

The default FHIR version of the public Firely Server endpoint is now R4.

Release 4.9.0, July 6th, 2022

Security

  1. Upgraded Microsoft.AspNetCore.Authentication.JwtBearer dependency as a mitigation for CVE-2021-34532.

Database

  1. Switched the serialization format for decimal types from string to the native decimal type in MongoDB to improve performance.

  2. For SQL Server database, if you upgrade Firely Server all the way from v4.2.1, it is likely that the resulting index vonk.ref.ref_name_relativereference differ from a clean installation of Firely Server. The upgrade procedure will try to fix the index automatically. If your database is large, this may take too long and the upgrade process will time out. If that happens you need to run the upgrade script manually. The script for the admin database can be found in sqlserver/FS_SchemaUpgrade_Admin_v22_v23.sql and the script for the data database can be found in sqlserver/FS_SchemaUpgrade_Data_v23_v24.sql.

Attention

The upgrade procedure for Firely Server running on MongoDb requires a mandatory migration. If your collection contains a lot of resources, this may take a very long time. Therefore, the MongoDb upgrade script has to be executed manually. The script can be found in mongodbFS_SchemaUpgrade_Data_v21_v22.js

Here are some guidelines:

  • We tested it on a MongoDb collection with a size of 500GB. The upgrade script took around 24 hours to complete on a fairly powerful machine.

  • As always, make sure you have a backup of your database that has been tried and tested before you begin the upgrade.

  • Please make sure that Firely Server is shutdown before you execute the script.

  • If you encounter problems running the script, or need any assistance, please contact us.

Fix

  1. Fixed an issue where a “/” was missing in the fullUrl of a “search” bundle in case an information model mapping with mode “Path” was used.

  2. Fixed an issue where a new resource id was not created when POST was used in a batch or transaction bundle and a resource id was already provided.

  3. An invalid system URI was provided by default in AuditEvent.source.observer.identifier. Now http://vonk.fire.ly/fhir/sid/devices|firely-server is being used to identify Firely Server itself.

  4. Adjusted the implementation of conditional create to match the description in https://jira.hl7.org/browse/FHIR-31965.

  5. Money.currency was not indexed correctly in FHIR R4. Please contact us if you are using the SearchParameters “price-override” on ChargeItem or “totalgross” / “totalnet” on Invoice. A migration for these fields will be provided upon request. Otherwise, please re-index these SearchParameters. See Re-indexing for new or changed SearchParameters for more details.

  6. Fixed an issue where bundles with conformance claims in meta.profile would have been validated against the profile claims even if the validation level was only set to “Core”.

  7. Validating a resource with an element containing only an extension and no value against validation level “Core” will no longer result in an error.

  8. SoF: Providing an invalid token to an unsecured operation does not lead to an HTTP 401 error status code. The invalid token is now being ignored.

  9. SoF: Fixed unauthorized issue when performing PATCH request with patient scope.

Feature

  1. Inferno, the ONC test tool: Firely Server is updated to pass all the tests in the latest ONC test kit (version 2.2.1)! Do you want a demo of this? Contact us.

  2. Transactions, including rollbacks, are now fully supported when running Firely Server on MongoDB. Please note that the SimulateTransaction setting is no longer available. See MongoDB Transactions for more details.

  3. $lastN is now available if Firely Server is running on MongoDB. See Observation - $lastN for more details.

  4. It is now possible to define exclusion criteria in the appsettings to configure which requests against Firely Server should not be audited. In certain cases, this can reduce the number of captured AuditEvent resources. See Auditing for more details.

  5. By default, the AuditEvent logging will now include the query parameters sent to Firely Server. These parameters will also be stored in case a request fails (HTTP 4xx or 5xx).

  6. The log sinks for AuditEvent logging are now configurable in the logsettings. See Audit log file configuration for more details.

  7. Firely Server will throw a startup exception if no default ITerminologyService is registered.

  8. CapabilityStatement.rest.resource.conditionalRead is now set to ‘full-support’ by default.

  9. _total is now included in every self-link of a “search” bundle by default.

  10. Added support for permanently deleting resources from the database. See Permanently delete resources - $erase for more details. You will need an updated license file. Please contact us if you want to use the feature.

  11. Improved the error message in case the JSON serialization format of a FHIR resource does not contain a valid “resourceType” Element.

  12. Improved validation in case a non-conformant URI is given in Quantity.system. It MUST be a valid absolute URI. In all other cases, a warning will be logged and the element will not be indexed.

  13. Improved error message logging in case SQL script fails when the database upgrade is performed automatically by Firely Server.

  14. Improved log message in case Firely Server SQL schema needs to be updated by adding the current schema version and the target schema version.

  15. Improved access control by no longer allowing retrieval of resources outside of the Patient compartment if SMART on FHIR is enabled and patient-level scopes are provided by the client. Additional resources need to be explicitly allowed by the token.

  16. Improved error message in case a condition create/update/delete operation is executed with SMART on FHIR enabled and the client provides a token with limited permissions (e.g. only write-scopes).

Performance

  1. Improved validation performance of large resources. Firely Server will now execute the validation of bundles in a linear amount of time depending on the number of resources in the bundle.

  2. Improved performance for chained searches in case SMART on FHIR is enabled.

Release 4.8.2, May 10th, 2022

Feature

  1. A new setting has been introduced in the “Hosting” settings to configure path base. Please check Firely Server settings page for details.

Fix

  1. US-Core profiles in conformance resources database vonkadmin.db are downgraded from version 4.0.0 to 3.1.1. The upgrade in previous Firely Server was unintentional.

  2. CapabilityStatement is cached now based on the absolute request url. With this fix, CapabilityStatement can be properly cached when a request contains X-Forwarded-* headers.

  3. For MongoDB repository, set allowDiskUse to true when using aggregate command. This fix solves memory restriction error during aggregation stages (See MongoDB document for details).

Release 4.8.1, Mar 5th, 2022

Plugins

  1. Upgraded the .NET SDK to 3.8.2. Please review its release notes for changes.

Feature

  1. A new option to configure settings regarding TLS client certificates has been introduced in the “Hosting” options. This option allows to set the ClientCertificateMode.

  2. Validation of transaction/batch bundles has been enabled by default when posting the resources to the transaction endpoint of Firely Server. Please note that the transaction is executed synchronously. To avoid client timeouts, the default value for the MaxBatchEntries (SizeLimits options) has been reduced to 200.

Release 4.8.0, Mar 21st, 2022

Plugins

  1. Upgraded the .NET SDK to 3.8.0. Please review its release notes for changes.

Database

  1. SQL Server

    1. Reduced database size by compressing the resource JSON.

    Attention

    This change requires a complex SQL migration which can be long if you have many resources. To estimate how long it will take for you, you can try running the migration for a subset of your data. The overall migration time will grow linearly with the number of resources in the database.

    For our test database containing ~185mln FHIR resources, the migration took approximately 1.5 days.

    If you have questions about the migration, please contact us.

    The required migrations for SQL Server will be applied automatically if AutoUpdateDatabase=true in the settings. Otherwise, or if the automatic migrations time out, you can run them manually. The scripts are located in the directory ./sqlserver. You can see the list of applied migrations in table [vonk].[schemainfo]. The upgrade requires the following migrations:

    • Admin database:

      • FS_SchemaUpgrade_Admin_v21_v22

    • Data database:

      • FS_SchemaUpgrade_Data_v21_v22, FS_SchemaUpgrade_Data_v22_v23

Performance

  1. Improved performance for update, _include/_revinclude and conditional create interactions

Feature

  1. You can now control the inclusion of the fhirVersion mimetype parameter in the Content-Type header of the response. See Running different versions on different endpoints. We chose to change the default for FHIR STU3 to not include it as this parameter was introduced with FHIR R4.

Fix

  1. Fixed exception by improving transaction handling when updating and deleting the same resource in parallel.

  2. Use correct restful interaction codes in AuditEvent.subtype when recording a request to Firely Server

  3. AuditEvent.action contained the wrong code when recording a SEARCH interaction

  4. The name of a custom operation is now recorded in an AuditEvent

  5. Fixed searching using the :identifier modifier in case the identifier system is not a valid URL

  6. Searching using a If-None-Exist header was not scoped to an information model, i.e. a request using FHIR R4 also matched STU3 resources

  7. Improved error message if $lastN operation is enabled but the corresponding repository is not included in the pipeline options

  8. Changed CapabilityStatement.software.name to Firely Server

  9. Fixed SQL Server maintenance job timeouts on large SQL Server databases

  10. Improved Bundle reference resolving in some corner cases, which are clarified in the this HL7 Jira issue

Security

  1. According to the best practices of docker, Firely Server container runs now under the user and group firely:firely instead of running under root privileges.

Release 4.7.1, Feb 15th, 2022

Fix

  1. An invalid CapabilityStatement was created by Firely Server in case a custom SearchParameter overwriting a common SearchParameter was loaded, e.g. “_id”. CapabilityStatement.rest.resource.searchParam.definition contains now the canonical of the more specific SearchParameter.

  2. The default CapabilityStatement contained an invalid canonical in the .url element.

  3. Enforce referential integrity for the elements “Composition.patient” and “Composition.encounter” when submitting a document bundle to the base endpoint. The corresponding resources need to be already present on the server (matching based on identifier), otherwise the bundle is rejected.

Release 4.7.0, Feb 1st, 2022

Attention

With version 4.7.0, Firely Server migrated to .NET 6.0. In order to run the binaries, ASP.NET Core Runtime 6.x needs to be installed.

Feature

  1. BulkDataExport is now supported for MongoDB as well. Get started with the Bulk Data Export documentation.

  2. Circular references in transaction bundles are now supported. Bundles of type transaction and batch are permitted to contain resources referencing another resource within the same bundle. This also means that you can now cross reference PUT and POST entries.

  3. An option to configure additional token issuers is now available. This is used in settings where the token issuer deviates from the token audience. This new setting replaces the existing AdditionalEndpointBaseAddresses. The setting needs to be adjusted manually as it will not be migrated automatically. Please check the configuration documentation on how to use it.

  4. Firely Server now supports receiving document bundles on the base endpoint. Firely Server will extract the narrative of document bundles and store this within a DocumentReference resource. Read more about it in the documentation.

  5. Added support for transforming SMART scopes issued by Azure Active Directory documentation.

  6. Firely Server will now recognize the name claim in JSON Web Tokens and also include its content in the logs.

  7. It is now possible to provide the Firely Server license via an environment variable.

Plugins

  1. BulkDataExport interfaces were made publicly available in order to provide these to Firely Server’s facade implementers. The Bulk Data Export page now has a section on BDE for facades.

  2. Upgraded the .NET SDK to 3.7.0. Please review its release notes for changes.

Logging improvements

  1. Error messages including information about authorization validation and authentication requests are now enriched with user information if ShowAuthorizationPII is enabled in the configuration.

  2. Authorization/Authentication logging messages are now enriched with more information when logging level for the namespace Vonk.Smart is set to Debug.

  3. In case SSL is activated, but the .pfx file configured in CertificateFile could not be found, Firely Server will now log this error more explicitly.

Fix

  1. Fixed a bug where newly created SQL connections were not closed properly with the raw SQL configuration.

  2. Fixed a bug that prevented searching on the ContactPoint datatype with a query of type system|value. Although this combination is disallowed by the FHIR specification, Firely Server still allows it. We do not provide a migration for this issue. Please Contact us if this is an issue for you.

  3. Fixed a bug that returned invalid self links without escaped whitespaces in bundles.

  4. Improved support for use of Firely Server with Azure SQL.

Other

  1. Firely Server will no longer support CosmosDb starting with version 4.7.0.

  2. The Docker image name has changed from simplifier/vonk to firely/server. The old image name will be maintained for a few months to allow for a smooth transition. When updating to version 4.7.0, you should start to use the new image name. Versions 4.6.2 and older will stay available (only) on ‘simplifier/vonk’.

Release 4.6.2, Dec 23rd, 2021

Fix

  1. IConformanceCacheR3 and IConformanceCacheR4 are registered again in the ServiceProvider for plugins that still make use of them. Note that these interfaces are obsolete by now, so make sure you don’t use them for any new plugins.

Release 4.6.1, Dec 15th, 2021

Fix

  1. Improved handling of TypeLoadException and ReflectionTypeLoadException when scanning external assemblies for SerializationSupportAttribute attributes.

Release 4.6.0, Nov 18th, 2021

Database

  1. SQL Server (all changes below applicable only when plugin Vonk.Repository.Sql.Raw is enabled)

    1. A new computed column IsDeleted on table [vonk].[entry] is leveraged for more performant SQL queries

    Note

    The performance of the old Vonk.Repository.Sql may be adversely impacted by this change. We encourage you to use the new Vonk.Repository.Sql.Raw implementation.

    1. Improved performance of SQL queries by converting 5 columns from [vonk].[entry] to varchar upon retrieval: InformationModel, Type, ResourceId, Version, Reference

    Note

    These columns should - by definition of the FHIR datatypes - not contain characters outside the varchar range, but please pay attention to this change if your id’s or custom resource type has those characters nonetheless. We may alter the datatype of the columns in a future release.

    1. Improved performance of some SQL queries by avoiding unnecessary SQL query parameter type conversion

    2. Improved performance of some SQL queries by avoiding excessive retrieval of the (large) ResourceJson column

    The required migrations will be applied automatically if AutoUpdateDatabase=true in the settings. Otherwise, or if the automatic migrations time out, you can run them manually. The scripts are located in the directory ./sqlserver. You can see the list of applied migrations in table [vonk].[schemainfo]. The upgrade requires the following migrations:

    • Admin database:

      • FS_SchemaUpgrade_Admin_v19_v20

    • Data database:

      • FS_SchemaUpgrade_Data_v20_v21

  2. MongoDB

    1. Improved performance of searches within a compartment

    2. Added an index ix_sysinfo to quickly retrieve the VonkVersion document.

Features

  1. Added support for SMART on FHIR v2

Note

Since most users currently use SMART on FHIR v1, the plugin for v2 is by default disabled in the PipelineOptions. You can switch v1 out and v2 in when you want to test the use of v2.

Logging improvements

  1. The password and the username are stripped out from a connection string when it gets logged (SQL Server / Sqlite, Verbose log level)

  2. SQL param values are not logged by default. This can be enabled by using a new config setting. See SQL query parameter logging (SQL Server / Sqlite, Verbose log level)

  3. Username and UserId are included in log and audit entries (when using SoF or another authentication plugin)

  4. SQL query duration now gets logged (changed for Vonk.Repository.Sql.Raw.KSearchConfiguration plugin; was always available for other repository plugins, Verbose log level)

  5. Fixed category names for some log entries to include the fully qualified type of their source. For example, category MetadataConfiguration was changed to Vonk.Core.Metadata.MetadataConfiguration, and category BulkDataExportConfiguration was changed to Vonk.Plugin.BulkDataExport.BulkDataExportConfiguration, etc.

Fix

  1. Fixed a bug when validation was not performed on PATCH requests even when the validation level was set to Full

  2. Fixed a bug when escaping of the pipe (‘|’) character was not working as expected for token search parameters

  3. Improved error handling when FS tries to load a non-.NET DLL from the plugins directory

  4. Fixed a bug (introduced in 4.5.1) when a compartment matches more than 1 Patient

  5. Fix: $validate checks whether a system parameter is provided

  6. Fix: Vonk.Repository.Sql.Raw: searching on quantities with values having a high precision failed

Other

  1. Firely SDK upgraded from v3.0.0 to v3.6.0. See the SDK release notes here

Note

This will make Firely Server import a new version of specification.zip into the Administration endpoint for each FHIR version. If you share the Administration database among instances, allow 1 instance to finish this process before starting the other instances.

Release 4.5.1

Attention

The upgrade procedure for Firely Server running on MongoDb will execute an upgrade script that adds a new field to store precalculated compartment links. If your collection contains a lot of resources, this may take a very long time. Therefore, the MongoDb upgrade script has to be executed manually. The script can be found in mongodbFS_SchemaUpgrade_Data_v17_v18.js

Here are some guidelines:

  • We tested it on a MongoDb collection with about 400k documents in total. The upgrade script took around 3.5 minutes to complete on a fairly powerful laptop.

  • As always, make sure you have a backup of your database that has been tried and tested before you begin the upgrade.

  • Please make sure that Firely Server is shutdown before you execute the script.

  • If you encounter problems running the script, or need any assistance, please Contact us.

Database

  1. MongoDB

    1. The migration script ‘FS_SchemaUpgrade_Data_v17_v18.js’ has been fixed. All data present in the database before the migration is now again accessible after the migration.

  2. SQL Server

    1. Improved the query performance when using _include by using “WITH FORCESEEK”.

    2. Improved performance by avoiding scanning indexes when searching on the UriHash column

Fix

  1. Firely Server will now by default include a user-agent header when retrieving the SMART Discovery document

Release 4.5.0

Database

Attention

The release version of the MongoDB migration contains an error causing compartment searches to return no search results for all migrated resources. Only newly added resources after the migration will be returned successfully. In Release 4.5.1 we have fixed this issue, so please use that version instead.

  1. MongoDB

    1. To improve the performance of compartment searches, Firely Server now precalculates the compartment links to which a resource belongs on insert in the database. An external migration script ‘FS_SchemaUpgrade_Data_v17_v18.js’ is provided in the distribution. It needs to be applied manually using MongoDB Shell.

Security

  1. A VonkConfigurationException, which was thrown if a SQL database migration could not be performed, included the SQL connection string in plain text in the log. Please check you log files if they include any sensitive information such as the database password, which might have been part of the connection string.

Fix

  1. It is now possible to configure pre- and post-handlers for a custom operations using VonkInteraction.all_custom regardless of the interaction level of the operation handler and the interaction level on which the operation is configured in the appsettings.

  2. $lastN could not handle chained arguments on the subject/patient reference

  3. $lastN reported an invalid error message if the reference to a subject/patient was provided as an urn:uuid reference

  4. $lastN search result bundles were missing self-links when no results were found

  5. Disabling Vonk.Fhir.R4 in the pipeline resulted in an internal exception thrown by the ConformanceCache

Feature

  1. $lastN can be combined with _elements and _include parameters

  2. $lastN can group the results by the component-code or combo-code search parameter

Documentation

  1. Added an explanation to the documentation why the use of _total=none influences the performance of a search query.

Plugins

  1. The FHIR Mapper is no longer distributed together with Firely Server. Please contact fhir@healex.systems for any questions regarding the FHIR Mapper.

  2. The packages Vonk.Fhir.R(3|4) depended on an unpublished NuGET package Vonk.Administration.Api.

  3. All classes in the namespace ‘Vonk.Facade.Relational’ are now published on GitHub.

Release 4.5.0-beta

Fix

  1. Security: Added a warning to the documentation that using compartments other than ‘Patient’ to restrict access based on patient-level SMART on FHIR scopes may result in undesired behavior. See Tokens and Compartments for more information.

  2. The RequestCountService caused an exception on startup if the RequestInfoFile could not be accessed, e.g. due to limited filesystem permissions. The RequestCountService has been removed completely. Any remaining .vonk-request-info.json files can be deleted manually.

  3. The logsettings for SQL server included an outdated configuration.

  4. The logsettings for MongoDB included an outdated configuration.

Feature

  1. Improved error messages if an internal exception occurred due to failing filesystem access.

  2. The $lastN operation is now available when using SQL Server as the backend for Firely Server. See Observation - $lastN for more information.

Plugin and Facade

  1. Added async support for the ISnapshotGenerator interface and its implementations.

Release 4.4.0

Database

  1. MongoDB

    1. To improve the performance of deletes, the definition of the index ix_container_id is redefined. Firely Server 4.4.0 will automatically change the definition.

  2. SQL Server

    1. Improved query behind _include to leverage an index. No changes to the database schema involved. This only affects the new implementation (available since 4.3.0).

Fix

  1. Improved automatic upgrading of terminology settings from pre-4.1.0 instances.

  2. Added CapabilityStatement.status for R4

  3. The default SmartAuthorizationOptions in appsettings.default.json only have the Filter for ‘Patient’ enabled. The rest is now commented out as those are generally not used.

Plugin and Facade

  1. The interfaces PrioritizedResourceResolver(R3|R4|R5) and their implementations are no longer available. It is advised to construct your own StructureDefinitionSummaryProvider incl. a MultiResolver combining your own resource resolver and the IConformanceCache provided by Firely Server.

  2. The interface IConformanceCacheInvalidation has been moved from Vonk.Core.Import to Vonk.Core.Conformance

  3. The classes SpecificationZipResolver(R3|R4|R5) are no longer available. Please use the IPrioritizedResourceResolvers instead.

  4. Starting from this version, a Facade should not have an order greater than or equal to 211. The reason for this is that upon configuring the administration database, Firely Server checks whether an ISearchRepository is registered. The earliest of these configurations is at order 211.

Release 4.3.0

Database

  1. SQL Server

    1. To improve the performance of searching we have rewritten a large part of our SQL Server implementation. To be able to use the new implementation go to section PipelineOptions in appsettings.default.json (or appsettings.instance.json if you have overridden the default pipeline options) and add "Vonk.Repository.Sql.Raw.KSearchConfiguration". See Using SQL server for more details.

    2. We have identified two indexes that needed a fix to increase query performance for certain searches. The upgrade procedure will try to fix these indexes automatically. If your database is large, this may take too long and the upgrade process will time out. If that happens you need to run the upgrade script manually, The script can be found in sqlserver/FS_SchemaUpgrade_Data_v19_v20.sql. If you use SQL Server as your Administration database, Firely Server will try to update it automatically as well. If you prefer a manual update, you can run the following script: sqlserver/FS_SchemaUpgrade_Admin_v18_v19.sql.

Feature

  1. Firely Server now allows you to execute a ValueSet expansion of large ValueSets (> 500 included concepts). Previously, Firely Server would log an error outlining that the expansion was not possible. The appsettings now contain a setting in the Terminology section allowing to select the MaxExpansionSize. See Options for more details.

Fix

  1. Fixed a NullPointerException which occurred when indexing UCUM quantities that contained more than one annotation (e.g. “{reads}/{base}”).

  2. Fixed a bug where it was possible to accidentally delete a resource with a different information model then the request. Firely Server will now check the information model of the request against the information model of the resource for conditional delete and delete requests.

  3. $subsumes returned HTTP 501 - Not implemented for a POST request (instance-level) even if the operation was enabled in the appsettings.

  4. The _type filter on $everything and Bulk data export didn’t allow for resources that are not within the Patient compartment. The operations would return an empty result set.

  5. Added a clarification to the documentation that $everything and Bulk data export do not export Device resources by default. Even though the resource contains a reference to Patient, the corresponding compartment definition for Patient does not include Device as a linked resource. It is possible to export Device resources by adding the resource type to “AdditionalResources” settings of the operations.

Release 4.2.1 hotfix

Database

Note

We found an issue in version 4.2.0, which affects the query performance for Firely Server running on a SQL Server database. If your are running FS v4.2.0 on SQL Server you should upgrade to v4.2.1 or if that is not possible, Contact us.

Attention

The upgrade procedure will execute a SQL script try to validate the foreign key constraints. If your database is large, this may take too long and the upgrade process will time out. If that happens you need to run the upgrade script manually, The script can be found in data/20210720085032_EnableCheckConstraintForForeignKey.sql.

Here are some guidelines:

  • We tested it on a database with about 15k Patient records, and 14 million resources in total. The upgrade script took about 20 seconds to complete on a fairly powerful laptop.

  • As always, make sure you have a backup of your database that has been tried and tested before you begin the upgrade.

  • If you expect the upgrade to time out, you can choose to run the SQL script manually beforehand. Please make sure that Firely Server is shutdown before you execute the script.

Fix

  1. Fixed a bug where some of the Foreign Keys in SQL Server had become untrusted. This bug has an impact on the query performance since the the SQL Server query optimizer will not consider FKs when they are not trusted. This has been fixed, all Foreign Keys have been validated and are trusted again.

Release 4.2.0

Database

Attention

For SQL Server users: this version of Firely Server running on SQL Server has a bug where some of the Foreign Keys became untrusted. This has an impact on the query performance. Please upgrade to version 4.2.1 or if that is not possible, Contact us. Please note that users running Firely Server running either MongoDb, CosmoDb, or SQLite are not affected by this issue.

Attention

For SQL Server we changed the datatype of the primary keys. The related upgrade script (data/20210519072216_ChangePrimaryKeyTypeFromIntToBigint.sql) can take a lot of time if you have many resources loaded in your database. Therefore some guidelines:

  • We tested it on a database with about 15k Patient records, and 14 mln resources in total. Migrating that took about 50 minutes on a fairly powerful laptop.

  • Absolutely make sure you create a backup of your database first.

  • If you haven’t done so already, first upgrade to version 4.1.x.

  • If you already expect the migration might time out, you can run it manually upfront. Shut down Firely Server, so no other users are using the database, and then run the script from SQL Server Management Studio (or a similar tool).

  • Running the second script (20210520102224_ChangePrimaryKeyTypeFromIntToBigintBDE.sql) is optional - that should also succeed when applied by the auto-migration.

Feature

  1. Terminology operation $lookup is now also connected to remote terminology services, if enabled. See Terminology services.

  2. We provided a script to ‘purge’ data from a SQL Server database. See data/20210512_Purge.sql. You can filter on the resource type only. Use with care and after a backup. If you need more elaborate support for hard deletes, please Contact us.

Fix

  1. Firely Server could run out of primary keys on the index tables in SQL Server. Fixed by upgrading to bigint, see warning above.

  2. Nicer handling of SQL Server migration scripts that time out on startup. It will now kindly ask you to run the related script manually if needed (usually depends on the size of your database).

  3. The Patient-everything ($everything) operation was not mentioned in the CapabilityStatement.

  4. License expired one day too early.

  5. Dependencies have been upgraded to the latest versions compatible with .NET Core 3.1.

  6. PATCH did not allow adding to a repeating element.

  7. If your license does not allow usage of SMART on FHIR, authorization was disabled, emitting a warning in the log. Possibly causing unauthorized access without the administrator noticing it. This specific case will now block the startup of Firely Server.

Release 4.1.3 hotfix

Fix

  1. Fixed a bug where a number of concurrent $transform requests on a freshly started Firely Server could lead to Internal Server Error responses.

  2. Upgraded the Mapping plugin.

Release 4.1.2 hotfix

Fix

  1. Fixed a bug when trying to delete multiple resources at once (bulk delete, see Configuration for configuration options). The operation would take a while and eventually return a 204 No Content without actually deleting any resources. This is fixed, the bulk delete operation now deletes the resources.

Release 4.1.1 hotfix

Feature

  1. SMART configuration: Some identity providers use multiple endpoints with different base addresses for its authorization operations. Added an extra configuration option AdditionalEndpointBaseAddresses to define additional base endpoints addresses next to the main authority endpoint to accommodate this. See SMART on FHIR Configuration for further details.

Fix

  1. Fixed an error in SQL script data/20210226200007_UpdateIndexesTokenAndDatetime_Up.sql that is used when manually updating the database to v4.1.0. We also made the script more robust by checking if the current version the database is suitable for the manual upgrade.

Release 4.1.0

Attention

We have found an issue with SMART on FHIR and searching with _(rev)include. And fixed it right away, see Fix nr 1 below. Your Firely Server might be affected if:

  • you enabled SMART on FHIR

  • and used patient/read.* scopes together with a patient compartment

What happens? Patient A searches Firely Server with a patient launch scope that limits him to his own compartment. If any of the resources in his compartment links to another patient (let’s say for Observation X, the performer is Patient B), Patient A could get to Patient B with <base>/Observation?_include=Observation.performer. If you host Group or List resources on your server, a _revinclude on those might give access to other Patient resources within the same Group or List.

If you think you might be affected you can:

  • upgrade to version 4.1.0

  • or if that is not possible, Contact us.

Database

  1. SQL Server

    1. A new index table was added. The upgrade procedure will try to fill this table based on existing data. If your database is large, this may take too long and time out. Then you need to run the upgrade script found in data/20210303100326_AddCompartmentComponentTable.sql manually.

    2. A new SQL Server index was added to improve query times when searching with date parameters. The upgrade procedure will try to build this index. If your database is large, this may take too long and time out. Then you need to run the upgrade script found in data/20210226200007_UpdateIndexesTokenAndDatetime_Up.sql manually.

    3. In both cases you may also run the script manually beforehand.

    4. As always: make sure you have a backup of your database that is tested for restore as well.

DevOps

Attention

Because of a change in the devops pipeline there is no longer a Firely.Server.exe (formerly Vonk.Server.exe) in the distribution zip file. You can run the server as always with dotnet ./Firely.Server.dll

Features

  1. Inferno, The ONC test tool: Firely Server now passes all the tests in this suite! With version 4.1.0 we specifically added features to pass the ‘Multi-patient API’ tests. Do you want a demo of this? Contact us!.

  2. Terminology support has been revamped. Previously you needed to choose between using the terminology services internal to Firely Server or external terminology services like from OntoServer or Loinc. With this version you can use both, and based on the codesystem or valueset involved the preferred terminology service is selected and queried.

    1. This works for terminology operations like $validate-code and $lookup

    2. It also works for validation, both explicitly with $validate and implicitly, when validating resources sent to Firely Server.

    3. The CodeSystem, ValueSet and ConceptMap resources involved are conformance resources and therefore always retrieved from the Administration database.

    4. Responses may differ on details from previous versions of Firely Server, but still conform to the specification.

    5. See Terminology services for further details.

  3. $everything: We now support the Patient-level Export - $everything operation for single Patients. (For multiple patients, there is the Bulk Data Export feature.)

  4. Performance of $everything, Bulk Data Export and authorization on compartments improved. We added a special index to the database that keeps track which resource belongs to which compartment. First in SQL Server, MongoDB has less need for it.

  5. SMART on FHIR: Support for token revocation. Reference tokens can be revoked, and Firely Server can check for the revocation.

Fixes

  1. SMART on FHIR: We have found ourselves that the authorization restrictions were bypassed when using _include or _revinclude in a FHIR Search. We solved this security issue immediately.

  2. Firely Server transparently translates absolute urls to relative urls (for internal storage) and back. There was a performance gain to be made in this part, which we did. This is mostly notable on large transaction or batch bundles.

  3. Batch bundles are not allowed to have links between the resources in the entries. Firely Server will now reject batch bundles that have these links. If you need links, use a transaction bundle instead.

Plugin and Facade

  1. We upgraded the Firely .NET SDK to version 3.0.0. This SDK version is almost fully compatible with 2.9, but it brings significant simplifications to its use because the Parameters and OperationOutcome resource POCOs are no longer FHIR-version specific.

    Note

    Every new version of the SDK brings new versions of the specification.zip files. So upon upgrade these new files will be read into the Administration database. See Managing Conformance Resources for more background.

Release 4.0.0

This major version introduces a new name: Firely Server instead of Vonk. Other than that, this release contains some significant code changes, which could impact you if you run Firely Server with your own plugins.

Features

  1. Name change Vonk -> Firely Server:

    1. The main entry point dll (formerly: Vonk.Server.dll) and executable (formerly: Vonk.Server.exe) names have been changed to Firely.Server.dll and Firely.Server.exe respectively.

    2. The name was changed in the CapabilityStatement.name.

    3. The name of the download zip (from Simplifier) has changed from vonk_distribution.zip to firely-server-latest.zip. Likewise the versioned zip files have changed as well.

  2. We have implemented FHIR Bulk Data Access ($export) to allow for fast, asynchronous ndjson data exports. The Bulk Data Export documentation can help you to get started.

  3. Firely Server now uses Firely .NET SDK 2.0.2 (formerly: FHIR .NET API)

    Attention

    If you are running Firely Server with your own self-made plugins, you will likely encounter package versioning problems and need to upgrade your NuGet Firely Server package references (package names starting with Vonk.) to version 4.0.0. You also need to upgrade any Firely .NET SDK package references (package names starting with Hl7.Fhir.) to version 2.0.2. The Firely .NET SDK release notes and Breaking changes in Firely SDK 2.0 can give you an idea of the changes you may encounter in the SDK.

  4. SMART on FHIR can now recognize prefixes to the claims, see its SMART on FHIR Configuration.

  5. The smart-configuration endpoint (<url>/.well-known/smart-configuration) relays the signature algorithms configured in the authorization server.

Fixes

  1. Application Insights has now been disabled by default. If you need Application Insights, you can enable it in your log settings file by including the entire section mentioned in Application Insights log settings.

  2. When validating a resource, a non-existing code would lead to an OperationOutcome.issue with the code code-invalid. That issue code has been changed to not-supported.

  3. On a batch or transaction bundle errors were not reported clearly if the entry in error had no fullUrl element. We fixed this by referring to the index of the entry in the entry array, and the resource type of the resource in the entry (if any).

  4. The import[.R4] folder allows for importing custom StructureDefinition resources. If any of them had no id, the error on that caused an exception. Fixed that.

  5. If a Facade returned a resource without an id from the Create method, an error was caused by a log statement. Fixed that.

  6. Indexing Subscription.channel[0].endpoint[0] failed for R4. Fixed that. This means you can’t search for existing Subscriptions by Subscription.url on the /administration endpoint for FHIR R4.

  7. Postman was updated w.r.t. acquiring tokens. We adjusted the documentation on that accordingly.

  8. If a patient claim was included in a SMART on FHIR access token, the request would be scoped to the Patient compartment regardless of the scope claims. We fixed this by allowing “user” scopes to access FHIR resources outside of the Patient compartment regardless of the patient claim. See Launch context arrives with your access_token for more background information.

Plugin and Facade

  1. The mapping plugin is upgraded to the Mapping Engine 0.6.0.

  2. As announced in Release 3.0.0 we removed support for creating a Facade as a standalone ASP.Net Core project. You can now only build a Facade as a plugin to Firely Server. See Firely Server Facade on how to do that.

  3. The order of some plugins has changed. This way it is possible to add a plugin between PreValidation and UrlMapping:

  4. A Facade based on Vonk.Facade.Relational no longer defaults to STU3

    Attention

    If you developed a facade plugin based on Vonk.Facade.Relational, you need to override RelationalQueryFactory.EntryInformationModel(string informationModel) in your implementation to allow the FHIR version you wish to target (see Deciding on a FHIR version)

  5. We took the opportunity of a major version upgrade to clean up a list of items that had been declared Obsolete already. Others have become obsolete now. This is the full list:

    # Obsolete, now deleted:

    # Vonk.Core.Common.DeletedResource # Vonk.Core.Common.IResource.Currency, Change and Clone(), also in VonkResource. # Vonk.Core.Common.IResourceExtensions.ToIResource(this ISourceNode original, ResourceChange change, ResourceCurrency currency = ResourceCurrency.Current) (the overload defaulting to STU3) # Vonk.Core.Context.Guards.SupportedInteractionOptions.SupportsCustomOperationOnLevel() # Vonk.Core.Context.Internal.BatchOptions # Vonk.Core.Operations.Validation.ValidationOptions # Vonk.Core.Pluggability.InteractionHandlerAttribute.Tag # Vonk.Core.Pluggability.ModelOptions # Vonk.Core.Repository.SearchOptions.LatestOne # Vonk.Core.Support.LogHelpers.TryGetTelemetryClient, both overloads. # Vonk.Core.Support.SpecificationZipLocator.ctor(IHostingEnvironment…) # Vonk.Fhir.R3.IResourceVisitor + extensions # Vonk.Fhir.R3.Configuration.ModelContributorsFacadeConfiguration # Vonk.Fhir.R3.FhirExtensions.AsIResource() # Vonk.Fhir.R3.FhirPropertyIndex + FhirPropertyInfo + FhirPropertyIndexBuilder # Vonk.Fhir.R3.IConformanceBuilder + BaseConformanceBuilder + HarvestingConformanceBuilder + extensions + IConformanceContributor # Vonk.Fhir.R3.CompartmentDefinitionLoader + (I)SearchParameterLoader # Vonk.Fhir.R3.MetadataImportOptions + MetadataImportSet + ImportSource # Vonk.Fhir.R3.PocoResource + PocoResourceVisitor # Vonk.Core.InformationModelAttribute (actually made internal)

    # Obsolete since this version:

    # Vonk.Core.Configuration.CoreConfiguration: allows for integrating Vonk components in your own ASP.NET Web server, discouraged per 3.0 (see these releasenotes). # Vonk.Fhir.R3.FhirR3FacadeConfiguration: see above.

Database

This version contains database schema changes for SQL Server, therefore, the upgrade requires running migrations.

  • Admin database:

    • 20200924095035_CreateTasksTable

  • Data database:

    • 20201001101247_CreateExportTable

The migrations will be applied automatically when AutoUpdateDatabase=true in the settings. You can see the list of applied migrations in table [dbo].[__EFMigrationsHistory].