Release notes Firely Server

Upgrading Firely Server

See How to upgrade Firely Server? for information on how to upgrade to a new version of Firely Server.

Public Endpoint Announcement 8 July 2021

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

Release 4.7.0, Feb 1st, 20222

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

  2. MongoDB

    1. Improved performance of searches within a compartment

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 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 $lastN Observations 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 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 $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 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 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.

Release 3.9.3 hotfix

Attention

We changed the behavior of resthook notifications on Subscriptions. See Fix nr 1 below.

Database

  1. SQL Server: The migration that adds the indexes described in Release 3.9.2 hotfix might run longer than the timeout period of 30 seconds. Therefore we added scripts to apply and revert this migration manually. If you encounter the timeout during upgrade: shut down vonk, run the script using SQL Server Management Studio or any similar tool, then start Vonk 3.9.3 again. In both scripts you only need to provide the database name for the database that you want to upgrade. If you run your administration database on SQL Server you can but probably do not need to run this script on it. The administration database is typically small enough to complete the script within 30 seconds.

    1. apply: <vonk-dir>/data/2021211113200_AddIndex_ForCountAndUpdateCurrent_Up.sql

    2. revert: <vonk-dir>/data/2021211113200_AddIndex_ForCountAndUpdateCurrent_Down.sql

Fix

  1. Subscriptions: A resthook notification was sent as a FHIR create operation, using POST. This was not compliant with the specification that states it must be an update, using PUT. We changed the default behavior to align with the specification. In order to avoid breaking changes in an existing deployments, you may set the new setting SubscriptionEvaluatorOptions:SendRestHookAsCreate to true - that way Vonk will retain the (incorrect) behavior from the previous versions.

Release 3.9.2 hotfix

Fix

All fixes are relevant to SQL Server only.

  1. The 3.9.0 fix that “Improved the handling of concurrent updates on the same resource.” decreased the performance of concurrent transaction handling. We implemented another solution that does not affect performance.

  2. Improved read performance by adding an index.

Release 3.9.1 hotfix

Fix

  1. Fixed a bug introduced with 3.9.0 were Vonk would throw the following exception on start-up System.InvalidOperationException: Unable to resolve service for type 'Vonk.Core.Conformance.IDefinitionProvider' while attempting to activate 'Vonk.Fhir.R3.SnapshotGeneration.SnapshotGeneratorR3

  2. Fixed a breaking change to public search API with the implementation of _total parameter. We had introduced a new parameter to the Next method in ResultPage, effectively breaking backwards compatibility. This has been fixed.

Release 3.9.0

Features

  1. We have made Subscriptions more robust. See Subscriptions for details. In summary, if an evaluation of a Subscription fails, Vonk will retry the evaluation periodically for a number amount of tries. You can control the retry period and the maximum number of retries in the subscription settings:

    • RetryPeriod is expressed in milliseconds. Default 30000 (30 sec).

    • MaximumRetries is the maximum amount of times Vonk will retry to send the resources. Default 3 retries.

  2. We have implemented the _total parameter for options none and accurate. Omitting the _total parameter is equivalent to _total=accurate. If the total number of resources is not relevant, using _total=none in the request results in better performance when searching.

  3. It is no longer necessary for the :type parameter to always be provided to distinguish between multiple reference targets. The parameter does not need to be provided anymore when the search only applies to a single target. For example: GET <base>/AllergyIntolerance?patient=xyz The patient:Patient type parameter does not have to be supplied. The ‘patient’ search parameter on AllergyIntolerance has two possible targets. It may reference either a Patient or a Group resource. However, the fhirpath statement that goes with it, selects ‘AllergyIntolerance.patient’, and that reference element may only target a Patient resource.

Fixes

  1. Indexing values for a string search parameter threw an exception when there was no value but only an extension. This has been corrected.

  2. We made the Provenance.target available as a revInclude Parameter in the CapabilityStatement. Previously, Vonk did not account for the case that a reference is allowed to ANY resource type, which incorrectly resulted in Provenance.target to not be shown in the CapabilityStatement.

All the following fixes are only relevant for SQL Server:

  1. Improved the handling of concurrent updates on the same resource.

  2. Upgraded the version of the SqlClient library to fix issues when running on Linux.

  3. Fixed missing language libraries for SQL Server when running on Docker.

Release 3.8.0

