Merge pull request #148 from FirelyTeam/vonk/4.0.0

Vonk/4.0.0

firelyserver/administration_api.rst

@@ -1,7 +1,7 @@
 .. _administration_api:
 
 Firely Server Administration API
-=======================
+================================
 
 Besides the regular FHIR endpoint, Firely Server also exposes an Administration API. The endpoint for this is:
 ::

firelyserver/configuration/appsettings.rst

@@ -1,7 +1,7 @@
 .. _configure_appsettings:
 
 Firely Server settings
-=============
+======================
 
 Firely Server settings are controlled in json configuration files called ``appsettings(.*).json``. The possible settings in these files are all the same and described below.
 The different files are read in a hierarchy so you can control settings on different levels. All appsettings files are in the Firely Server distribution directory, next to Firely.Server.dll.
@@ -468,7 +468,7 @@ See :ref:`restful_history`.
 .. _settings_pipeline:
 
 Configuring the Firely Server Pipeline
------------------------------
+--------------------------------------
 
 You can add your own plugins to the Firely Server pipeline, or control which of the standard Firely Server plugins
 are used for your Firely Server, by changing the ``PipelineOptions``.

firelyserver/configuration/configuration.rst

@@ -1,7 +1,7 @@
 .. _configure_vonk:
 
-Configuring the Firely Server
-===========================
+Configuring Firely Server
+=========================
 
 In this section we assume you have downloaded and installed the Firely Server binaries, and have obtained a license file.
 If not, please see the :ref:`previous section <getting_started>` and follow the steps there first.

firelyserver/configuration/cors.rst

@@ -3,6 +3,6 @@
 Cross Origin Resource Sharing (CORS)
 ====================================
 
-CORS is enabled in Firely Server FHIR Server.
+CORS is enabled in Firely Server.
 Since Firely Server provides an API that is expected to be consumed by applications from different domains, CORS is enabled for any origin.
 Currently there is no setting to control this behaviour.

firelyserver/configuration/db_mongo.rst

@@ -89,7 +89,7 @@ This works the same as with the normal Firely Server database, except that you:
     For MongoDb it is essential to retain the ``.vonk-import-history.json`` file. Please read :ref:`vonk_conformance_history` for details.
 
 Tips and hints for using MongoDb for Firely Server
------------------------------------------
+--------------------------------------------------
 
 #. If searches and/or creates and updates are excessively slow, you may be limited by the IOPS on your MongoDb deployment (e.g. MongoDb Atlas). Try upgrading it and check the timings again.
 #. If for any reason you would like to see how Firely Server is interacting with MongoDb, make the following adjustments to the :ref:`configure_log`:

firelyserver/configuration/db_sql.rst

@@ -74,7 +74,7 @@ In both cases:
 
 
 Have Firely Server create your database
-------------------------------
+---------------------------------------
 
 This option is mainly for experimentation as it effectively requires sysadmin privileges for the connecting user.
 
@@ -112,7 +112,7 @@ This option is mainly for experimentation as it effectively requires sysadmin pr
     For SQL Server it is essential to retain the ``.vonk-import-history.json`` file. Please read :ref:`vonk_conformance_history` for details.
 
 Create a database and users by script, and have Firely Server create the schema
-----------------------------------------------------------------------
+-------------------------------------------------------------------------------
 
 *   Log into SQL Server as the Administrator user.
 

firelyserver/configuration/db_sqlite.rst

@@ -7,18 +7,18 @@
 Using SQLite
 ============
 
-SQLite is a file based database engine. The engine itself does not run separately on the server, but in-process in the application, Firely Server FHIR Server in this case. 
+SQLite is a file based database engine. The engine itself does not run separately on the server, but in-process in the application, Firely Server in this case. 
 
 For more background on SQLite please refer to the `SQLite documentation <https://sqlite.org/about.html>`_.
 
-SQLite is the default configuration of Firely Server FHIR Server. For the Administration database there is little reason to change this. 
+SQLite is the default configuration of Firely Server. For the Administration database there is little reason to change this. 
 For the actual runtime data, (the 'Firely Server database') itself, you may run into limitations of SQLite if you put it through its paces. 
 You may find one of the other repositories a better fit then. You can safely use different storage engines for Firely Server Data and Firely Server Administration.
 
 .. _sqlite_admin_reasons:
 
 Prefer SQLite for Firely Server Administration
