Release notes Vonk

Upgrading Vonk

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

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 Vonk 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. IResourceChangeRepository.Delete requires a new second parameter: string informationModel
  4. Exclude Vonk.Fhir.R3 or Vonk.Fhir.R4 from the PipelineOptions if you don’t support it in your Facade.
  5. 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 Vonk.

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 directoryname 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 responsecode 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 Running 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 Running 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 Controlling the 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 FHIR Versions.
  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:
    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 (responsecode 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 searchparameters 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 a set of resources: does not work for R4 yet.
  3. Subscriptions: do not work for R4 yet.
  4. Terminology: 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.

Release 2.1.0

Database

  1. SQL Server: Improved concurrent throughput.

Features

  1. Upgrade to HL7.Fhir.Net API 1.3, see its releasenotes.
  2. Vonk calls UseIISIntegration for better integration with IIS (if present).

Fix

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

Release 2.0.1 hotfix

Fix

  1. Supported Interactions were not checked for custom operations. In the appsettings.json the custom operations, like $meta, were ignored. This has been fixed now.

Release 2.0.0 final

This is the final release of version 2.0.0, so the -beta is off. If you directly upgrade from version 1.1, please also review all the 2.0.0-beta and -beta2 release notes below.

Attention

We upgraded the version of .NET Core used to 2.2. Please get the latest 2.2.x runtime from the .NET download site. The update was needed for several security patches and speed improvements.

Attention

The structure of the Validation section in the settings has changed. See Validating incoming resources for details.

Attention

This version of Vonk is upgraded to the Hl7.Fhir.API version 1.2.0. Plugin- and Facade builders will transitively get this dependency through the Vonk.Core package.

Database

No changes have been made to any of the database implementations.

Fix

  1. When you created a StructureDefinition for a new resourcetype on /administration, the corresponding endpoint was not enabled.
  2. Vonk does not update references in a transaction when a conditional create is used for an existing resource.
  3. Paths in PipelineOptions would interfere if one was the prefix of the other.
  4. Indexing a HumanName with no values but just extensions failed.
  5. The selflink in a bundle did not contain the sort parameters. In this version the selflink always contains a sort and a count parameter, even if they were not in the request and the default values have been applied.
  6. The import of conformance resources from specification.zip yielded warnings on .sch files.
  7. Errors introduced in the 2.0.0-beta versions:
    1. Syntax errors in the XML or JSON payload yielded an exception, now they are reported with an OperationOutcome upon parsing.
    2. $expand and other terminology operations caused a NullReference exception.
    3. _element did not include the mandatory elements.

Feature

  1. Vonk supports Custom Resources. See Custom Resources.
  2. Operation $meta is now supported, to quickly get the tags, security labels and profiles of a resource.
  3. /metadata, retrieving the CapabilityStatement performs a lot better (just the initial call for a specific Accept-Type takes a bit longer).
  4. Validation can be controlled more detailed. Choose the strictness of parsing independent of the level of validation. With this, the settings section ‘Validation’ has also changed. See Validating incoming resources.

Plugin and Facade API

  1. We upgraded the embedded Fhir.Net API to version 1.2, see its release notes.
  2. Together with the upgrade to .NET Core 2.2, several libraries were updated as well. Most notably Microsoft.EntityFrameworkCore.*, to 2.2.3.

Release 2.0.0-beta2

Fix

  • Fixed RelationalQuery in Vonk.Facade.Relational, so Vonk.Facade.Starter can be used again.

Release 2.0.0-beta

We have refactored Vonk internally to accomodate future changes. There are only minor functional changes to the FHIR Server. Facade and Plugin builders must be aware of a few interface changes, most notably to the IResource interface.

This release is a beta release because of the many internal changes, and because we expect to include a few more in the final release. Have a go with it in your test environment to see whether you encounter any trouble. We also encourage you to build your plugin and/or facade against it to prepare for code changes upon the final release.

You can still access the latest final release (1.1.0):

  • Binaries: through the Simplifier downloads page, choose ‘List previous versions’.
  • Docker: docker pull simplifier/vonk:1.1.0
  • NuGet: <PackageReference Include="Vonk.Core" Version="1.1.0" />

Database

No changes have been made to any of the database implementations.

Fix

  1. The $validate operation processes the profile parameter.
  2. If an update brings a resource ‘back to life’, Vonk returns statuscode 201 (previously it returned 200).
  3. On an initial Administration Import of specification.zip, Vonk found an error in valueset.xml. This file was fixed in the specification.zip that comes with Fhir.NET API 1.1.2.
  4. Transaction: references within the transaction are automatically changed to the id’s the referenced resources get from Vonk when processing the transaction. This did not happen for references inside extensions. It does now.
  5. Administration Import: an Internal Server Error could be triggered with a zip file with nested directories in it.
    • NB: Directories in your zip are still not supported because of Fhir.NET API issue #883, but Vonk will not error on it anymore.
  6. Search: The entry.fullUrl for an OperationOutcome in a Search bundle had a relative url.
  7. Search: Processed _elements and _summary arguments were not reported in the selflink of the bundle (or any of the paging links).
  8. Search: The selflink will include a _count parameter, even if it was not part of the request and hence the default value for _count from the BundleOptions was applied.
  9. Search on :exact with an escaped comma (e.g. /Patient?name:exact=value1\,value2) was executed as a choice. Now the escape is recognized, and the argument processed as one term.

Feature

  1. Upgraded Fhir.NET API to version 1.1.2, see its release notes.
  2. The Vonk Administration API now allows for StructureMap and GraphDefinition resources to be loaded.
  3. The opening page of Vonk (and the only UI part of it) is updated. It no longer contains links that you can only execute with Postman, and it has a button that shows you the CapabilityStatement.
  4. We published our custom operations on Simplifier! And integrated those links into the CapabilityStatement.
  5. You can now access older versions of the Vonk binaries through the Simplifier downloads. (This was already possible for the Docker images and NuGet packages through their respective hubs).
  6. Vonk.IdentityServer.Test and Vonk.Facade.Starter have been integrated into the Continuous Integration system.
  7. In JSON, the order of the output has changed:
    1. If id and/or meta elements were added by Vonk (on a create or update), they will appear at the end of the resource.

Plugin and Facade API

  1. IResource interface and related classes have had several changes. If you encounter problems with adapting your code, please contact us.

    • It derives from the ISourceNode interface from the Fhir.NET API.

    • Change and Currency are properties that were only relevant in the repository domain, and not in the rest of the pipeline. They have been deprecated. You can access the values still with resource.GetChangeIndicator() and resource.GetCurrencyIndicator(). This is implemented with Annotations on the ISourceNode. All of Vonk’s own implementations retain those annotations, but if the relevant annotation is somehow missing, default values are returned (ResourceChange.NotSet resp. ResourceCurrency.Current).

    • The Navigator property is obsolete. The type of it (IElementNavigator) is obsolete in the Fhir.NET API. To run FhirPath you provide type information and run the FhirPath over an ITypedElement:

      //Have IStructureDefinitionSummaryProvider _schemaProvider injected in the constructor.
      var typed = resource.ToTypedElement(_schemaProvider);
      var matchingElements = typed.Select('your-fhirpath-expression');
      
    • Id, Version and LastUpdated can no longer be set directly on the IResource instance. IResource has become immutable (just like ISourceNode). The alternatives are:

      var resourceWithNewId = resource.SetId("newId");
      var resourceWithNewVersion = resource.SetVersion("newVersion");
      var resourceWithNewLastUpdated = resource.SetLastUpdated(DateTimeOffset.UtcNow);
      
    • Because the IChangeRepository is responsible for creating new id’s and versions, we also included extensions methods on it to update all three fields at once:

      var updatedeResource = changeRepository.EnsureMeta(resource, KeepExisting.Id / Version / LastUpdated);
      var updatedResource = changeRepository.FreshMeta(resource); //replaces all three
      
  2. The PocoResource class is obsolete. To go from a POCO (like an instance of the Patient class) to an IResource, use the ToIResource() extension method found in Vonk.Fhir.R3.

  3. The PocoResourceVisitor class is obsolete. Visiting can more effectively be done on an ITypedElement:

    //Have IStructureDefinitionSummaryProvider _schemaProvider injected in the constructor.
    var typed = resource.ToTypedElement(_schemaProvider);
    typed.Visit((depth, element) => {//do what you want with element});
    
  4. SearchOptions has changed:

    • Properties Count and Offset have been removed.
    • Instead, use _count and _skip arguments in the IArgumentCollection provided to the SearchRepository.Search method if you need to.
  5. We have created a template for a plugin on GitHub. Fetch it for a quick start of your plugin.