Database

  • We added an important note to the 3.6.0 release notes for MongoDb users.

  • Because of the changes in searching for Quantities (feature 2 below), you will need to do a reindex in order to make use of this. You may limit the reindex to only the search parameters of type ‘quantity’ that you actually use (e.g. Observation.value-quantity).

Features

  1. We upgraded the FHIR .NET API to 1.9, see the 1.9 releasenotes. This will trigger an automatic import of the Conformance Resources at startup.

  2. We upgraded the Fhir.Metrics library to 1.2. This allows for a more uniform search on Quantities (mainly under the hood)

  3. We upgraded the FHIR Mapping plugin to support the FHIR Mapper version 0.5.

  4. The built-in terminology services now support the includeDesignations parameter.

  5. The IVonkContext now lets you access the original HttpContext.

  6. The CapabilityStatement now lists the profiles that are known to Vonk (in its Administration database) under CapabilityStatement.rest.resource.supportedProfile (>= R4 only) and the base profile for a resource under CapabilityStatement.rest.resource.profile.

  7. We extended the security extension on the CapabilityStatement to include the endpoints for register, manage, introspect and revoke.

  8. IAdministrationSearchRepository and IAdministrationChangeRepository interfaces are no publicly available. Use with care.

Fixes

  1. If the server configured as authorization endpoint in the Smart setting is not reachable, Vonk will log a proper error about that.

  2. An error message for when a query argument has no value is improved.

  3. When SMART-on-FHIR is enabled, and the received token contains a launch context, the _history operation is no longer available. Because Vonk does not retain the search parameter index for historical resources, it cannot guarantee that these resources fall within the launch context (at least not in a performant way). To avoid information leakage we decided to disable this case altogether.

  4. A Create interaction without an id in the resource, with SMART-on-FHIR enabled, resulted in an exception.

  5. You can now escape the question mark ‘?’ in a query argument by prepending it with a backslash ‘'.

  6. A Quantity search using ‘lt’ on MongoDb resulted in too many results.

Release 3.7.0

Database

Attention

To accommodate for feature #2 below there is an automatic migration carried out for SQL Server and SQLite. This migration might take some time, so please test it first. For MongoDb, you will have to Rebuild the whole search index. If this is not feasible for your database, please Contact us for assistance.

Features

  1. Patch: We implemented FHIR Patch. You can now update a resource having only partial data for it. See Create, read, update, patch, delete.

  2. Search on accents and combined characters: we improved searching with and on accents and combined characters. Note the database change above.

  3. API 1.7: We upgraded Vonk to use the FHIR .NET API 1.7, having its own releasenotes.

  4. Security: The Docker image is now based on the Alpine image for .NET Core. This has far less security issues than the Ubuntu image that we used before. The base image is aspnet:3.1-alpine:3.11 (newest version 3.12 has an open bug related to SQLite).

  5. Security: We revisited the list of security vulnerabilities, see Security notifications for Firely Server.

  6. Administration: ConceptMaps are now imported at startup.

Fixes

  1. Searching on _lastUpdated could be inaccurate when time zone differences are in play. We fixed that.

  2. Search arguments for a quantity search weren’t allowed to be greater than 999.

Release 3.6.1

Features

  1. ConceptMap resources can be stored at the Administration endpoint, both through import and through the RESTful API.

Attention

Previous versions of Vonk did not include the ConceptMap resources in the import so they will currently not be in your Administration database. If you run your Administration database on SQL Server or MongoDb and want to use the ConceptMap resources from the spec, be sure to rerun the import of the specification resources. You can force Vonk to do so by deleting the .vonk-import-history.json file from the ImportedDirectory (see the settings under AdministrationImportOptions). If you use SQLite, you can simply use the pre-built ./data/admin.db from the binaries.

Plugins

  1. The FHIR Mapper plugin is upgraded to version 0.3.6.

  2. The FHIR Mapper plugin now fully works on the Administration endpoint.

Release 3.6.0

Database

Attention

For MongoDb users: We implemented feature #1 below using the Aggregation Pipeline. This makes an existing issue in MongoDb - SERVER-7568 <https://jira.mongodb.org/browse/SERVER-7568> - a more urgent problem. MongoDb has solved this problem in version 4.4. Therefore we advise you to upgrade to MongoDb 4.4.