--------------------------------------
+----------------------------------------------
 
 Until Firely Server (Vonk) version 0.7.0 you could use any of the storage engines for both Firely Server Data and Firely Server Administration. Starting with Firely Server (Vonk) 0.7.1 you are encouraged to use SQLite for Firely Server Administration.
 Over time we will deprecate support for running Firely Server Administration on the SQL Server, MongoDb and Memory storage engines.
@@ -34,13 +34,13 @@ Firely Server Administration poses very limited stress on its storage engine, th
 *   Readymade database: In the other storage engines, the conformance resources from the specification had to be :ref:`imported<conformance_import>` before Firely Server could start. This would take a couple of minutes.
     Because SQLite is file based, we can run the import process for you and provide you with a readymade Administration database.
 
-*   Runs with Facades: perhaps the most important feature. If you build a Firely Server FHIR Facade, the facade will not provide support for hosting conformance resources. 
+*   Runs with Facades: perhaps the most important feature. If you build a Firely Server Facade, the facade will not provide support for hosting conformance resources. 
     With Firely Server Administration on SQLite the facade has its own storage and you can use Firely Server Administration out of the box. This enables e.g. validation against your custom resources (that can be imported from your Simplifier project), subscriptions, and other use cases.
 
 .. _configure_sqlite_data:
 
 Settings for using SQLite for Firely Server Data
----------------------------------------
+------------------------------------------------
 
 *	Changing a setting means overriding it as described in :ref:`configure_change_settings`. 
 
@@ -75,7 +75,7 @@ Settings for using SQLite for Firely Server Data
 .. _configure_sqlite_admin:
 
 Settings for using SQLite for Firely Server Administration
--------------------------------------------------
+----------------------------------------------------------
 
 *   Set the ``SqlDbOptions`` under ``Administration`` for the Administration database similar to those above:
     ::

firelyserver/configuration/environment_variables.rst

@@ -6,7 +6,7 @@
 .. _configure_envvar:
 
 Firely Server settings with Environment Variables
-========================================
+=================================================
 
 .. _configure_envvar_appsettings:
 

firelyserver/deployment/azureWebApp.rst

@@ -1,7 +1,7 @@
 .. _azure_webapp:
 
 Firely Server deployment on Azure Web App Service
-========================================
+=================================================
 
 In this section we explain how you can deploy Firely Server in the Azure cloud. 
 

firelyserver/deployment/deployment.rst

@@ -1,7 +1,7 @@
 .. _deployment:
 
 Firely Server deployment options
-=======================
+================================
 
 Firely Server can be deployed as:
 

firelyserver/deployment/docker.rst

@@ -1,8 +1,8 @@
 .. _use_docker:
 
-====================
+=============================
 Using Firely Server on Docker
-====================
+=============================
 
 We have created a Docker image for Firely Server, so you can run the server in any environment that supports Docker. For this section we
 assume you have Docker installed on your system. If you want to install Docker for Windows, please read :ref:`docker_win` for specific
@@ -25,7 +25,7 @@ Before you can run Firely Server, you will need to pull the Docker Firely Server
 .. warning:: If you use Docker, you may want to run multiple instances of Firely Server (e.g. with Kubernetes). Read :ref:`vonk_conformance_instances` for caveats with the Administration endpoint.
 
 Running a Docker Firely Server in SQLite mode
-------------------------------------
+---------------------------------------------
 
 The easiest and the default way to run a Docker Firely Server container is to run Firely Server in SQLite repository mode. Note that this is not the most performant mode - see MongoDB and SQL Server options below for that.
 

firelyserver/deployment/identityprovider.rst

@@ -4,7 +4,7 @@ Set up an Identity Provider
 ===========================
 
 About Identity Providers and Firely Server
----------------------------------
+------------------------------------------
 
 In order to use :ref:`feature_accesscontrol` you need an Identity Provider that can provide OAuth2 JWT Tokens with claims that conform to `SMART on FHIR`_. In a production scenario, you typically already have such a provider. It could be the EHR system, the Active Directory, or a provider set up specifically for let's say a Patient Portal. It is also very well possible that the provider handing the correct claims uses a federated OAuth2 provider to do the authentication.
 

firelyserver/deployment/performance.rst

@@ -1,7 +1,7 @@
 .. _vonk_performance:
 
-Performance of Firely Server FHIR Server
-===============================
+Performance of Firely Server
+========================================
 
 About Performance
 -----------------
@@ -12,7 +12,7 @@ Performance variables
 ---------------------
 
 Firely Server Configuration