Feature

  1. Sort: The sorting that was implemented for the SQL/SQLite repositories in the previous version is now also implemented for MongoDb.

  2. Terminology: The local terminology service, built in to the Vonk Administration API, is upgraded to support R4 and R5 (and still R3 of course).

  3. Vonk can now index and search on search parameters that reference a nested resource, like Bundle.message.

    Attention

    Note that any nested resources have to be indexed by Vonk. For new data that is done automatically. But if you want to use this on existing data, you have to reindex for the search parameters you want to use it on. Those will most notably be Bundle.message and Bundle.composition.

  4. If you accidentally provide a body in a GET or DELETE request, Vonk will now ignore that body instead of returning an error.

Fix

  1. CapabilityStatement (rev)includes now use ‘:’ as a separator instead of ‘.’.

Plugins

  1. The BinaryWrapper plugin is upgraded to 0.3.1, where the included BinaryEncodeService is made more reusable for other plugins (most notably the FHIR mapper).

Release 3.5.0

Feature

  1. Search reference by identifier: FHIR R4 allows you to search a reference by its identifier. We added support for this in Vonk. Note that any identifiers in reference elements have to be indexed by Vonk. For new data that is done automatically. But if you want to use this on existing data, you have to reindex for the search parameters you want to use it on. E.g. Observation.patient.

  2. AuditEvent logging: In release 3.3.0 we already added support for logging audit information to a file. With this release we add to that logging that same information in AuditEvent resources. These resources are written to the Vonk Data database (not the Administration database). Users are not allowed to update or delete these resources. See Auditing for more background.

  3. Audit logging: We added [Request] or [Response] to the log lines so you can distinguish them better.

  4. Sort: We started implementing sorting. This release provides sorting for search parameters of the types string, number, uri, reference, datetime and token, on the repositories SQL, SQLite and Memory. On the roadmap is extending this support to MongoDb and to quantity search parameters.

  5. Terminology Integration: You can configure Vonk to route the terminology operations to external terminology servers. You can even configure a preferred server for certain code systems like LOINC or Snomed-CT. On the roadmap is to also allow you to use these servers for validation of codes and for token searches.

  6. We implemented $meta-delete, see Meta plugins.

  7. Loading plugins can lead to unexpected errors. We made the process and the log friendlier, so you can spot configuration errors more easily:

    • The log outputs the version of each of the plugins

    • If a duplicate .dll file is found, Vonk tells you which two dlls are causing this and then exits.

    • If you configured a plugin that you are not licensed to use, this is logged with a friendly hint to acquire a license that does allow you to use it.

  8. The log is now by default configured to use asynchronous logging so Vonk is not limited by the speed of the logging sinks (like the Console and the log file). Please update your logsettings.instance.json if you created your own log settings in that. See Log settings for more background.

Fix

  1. You could load invalid XML in the Resource.text through a JSON payload. When that resource was then retrieved in XML, it would fail with an InternalServerError. Vonk will now return an OperationOutcome telling you what the problem is. You can then correct it by using JSON.

  2. Composite search parameters were not parsed correctly. Now they are. So you don’t see warnings like Composite SearchParameter 'CodeSystem.context-type-quantity' doesn't have components. anymore.

  3. Indexing for the _profile search parameter was broken for R4 since Vonk 3.2.1. We fixed it. If you added new resources with Vonk 3.2.1 - 3.4.0, you need to reindex for the Resource._profile parameter.

  4. Audit log: %temp% in the path setting was evaluated as <current directory>\%temp%. Fixed that to evaluate to the systems temporary directory.

  5. The logsettings.json configured the Serilog RollingFile sink by default. That is deprecated, so we replaced it with the File sink.

  6. Rebuild the search index for specific searchparameters now returns an error if you forget to actually specify a search parameter.

  7. An InternalServerError was returned when you validate a resource that is syntactically incorrect. Like a Patient with multiple id’s. Vonk now returns an OperationOutcome with the actual problem.

  8. The configuration for the FHIR Mapper was simplified. You only need to include Vonk.Plugin.Mapping. Check appsettings.default.json for the new pipeline.

  9. Maybe you got accustomed to ignoring a list of warnings at startup of Vonk. We cleaned up the list so that if there is a warning, it is worthwhile investigating the cause of it.

  10. The appsettings and logsettings can contain relative file paths for several settings, like the License:LicenseFile. These were evaluated against the current working directory, but that could lead to problems if that was not the Vonk directory. We solved that: all relative paths are evaluated against the Vonk directory.

  11. The docker image for version 3.4.0 was tagged 3.4.0-. With 3.5.0 we removed the superfluous hyphen at the end.

  12. We updated the documentation on Using Firely Server on Docker on SQL Server to be clearer about the order of the steps to take.

  13. We updated the documentation on Firely Server Plugin example - Create a new landing page to match .NET Core 3.1.

Plugins & Facade

  1. FHIR Mapper

    • Has been upgraded to version 0.3.4.

Release 3.4.0

Feature

  1. Upgraded to FHIR .NET API 1.6.0, that features a couple of changes for working with CDA logical models. See the release notes of the API.

  2. Included the FHIR Mapper in the distribution. It is only enabled however when you include the mapping plugin in your license.

Fix

  1. When prevalidation is set to the level ‘Core’, Vonk no longer complains about extensions that are not known if they are not core extensions (i.e. having a url starting with ‘http://hl7.org/fhir/StructureDefinition/’).

Release 3.3.0

Attention

To use the new features for auditing and R5, you need a new license file including the tokens for those plugins. For evaluation and community editions you can retrieve them from Simplifier.net. If you need these updates in your production license, please contact us.

Feature

  1. Vonk was upgraded to FHIR .NET API 1.5.0. See the release notes of the API.

  2. Vonk can now log audit lines in a separate file. This can help you achieve HIPAA/GDPR compliancy. See Auditing for more info.

  3. Failed authorization attempts are now logged from the SMART on FHIR plugin.

  4. Support for _include:iterate and _revinclude:iterate, see Search.

  5. The BinaryWrapper plugin is now two-way. So you can POST binary content and have it stored as a Binary resource, and GET a Binary resource and have it returned in its original binary format.

  6. Experimental support for R5 is now included in the Vonk distribution. For enabling it, see Support for R5 (experimental!).

Fix

  1. Indexing of a quantity in resource could fail with a Status code 500 if it had no .value but only extensions.

  2. The use of a SearchParameter of type reference having no target failed. These search parameters are now signalled upon import.

  3. Since R4 it is valid to search for a quantity without specifying the unit. Vonk now accepts that.

  4. A transaction response bundle could contain an empty response.etag element, which is invalid.

  5. Preloading resources was not working since the upgrade to .NET Core 3.0. That has been fixed. It is still only available for STU3 though.

  6. Administration import would state that it moves a file to history when it had imported it. That is no longer true, so we removed this incorrect statement from the log.

  7. $validate-code could cause a NullReference exception in some case.

  8. The generated CapabilityStatement for R4 failed constraint cpb-14.

  9. Content negotiation favoured a mediatype with quality < 1 over a mediatype without quality. But the default value is 1, so the latter is now favoured.

  10. Validate an instance from the database did not account for the informationmodel (aka FHIR version) of the resource.

Plugins & Facade

  1. Document Operation

    • Has been upgraded to Vonk 3.2.0.

    • Was assigned a license token

    • Assigns an id and lastUpdated to the result bundle

  2. Conversion

    • Has been upgraded to Vonk 3.2.0.

    • Was assigned a license token.

  3. Vonk.Facade.Starter has been upgraded to Vonk 3.2.1 and as a consequence also to EntityFrameworkCore 3.1.0.

Release 3.2.1

Fix

  1. SMART plugin now understands multiple scopes per access token.

  2. SMART plugin now understands Resource.* claims, in addition to already understanding Resource.read and Resource.write.

Release 3.2.0

Attention

Vonk 3.2.0 is upgraded to .NET Core 3.1.0, ASP.NET Core 3.1.0 and EntityFramework Core 3.1.0.

  • For running the server: install the ASPNET.Core runtime 3.1.0.

  • For developing or upgrading Facades that use Vonk.Facade.Relational: upgrade to EF Core 3.1.0.

  • Plugins that target NetStandard 2.0 need not be upgraded.

Database

  1. There are no changes to the databases. The upgrade of EntityFramework Core does not affect the structure of the SQL Server or SQLite databases, just the access to it.

Fix

  1. Supported interactions were not enforced for custom operations like e.g. $convert.

  2. If a resource failed Validating incoming resources, the OperationOutcome also contained issues on not supported arguments.

  3. A search with ?summary=count failed.

  4. Added support for FhirPath hasValue() method.

  5. Resolution of canonical http://hl7.org/fhir/v/0360|2.7 failed.

  6. CapabilityStatement.rest.resource.searchInclude used ‘.’ as separator, fixed to use ‘:’ in <resource>:<search parameter code>

  7. Changed default value of License:LicenseFile to vonk-license.json, aligned with the default naming if you download a license from Simplifier.

  8. Reindexing always interpreted a resource as STU3. Now it correctly honours the actual FHIR version of the resource.

Feature

  1. BinaryWrapper plugin can now be restricted to a list of mediatypes on which to act.

  2. Vonk used to sort on _lastUpdated by default, and add this as extra sort argument if it was not in the request yet. Now you can configure the element to sort on by default in BundleOptions:DefaultSort. Although Vonk FHIR Server does not yet support sorting on other elements, this is useful for Facade implementations that may support that (and possibly not support sort on _lastUpdated). See also Search and History.

  3. Implemented $versions operation

  4. Extended the documentation on:

  5. The SMART authorization plugin can now be configured to not check the audience. Although not recommended, it can be useful in testing scenarios or a highly trusted environment.

    Attention

    We changed the default value for the setting SmartAuthorizationOptions.Audience from vonk to empty, or ‘not set’. This is to avoid awkward syntax to override it with ‘not-set’. But if you rely on the value vonk, please override this setting in your appsettings[.instance].json or environment variables as described in Changing the settings.

Plugin and Facade API

  1. Vonk.Facade.Relational now supports the use of the .Include() function of EntityFramework Core. To do so, override RelationalQuery.GetEntitySet(DbContext dbContext).

  2. Vonk.Facade.Relational now supports sorting. Override RelationalQueryFactory.AddResultShape(SortShape sortShape) and return a RelationalSortShape using the extension method ``SortQuery().

Release 3.1.3 hotfix

Fix

  1. Fixed behavior on conditional updates in transactions. In odd circumstances Vonk could crash on this.

Release 3.1.0

Please also note the changes in 3.0.0 (especially the one regarding the SQL server database)

Fix

  1. Validation on multi-level profiled resources no longer fails with the message “Cannot walk into unknown StructureDefinition with canonical”

  2. Improved documentation on upgrading Vonk, the Vonk pipeline, CORS support, plugins and IIS deployment

  3. Using multiple parameters in _sort led to an error for all repositories

  4. Vonk UI capability statement view now works for self-mapped endpoints like /R3 or /R4

  5. A saved resource reference (e.g. Patient.generalPractitioner) on a self-mapped endpoint (e.g. /R4/...) would have its relative path duplicated (/R4/R4/...)

    Attention

    If you have used self-mapped endpoints (appsettings: InformationModel.Mapping.Map in the ‘Path’ mapping mode) and you have saved resources containing references, it is possible that your database now contains some resources with broken references. Please contact us if this is the case

Feature

  1. The new experimental FHIR mapping engine, which is currently exclusively available on our public FHIR server http://vonk.fire.ly

  2. New licensing system, supporting the community edition

  3. Simplifier projects are now imported for FHIR R4 as well

  4. The following plugins have been bundled with the Vonk release (compare your appsettings with the new appsettings.default.json to activate them)

    1. The $document operation (see Documents)

    2. The $convert operation (see Conversion)

    3. The binary wrapper (see Binary)

Plugin and Facade API

  1. Vonk.Facade.Starter has been upgraded to work with Vonk 3.1.0

  2. IConformanceContributor and IConformanceBuilder have moved from Vonk.Core.Pluggability to Vonk.Fhir.R3.Metadata. It is also deprecated, as Vonk.Core.Metadata.ICapabilityStatementContributor is now preferred instead. See Capabilities for more information

  3. Implementations of ISearchRepository can now sort on multiple parameters (in BaseQuery.Shapes). Previously this would result in an error.

  4. Improved documentation on the Important classes and interfaces

  5. See Release 3.0.0 for some additional issues you may encounter upgrading your plugins

Release 3.0.0

Database

Please also note the changes in 3.0.0-beta1

  1. SQL Server: SQL script ‘20190919000000_Cluster_Indexes_On_EntryId.sql’ (found in the /data folder of the Vonk distribution) must be applied to existing Vonk SQL databases (both to the admin and to the data repositories)

    Attention

    Vonk 3.0.0 (using SQL server) will not start unless this script has been applied to the databases. Please note that running the script can take considerable time, especially for large databases.

Feature

  1. Information model (= FHIR version) settings

    1. Although Vonk now supports multiple information models (STU3 and R4) simultaneously, an unused model can be disabled (see Configuring the Firely Server Pipeline)

    2. You can set the default (or fallback) information model (previously: STU3), which is used when Vonk can not determine the information model from context (see Information model)

    3. You can map a path or a subdomain to a specific information model (see Information model), mitigating the need to specify it explicitly in a request

  2. Vonk now uses FHIR .NET API 1.4.0

  3. Several performance enhancements have been made for SQL server and IIS setups

  4. Added R4-style Conditional Update to both STU3 and R4

Fix

  1. Circular references within resources are now detected, cancelling validation for now. We will re-enable validation for these resources when the FHIR .NET API has been updated

  2. An $expand using incorrect data returned a 500 (instead of the correct 400)

  3. Vonk now returns a 406 (Not Acceptable) when the Accept header contains an unsupported format

  4. Deletes did not work for R4

  5. Search parameters

    1. Search parameters were read twice (at startup and upon the first request)

    2. Search parameter ‘CommunicationRequest.occurrence’ is not correctly specified in the specification. We provide a correct version.

  6. _history

    1. _history was not usable in a multi information model setup

    2. The resulting Bundle.entry in an STU3 _history response contained the unallowed response field

    3. Added Bundle.entry.response to the R4 _history entry

  7. Batches

    1. Valid entries in batches also containing invalid entries were not processed

    2. Duplicate fullUrls are no longer accepted in a batch request, which previously led to a processing error

    3. An R4 transaction resulted in STU3 entries

    4. Transactional errors did not include fullUrl

Plugin and Facade API

  1. Improved the message you get when the sorting/shaping operator is not implemented by your facade

  2. VonkOutcome (and VonkIssue) has been simplified

  3. VonkConstants has moved from Vonk.Core.Context to Vonk.Core.Common

  4. IResourceChangeRepository.Delete requires a new second parameter: string informationModel. Information model constants can be found in Vonk.Core.Common.VonkConstants.Model

  5. Exclude Vonk.Fhir.R3 or Vonk.Fhir.R4 from the PipelineOptions if you don’t support it in your Facade.

  6. Updated the minimal PipelineOptions for a Facade Plugin in the example appsettings.json:

    • updated Vonk.Core.Operations.SearchConfiguration to Vonk.Core.Operations.Search

    • removed Vonk.UI.Demo

    • removed Vonk.Core.Operations.Validate.SpecificationZipSourceConfiguration from the Exclude

    • updated Vonk.Core.Operations.Terminology to Vonk.Plugins.Terminology

Note

Early Facade implementations were built with by using Vonk services and middleware in a self-built ASP.NET Core web server. This can be seen in the Vonk.Facade.Starter project in the repository with the same name. Due to changes in Vonk this does not work with Vonk 3.0.0. It will be fixed in 3.1.0. But after that such projects cannot be upgraded anymore and will have to be refactored to a proper plugin (as the ViSi.Repository project in the same repository). Please contact us in case of any questions.

Release 3.0.0-beta2

Attention

We updated the Security notifications for Firely Server.

Database

Note the changes in 3.0.0-beta1, but there are no new changes in beta2.

Feature

  1. Subscriptions works for R4 also. Note that a Subscription will only be activated for resource changes in the same FHIR version as the Subscription itself.

  2. Load Conformance Resources from disk works for R4 also. Use a directory name that ends with .R4 for R4 conformance resources.

  3. Re-indexing for new or changed SearchParameters works for R4 also. Issue a reindex with a fhirVersion parameter in the Accept header, and it will be executed for the SearchParameters defined for that FHIR version.

  4. Allow for non-hl7 prefixed canonical urls for conformance resources (since sdf-7 is lifted). See Custom Resources.

  5. Custom Resources can be validated, both individually and as part of a bundle. See Custom Resources.

  6. If the Accept header lacks a fhirVersion parameter, it will fall back to the fhirVersion parameter of the Content-Type header and vice versa. If both are missing, Vonk will default to STU3.

Fix

  1. _include did not work for R4.

  2. _include gave a 500 response code if a resource contains absolute references.

  3. A resource with unknown elements could result in an uncaught Hl7.Fhir.ElementModel.StructuralTypeException.

  4. The homepage stated that Vonk was only for STU3. Fixed that.

  5. Bundle.timestamp element (new in R4) was not populated in bundles returned from Search and History operations.

  6. Some operations could return an OperationOutcome with an issue and a success message.

  7. Better error message if a resource without any meta.profile is not accepted by Validating incoming resources.

  8. Requesting an invalid FHIR version resulted in a ArgumentNullException.

Plugin and Facade API

  1. NuGet package Vonk.Fhir.R4 had a dependency on Vonk.Administration.API, but the latter is not published. We removed the dependency.

  2. IResourceExtensions.UpdateMetadata did not update the id of the resource.

  3. VonkOutcome.RemoveIssue() method has been removed.

Examples

  1. Plugin example (Vonk.Plugin.ExampleOperation):

    1. Added an example of middleware directly interacting with the HttpContext (instead of just the VonkContext), see the file VonkPluginMiddleware.cs

    2. CapabilityStatementBuilder was not called.

  2. DocumentOperation (Vonk.Plugin.DocumentOperation):

    1. Composition ID was not determined correctly when using POST.

Release 3.0.0-beta1

Vonk 3.0.0 is a major upgrade that incorporates handling FHIR R4. This runs in the same server core as FHIR STU3. See Multiple versions of FHIR for background info.

Attention

If you have overridden the PipelineOptions in your own settings, you should review the new additions to it in the appsettings.default.json. In particular we added Vonk.Fhir.R4 that is needed to support FHIR R4.

Attention

MacOS: you may need to clean your temp folder from previous specification.zip expansions. Find the location of the temp folder by running echo $TMPDIR.

Database

  1. SQL Server, SQLite:

    1. vonk.entry got a new column ‘InformationModel’, set to ‘Fhir3.0’ for existing resources.

    2. vonk.ref got a new column ‘Version’.

    3. Database indexes have been updated accordingly.

    Vonk will automatically update both the Administration and the Data databases when you run Vonk 3.0.0.

  2. MongoDb / CosmosDb:

    1. The documents in the vonkentries collection got a new element im (for InformationModel), set to ‘Fhir3.0’ for existing resources.

    2. The documents in the vonkentries collection got a new element ref.ver (for Version).

    3. Database indexes have been updated accordingly.

  3. MongoDb / CosmosDb: Got a light mechanism of applying changes to the document structure. A single document is added to the collection for that, containing VonkVersion and LatestMigration.

  4. MongoDb: The default name for the main database was changed from ‘vonkstu3’ to ‘vonkdata’. If you want to continue using an existing ‘vonkstu3’ database, override MongoDbOption:DatabaseName, see Hierarchy of settings.

Feature

  1. Support for FHIR R4 next to FHIR STU3. Vonk will choose the correct handling based on the fhirVersion parameter in the mimetype. The mimetype is read from the Accept header and (for POST/PUT) the Content-Type header. See Multiple versions of FHIR for background info.

  2. Upgrade to HL7.Fhir.Net API 1.3, see its releasenotes.

  3. Administration API imports both STU3 and R4 conformance resources, see Conformance Resources

    1. Note: Terminology operations are still only available for STU3.

    2. Note: Subscriptions are still only available for STU3.

  4. Conditional delete on the Administration API. It works just as on the root, see Create, read, update, patch, delete.

  5. Defining a custom SearchParameter on a Custom ResourceType is now possible.

  6. Canonical uris are now recognized when searching on references (specification)

  7. Vonk calls UseIISIntegration for better integration with IIS (if present).

Fix

  1. In the settings, PipelineOptions.Branch.Path for the root had to be /. Now you can choose your own base (like e.g. /fhir)

  2. $meta:

    1. enabled on history endpoint (e.g. /Patient/123/_history/v1)

    2. disabled on type and system level

    3. returned empty Parameters resource if resource had no meta.profile, now returns the resources meta element.

    4. when called on a non-existing resource, returns 404 (was: empty Parameters resource)

    5. added to the CapabilityStatement

  3. History on non-existing resource returned OperationOutcome instead of 404.

  4. The setting for SupportedInteractions was not enforced for custom operations.

  5. CapabilityStatement.name is updated from Vonk beta conformance to Vonk FHIR Server <version> CapabilityStatement.

  6. Terminology services:

    1. $lookup did not work on GET /CodeSystem

    2. $lookup did not support the coding parameter

    3. $expand did not fill in the expansion element.

    4. Operations were not listed in the CapabilityStatement.

    5. Namespace changed to Vonk.Plugins.Terminology, and adjusted accordingly in the default PipelineOptions.

  7. A SearchParameter of type token did not work on an element of type string, e.g. CodeSystem.version.

  8. Search with POST was broken.

  9. If a long running task is active (response code 423, see Import of Conformance Resources and Re-indexing for new or changed SearchParameters), the OperationOutcome reporting that will now hide issues stating that all the arguments were not supported (since that is not the cause of the error).

  10. Overriding an array in the settings was hard - it would still inherit part of the base setting if the base array was longer. We changed this: an array will always overwrite the complete base array. Note that this may trick you if you currently override a single array element with an environment variable. See Hierarchy of settings.

  11. The element meta.source cannot be changed on subsequent updates to a resource (R4 specific)

  12. SearchParameter StructureDefinition.ext-context yielded many errors in the log because the definition of the fhirpath in the specification is not correct. We provided a corrected version in errataFhir40.zip (see Errata to the specification).

  13. Enable or disable interactions was not evaluated for custom operations.

  14. Delete of an instance accepted search parameters on the url.

  15. Transactions: references to other resources in the transaction were not updated if the resource being referenced was in the transaction as an update (PUT). (this error was introduced in 2.0.0).

Plugin and Facade API

  1. A new NuGet package is introduced: Vonk.Fhir.R4.

  2. VonkConstants moved to the namespace Vonk.Core.Common (was: Vonk.Core.Context)

  3. IResource.Navigator element is removed (was already obsolete). Instead: Turn it into an ITypedElement and use that for navigation with FhirPath.

  4. InformationModel element is added to

    1. IResource: the model in which the resource is defined (VonkConstants.Model.FhirR3 or VonkConstants.Model.FhirR4)

    2. IVonkContext: the model that was specified in the Accept header

    3. IModelService: the model for which this service is valid (implementations are available for R3 and R4)

    4. InteractionHandler attribute: to allow you to specify that an operation is only valid for a specific FHIR version. This can also be done in the fluent interface with the new method AndInformationModel. See Interaction Handling

  5. Dependency injection: if there are implementations of an interface for R3 and R4, the dependency injection in Vonk will automatically inject the correct one based on the InformationModel in the request.

  6. If you want to register your own service just for one informationmodel, do that as follows:

    Add a ContextAware attribute to the implementation class:

    [ContextAware (InformationModels = new[] {VonkConstants.Model.FhirR3}]
public class MySearchRepository{...}

    Then register the service as being ContextAware:

    services.TryAddContextAware<ISearchRepository, MySearchRepository>(ServiceLifeTime.Scoped);

  7. FhirPropertyIndexBuilder is moved to Vonk.Fhir.R3 (and was already marked obsolete - avoid using it)

  8. Implementations of the following that are heavily dependent upon version specific Hl7.Fhir libraries have been implemented in both Vonk.Fhir.R3 and Vonk.Fhir.R4.

    1. IModelService

    2. IStructureDefinitionSummaryProvider (to add type information to an IResource and turn it into an ITypedElement)

    3. ValidationService

  9. IConformanceContributor is changed to ICapabilityStatementContributor. The methods on it have changed slightly as well because internally they now work on a version-independent model. Please review your IConformanceContributor implementations.

Examples

  1. Document plugin:

    1. Document Bundle does not contain an identifier

    2. Missing unit test for custom resources

    3. Upgraded to Vonk 2.0.0 libraries (no, not yet 3.0.0-beta1)

  2. Facade example

    1. Added support for searching directly on a reference from Observation to Patient (e.g. /Observation?patient=Patient/3).

    2. Fixed support for _revinclude of Observation on Patient (e.g. /Patient?_revinclude:Observation:subject:Patient).

    3. Upgraded to Vonk 2.0.0 libraries (no, not yet 3.0.0-beta1)

  3. Plugin example

    1. Added examples for pre- and post handlers.

Known to-dos

  1. Re-indexing for new or changed SearchParameters: does not work for R4 yet.

  2. Preloading resources: does not work for R4 yet.

  3. Subscriptions: do not work for R4 yet.

  4. Terminology services: operations do not work for R4.

  5. During Import of Conformance Resources: Files in the import directory and Simplifier projects are only imported for R3.