-^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Firely Server can be run as self contained FHIR Server or as a Facade on top of an existing system. The performance of a Facade is heavily dependent on the performance of the system it is built on top of. The self contained server can run on different databases. On top of that you can configure a couple of features in the settings that influence the performance. These are the most important configuration variables to take into account:
 
 Repository 
@@ -114,7 +114,7 @@ Available performance figures
 We are in the process of setting up performance tests as part of our Continuous Integration and Deployment. Here we describe how this test is currently set up. Because of the beta phase this is in, the output is not yet complete nor fully reliable. Nevertheless we share the preliminary results to give you a first insight.
 
 Firely Server performance test setup
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 #. Configuration
 

firelyserver/deployment/reverseProxy/iis.rst

@@ -4,9 +4,9 @@
 
 .. _iis:
 
-==================
+===========================
 Deploy Firely Server on IIS
-==================
+===========================
 
 Prerequisites
 -------------

firelyserver/deployment/reverseProxy/nginx.rst

@@ -4,9 +4,9 @@
 
 .. _nginx:
 
-=============================
+======================================
 Deploy Firely Server on Nginx on Linux
-=============================
+======================================
 
 About Nginx
 -----------
@@ -25,7 +25,7 @@ Prerequisites
 #. Install Nginx  :code:`sudo apt-get install nginx`
 
 Start Kestrel Firely Server
--------------------------
+---------------------------
 
 Download the binaries for Firely Server (see :ref:`vonk_getting_started`), open a terminal console and start the Firely Server process by using:
 dotnet Vonk.Server.dll.

firelyserver/deployment/reverseProxy/reverseProxy.rst

@@ -1,8 +1,8 @@
 .. _deploy_reverseProxy:
 
-==============================
+=======================================
 Deploy Firely Server on a reverse proxy
-==============================
+=======================================
 
 Why
 ---

firelyserver/deployment/yellowbutton.rst

@@ -1,15 +1,15 @@
 .. _yellowbutton:
 
-================================================
+=========================================================
 Yellow Button - Firely Server for your Simplifier project
-================================================
+=========================================================
 
-Yellow Button is an easy way to run an instance of Firely Server FHIR Server that is aware of all the profiles, search parameters and other (conformance) resources that are part of a Simplifier project. That can be a project of your own or for instance a project with national profiles.
+Yellow Button is an easy way to run an instance of Firely Server that is aware of all the profiles, search parameters and other (conformance) resources that are part of a Simplifier project. That can be a project of your own or for instance a project with national profiles.
 
 Prerequisites
 -------------
 
-Yellow Button provides you with a PowerShell script to start Firely Server FHIR Server in a Docker container. This means that you will need:
+Yellow Button provides you with a PowerShell script to start Firely Server in a Docker container. This means that you will need:
 
 - Windows OS that can run Docker for Windows
 - Docker for Windows
@@ -54,7 +54,7 @@ Powershell will probably still ask for confirmation before running the script. T
 
 .. image:: ../images/yellow_Powershell_SecurityWarning.png
 
-The script will pull images from the Docker hub as necessary, and then start the Firely Server FHIR Server. Firely Server will load all the conformance resources from the core specification, and from your project into its Administration database. You can read :ref:`conformance` if you want to know more about this. Since this may take some time, you will see a progress bar. Firely Server is allowed to finish this task in at most 6 minutes.
+The script will pull images from the Docker hub as necessary, and then start the Firely Server. Firely Server will load all the conformance resources from the core specification, and from your project into its Administration database. You can read :ref:`conformance` if you want to know more about this. Since this may take some time, you will see a progress bar. Firely Server is allowed to finish this task in at most 6 minutes.
 
 .. image:: ../images/yellow_ScriptProgress.png
   :align: left
@@ -128,7 +128,7 @@ If the project you created the server off of contains any *example* resources, t
 Your project in progress
 ------------------------
 
-You created the Firely Server FHIR Server off of a Simplifier project. That project may evolve. Either because it is your own and you improve your profiles, or because the maintainer of the project applies changes. Firely Server is connected to the Simplifier project. This means that you can update the conformance resource in Firely Server from the contents of the project by:
+You created the Firely Server off of a Simplifier project. That project may evolve. Either because it is your own and you improve your profiles, or because the maintainer of the project applies changes. Firely Server is connected to the Simplifier project. This means that you can update the conformance resource in Firely Server from the contents of the project by:
 
 - invoking importResources::
 
@@ -142,7 +142,7 @@ You created the Firely Server FHIR Server off of a Simplifier project. That proj
 Further steps
 -------------
 
-Yellow Button is an easy way to get started with Firely Server FHIR Server. But there are many other :ref:`deployment options <deployment>` for the server. Besides that you can add your own plugins with :ref:`vonk_plugins`, or build a :ref:`vonk_facade` with Firely Server. 
+Yellow Button is an easy way to get started with Firely Server. But there are many other :ref:`deployment options <deployment>` for the server. Besides that you can add your own plugins with :ref:`vonk_plugins`, or build a :ref:`vonk_facade` with Firely Server. 
 
 .. _Simplifier: https://simplifier.net
 

firelyserver/facade/databasemodel.rst

@@ -101,7 +101,7 @@ Create your first mapping
                                            source.PatientNumber));
      // etc.
 
-  For more examples of filling the elements, see the FHIR API documentation: :ref:`FHIR-model`.
+  For more examples of filling the elements, see the FHIR API documentation: `FHIR-model <https://docs.fire.ly/projects/Firely-NET-SDK/model.html>`_.
 
 5. Then return the created Patient object as an IResource with ``patient.ToIResource()``.
 

firelyserver/facade/enablechange_1.rst

@@ -183,7 +183,7 @@ to throw an error.
 .. _config_change_repo:
 
 3. Configure the service and Firely Server
-----------------------------------------
+------------------------------------------
 
 Just like with the search repository, you will need to add your change repository as service to the pipeline.
 Also, you will need to indicate support for the CRUD interactions in your Firely Server appsettings.

firelyserver/facade/enablesearch_1.rst

@@ -11,7 +11,7 @@ The next paragraphs will walk you through these steps.
 1. Create a query
 -----------------
 
-Firely Server FHIR Facade is meant to be used across all kinds of database paradigms and schemas. Or even against underlying web services or stored procedures.
+Firely Server Facade is meant to be used across all kinds of database paradigms and schemas. Or even against underlying web services or stored procedures.
 This means Firely Server cannot prescribe the way your query should be expressed. After all, it could be an http call to a webservice, or a json command to MongoDB.
 
 In our case we will build a LINQ query against our ViSi model, that is translated by Entity Framework to a SQL query.
@@ -51,6 +51,31 @@ The DbContext is used for retrieving DbSets for related entities, as we will see
     public PatientQueryFactory(DbContext onContext) : base("Patient", onContext) { }
 
 
+.. _facade_fhir_version:
+
+Deciding on a FHIR version
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You need to explicitly tell Firely Server for which FHIR version(s) you wish to return resources. If you don't override ``EntryInformationModel``, any search will fail with a ``501 Not Implemented``. The following override will allow searches for any possible FHIR version to be handled by your facade::
+       
+    public override PatientQuery EntryInformationModel(string informationModel)
+    {
+        return default(PatientQuery);
+    }
+
+If you wish to implement search only for a single FHIR version or for a limited set of versions you can override the method like this::
+
+    public override PatientQuery EntryInformationModel(string informationModel)
+    {
+        if (informationModel == VonkConstants.Model.FhirR4)
+        {
+            return default(PatientQuery);
+        }
+        
+        throw new NotImplementedException($"FHIR version {informationModel} is not supported");        
+    }
+	
+
 Handling the search request
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Each of the searchparameters in the search request triggers a call to the ``Filter`` method. This method takes a

firelyserver/facade/enablesearch_2.rst

@@ -86,13 +86,6 @@ The gist of the implementation is to switch the querying based on the ResourceTy
          return new SearchResult(patientResources, query.GetPageSize(), count);
      }
 
-* Please note that R4 calls can lead to NotImplementedExceptions, as some older Facades may implement STU3 only. Therefore, when using FHIR version R4 or higher, you will need to override the EntryInformationModel to suppress the NotImplementedException. This can be done by either adding a version filter to your query or, if you only do R4 and you don't want to use a filter, by implementing the following override::
-       
-    public override PatientQuery EntryInformationModel(string informationModel)
-    {
-        return default(PatientQuery);
-    }
-
 What happens behind the scenes is that the QueryBuilderContext creates a QueryBuilder that analyzes all the arguments and options, and translates that into calls into your PatientQueryFactory.
 This pattern offers maximum assistance in processing the search, but also gives you full control over the raw arguments in case you need that for anything.
 Any argument that is reported as in Error, or not handled will automatically show up in the OperationOutcome of the Firely Server response.