Merge pull request #161 from FirelyTeam/vonk/patient-everything

Added patient $everything and included export resources
FirelyTeam · Apr 13, 2021 · b49d45a · b49d45a
2 parents 6a8acba + 35d2361
commit b49d45a
Show file tree

Hide file tree

Showing 11 changed files with 369 additions and 164 deletions.
diff --git a/firelyserver/features/bulkdataexport.rst b/firelyserver/features/bulkdataexport.rst
@@ -53,13 +53,16 @@ BDE introduces two new parts to the appsettings, namely TaskFileManagement and B
       "StoragePath": "./taskfiles"
     },
   "BulkDataExport": {
-      "RepeatPeriod" : 60000 //ms
+      "RepeatPeriod" : 60000, //ms
+      "AdditionalResources": [ "Organization", "Location", "Substance", "Device", "BodyStructure", "Medication", "Coverage" ] 
     },
     
 In StoragePath you can configure the folder where the exported files will be saved to. Make sure the server has write access to this folder.
 
 In RepeatPeriod you can configure the polling interval (in milliseconds) for checking the Task queue for a new export task.
 
+A patient-based or group-based Bulk Data Export returns resources based on the Patient compartment definition (https://www.hl7.org/fhir/compartmentdefinition-patient.html). These resources may reference resources outside the compartment as well, such as a Practitioner who is the performer of a Procedure. Using the `AdditionalResources`-setting, you can determine which types of referenced resources are exported in addition to the compartment resources.
+
 $export
 -------
 

diff --git a/firelyserver/features/conformanceresources.rst b/firelyserver/features/conformanceresources.rst
@@ -1,7 +1,7 @@
 .. _conformance:
 
-Controlling the Conformance Resources
-=====================================
+Conformance Resources
+=====================
 
 Firely Server uses `Conformance Resources <http://www.hl7.org/implement/standards/fhir/conformance-module.html>`_ along with some `Terminology Resources <http://www.hl7.org/implement/standards/fhir/terminology-module.html>`_ for various operations:
 

diff --git a/firelyserver/features/customsearchparameters.rst b/firelyserver/features/customsearchparameters.rst
@@ -5,8 +5,8 @@
 
 .. _feature_customsp:
 
-Using Custom Search Parameters
-==============================
+Custom Search Parameters
+========================
 
 .. _feature_customsp_configure:
 

diff --git a/firelyserver/features/features.rst b/firelyserver/features/features.rst
@@ -11,10 +11,10 @@ Firely Server offers many features as defined in the FHIR Specification and beyo
 
    restful_api
    bulkdataexport
+   patienteverything
    customoperations
    customresources
    terminology
-   terminologyintegration
    prevalidation
    customsearchparameters
    conformanceresources

diff --git a/firelyserver/features/multiversion.rst b/firelyserver/features/multiversion.rst
@@ -1,7 +1,7 @@
 .. _feature_multiversion:
 
-Running multiple versions of FHIR
-=================================
+Multiple versions of FHIR
+=========================
 
 Since version 3.0.0 Firely Server can run multiple versions of FHIR side-by-side in the same server. This page explains how this works and what the consequences are.
 

diff --git a/firelyserver/features/patienteverything.rst b/firelyserver/features/patienteverything.rst
@@ -0,0 +1,59 @@
+.. _feature_patienteverything:
+
+Patient $everything
+===================
+
+Description
+-----------
+
+This plugin implements the Patient $everything operation, as described in https://www.hl7.org/fhir/operation-patient-everything.html. This operation returns all resources associated with a single patient. The resources returned are determined by the Patient compartment, defined in https://www.hl7.org/fhir/compartmentdefinition-patient.html. Currently, the functionality is only available if you use SQL server for your data.
+
+::
+
+   GET <base-url>/Patient/<patient-id>/$everything
+   Accept: <any supported FHIR media type>
+   
+Optional parameters:
+
+* _since: Get only resources changed since this moment
+* _type: Limit the returned resource types to only the types in this list
+
+Please note that other defined operation parameters have not been implemented (yet).
+
+So if you would want to fetch only Patient 1 and their Observations, changed since the 1st of January, 2021 in FHIR JSON format, you would use:
+
+::
+
+   GET <base-url>/Patient/1/$everything?_type=Patient,Observation&_since=2021-01-01
+   Accept: application/fhir+json
+   
+Configuration
+-------------
+Many resources in the Patient compartment reference resources outside the compartment. For example: An Observation might have a performer which is a Practitioner. As Practitioner itself is not in the Patient compartment, the resource would normally not be returned. But using a setting you can control which additional resource types are returned if they are referenced by any of the resources you requested.
+
+.. code-block:: JavaScript
+
+   "PatientEverythingOperation": {
+      "AdditionalResources": [ "Organization", "Location", "Substance", "Device", "Medication" ] 
+   }
+   
+This is the default value for the setting. As you can see, Practitioner is not included by default out of privacy considerations but you can change that by overriding the setting. To include the plugin in your pipeline, add the following extra Include:
+
+.. code-block:: JavaScript
+
+   "PipelineOptions": {
+      "Branches": [
+         {
+            "Path": "/",
+            "Include": [
+               ...
+               "Vonk.Plugin.PatientEverything"
+            ]
+         },
+         ...
+      ]
+   }   
+
+License
+-------
+The Patient $everything operation is licensed. To use it, you may need to renew your license.
diff --git a/firelyserver/features/preload.rst b/firelyserver/features/preload.rst
@@ -4,8 +4,8 @@
 
 .. _feature_preload:
 
-Preloading a set of resources
-=============================
+Preloading resources
+====================
 
 .. caution:: Preload in Firely Server (Vonk) 3.0.0 is only available for STU3.
 

diff --git a/firelyserver/features/terminology.rst b/firelyserver/features/terminology.rst
@@ -1,31 +1,28 @@
 .. _feature_terminology:
 
-Terminology
-===========
+Terminology services
+====================
 
-Firely Server provides limited support for these Terminology operations:
+Firely Server provides support for Terminology operations and validation against terminologies. This is done through a local implementation based on the Administration database ('Local Terminology Service') and - if configured - extended with external FHIR Terminology Servers ('Remote Terminology Services'). The configuration allows you to set preferred services for each CodeSystem and ValueSet. Firely Server will then transparently select and query either the Local or one of the Remote Terminology Services.
 
-* $validate-code
-* $expand
-* $lookup
-* $compose
+Of the operations listed below the following can be supported by the Local Terminology Service: $validate-code, $expand, $lookup, $find-matches. Note that it only supports simple ValueSets and CodeSystems like the ones part of the FHIR specification. It cannot support complex terminologies like LOINC or SNOMED-CT.
 
-These operations are currently implemented on the :ref:`Administration API<administration_api>` and therefore only available through the administration endpoint on ``<firely-server-endpoint>/administration``.
+The terminology operations can be invoked for different FHIR versions as specified in :ref:`feature_multiversion`.
 
-Refer to :ref:`conformance` on how to provide CodeSystem and ValueSet resources to the Administration API.
+.. _feature_terminologyintegration:
 
-.. note::
-   This is a first attempt on supporting Terminology operations. We welcome feedback on how you would like to use them. Contact us at server@fire.ly.
+Terminology Integration
+^^^^^^^^^^^^^^^^^^^^^^^
 
-.. note::
-   This implementation does not support complex terminologies like Snomed CT or LOINC. If you need that: Starting with Firely Server (Vonk) 3.5.0 we provide more elaborate terminology support by integrating with a full Terminology Server, see :ref:`Terminology Integration docs<feature_terminologyintegration>`.
+In earlier versions of Firely Server, local terminology services were separately configured from so-called Terminology Integration. These are now merged.
 
-.. _terminology_validate-code:
+Operations
+----------
 
 ValueSet $validate-code
 -----------------------
 
-:definition: http://www.hl7.org/implement/standards/fhir/valueset-operations.html#validate-code
+:definition: http://www.hl7.org/implement/standards/fhir/valueset-operation-validate-code.html
 :notes: 
    * Available on the type level ``<firely-server-endpoint>/administration/ValueSet/$validate-code`` and the instance level ``<firely-server-endpoint>/administration/ValueSet/<id>/$validate-code``.
    * Only the parameters url, valueSet, valueSetVersion, code, system, display, coding, codeableConcept, abstract are supported.
@@ -35,7 +32,7 @@ ValueSet $validate-code
 ValueSet $expand
 ----------------
 
-:definition: http://www.hl7.org/implement/standards/fhir/valueset-operations.html#expand
+:definition: http://www.hl7.org/implement/standards/fhir/valueset-operation-expand.html
 :notes:
    * Available on the type level ``<firely-server-endpoint>/administration/ValueSet/$expand`` and the instance level ``<firely-server-endpoint>/administration/ValueSet/<id>/$expand``.
    * Only the parameters url, valueSet, valueSetVersion and includeDesignations are supported.
@@ -45,20 +42,180 @@ ValueSet $expand
 CodeSystem $lookup
 ------------------
 
-:definition: http://www.hl7.org/implement/standards/fhir/codesystem-operations.html#lookup
+:definition: http://www.hl7.org/implement/standards/fhir/codesystem-operation-lookup.html
 :notes:
    * Available on the type level ``<firely-server-endpoint>/administration/CodeSystem/$lookup``.
    * Only the parameters code, system, version, coding and date are supported. 
    * Code & system combination takes priority over the coding parameter.
    * Both ``GET`` and ``POST`` interactions are available. 
 
-CodeSystem $compose
--------------------
+CodeSystem $find-matches / $compose
+-----------------------------------
 
-:definition: http://www.hl7.org/implement/standards/fhir/codesystem-operations.html#compose
+:definition: http://www.hl7.org/implement/standards/fhir/codesystem-operation-find-matches.html
 :notes:
-   * Available on the type level ``<firely-server-endpoint>/administration/CodeSystem/$compose`` and the instance level ``<firely-server-endpoint>/administration/CodeSystem/<id>/$compose``.
+   * Available on the type level ``<firely-server-endpoint>/administration/CodeSystem/$find-matches`` and the instance level ``<firely-server-endpoint>/administration/CodeSystem/<id>/$find-matches``.
    * Only the parameters system, exact, version, property.code and property.value are supported.
    * The url and valueSetVersion input parameters are only taken into consideration if no valueSet resource was provided in the body. So the valueSet in the body takes priority.
    * Both ``GET`` and ``POST`` interactions are available. 
+   * $find-matches was named $compose in FHIR STU3. The operation is supported with both names.
+
 
+CodeSystem $subsumes
+--------------------
+
+:definition: http://www.hl7.org/implement/standards/fhir/codesystem-operation-subsumes.html
+:notes:
+   * Available on the type level ``<firely-server-endpoint>/administration/CodeSystem/$subsumes``.
+   * Only the parameters codeA, codeB, system, and version are supported.
+   * The system input parameters is only taken into when called on the type level.
+   * Both ``GET`` and ``POST`` interactions are available. 
+
+CodeSystem $closure
+--------------------
+
+:definition: http://www.hl7.org/implement/standards/fhir/codesystem-operation-closure.html
+:notes:
+   * Available on the system level ``<firely-server-endpoint>/administration/$closure``.
+   * This operation is passed on to a Remote Terminology Service supporting it. It supports any parameters that the Remote service supports. 
+   * Only ``POST`` interactions are available. 
+
+ConceptMap $translate
+---------------------
+
+:definition: http://www.hl7.org/implement/standards/fhir/conceptmap-operation-translate.html
+:notes:
+   * Available on the instance level ``<firely-server-endpoint>/administration/ConceptMap/[id]/$translate`` and the type level ``<firely-server-endpoint>/administration/ConceptMap/$translate``.
+   * Only the parameters url, conceptMap (on POST), conceptMapVersion, code, system, version, source, target, targetsystem and reverse are supported.
+   * Both ``GET`` and ``POST`` interactions are available. 
+
+
+Configuration
+-------------
+
+Pipeline
+^^^^^^^^
+
+Make sure to add the ``Vonk.Plugins.Terminology`` plugin to the PipelineOptions in appsettings in order to make use of the ``TerminologyIntegration`` plugin.
+
+.. code-block:: JavaScript
+
+    "PipelineOptions": {
+        "PluginDirectory": "./plugins",
+        "Branches": [
+          {
+            "Path": "/",
+            "Include": [..]
+          },
+          {
+          "Path": "/administration",
+          "Include": [
+            "Vonk.Core",
+              "Vonk.Fhir.R3",
+              "Vonk.Fhir.R4",
+              "Vonk.Administration",
+              ...
+              "Vonk.Plugins.Terminology"
+            ],
+            "Exclude": [
+              "Vonk.Subscriptions.Administration"
+            ]
+          }, ...etc...
+
+          
+To include or exclude individual operations in the pipeline, see the available plugins under :ref:`vonk_plugins_terminology`.
+
+Also make sure that the terminology operations are allowed at all in the ``SupportedInteractions`` section::
+
+   "SupportedInteractions": {
+      "InstanceLevelInteractions": "$validate-code, $expand, $compose, $translate, $subsumes",
+      "TypeLevelInteractions": "$validate-code, $expand, $lookup, $compose, $translate, $subsumes",
+      "WholeSystemInteractions": "$closure"
+   },
+
+Lastly, operation on the administration endpoint can be limited to specific IP addresses::
+
+   "Administration": {
+      "Security": {
+         "AllowedNetworks": [ "127.0.0.1", "::1" ], // i.e.: ["127.0.0.1", "::1" (ipv6 localhost), "10.1.50.0/24", "10.5.3.0/24", "31.161.91.98"]
+         "OperationsToBeSecured": [ "$validate-code", "$expand", "$compose", "$translate", "$subsumes", "$lookup", "$closure" ]
+      }
+   },
+
+
+Options
+^^^^^^^
+
+You can enable the integration with one or more external terminology services by setting the required options in the appsettings file. There is a block for the Local Terminology Service and one for each Remote Terminology Service.
+
+For each terminology service you can set the following options:
+
+    :Order: The order of the terminology service, or the priority. If multiple Terminology services could be used for a request, Firely Server will use the priority to select a service. Terminology services are arranged in a ascending order: so 1 will be selected over 2.
+    :PreferredSystem: If a request is directed at a specific code system, Firely Server will choose this terminology server over other available services. A system matches one of the preferred systems if the system starts with the preferred system. So ``http://loinc.org`` will match any CodeSystem or ValueSet with a canonical that starts with that url.  
+    :SupportedInteractions: The operations supported by the terminology service. Firely Server will only select this service if the operation is in this list. Valid values::
+
+       "ValueSetValidateCode"
+       "CodeSystemValidateCode"
+       "Expand"
+       "FindMatches" / "Compose"
+       "Lookup"
+       "Translate"
+       "Subsumes"
+       "Closure"
+
+    :SupportedInformationModels: The FHIR versions supported by the terminology service. Valid values::
+
+       "Fhir3.0" 
+       "Fhir4.0" 
+       "Fhir5.0"
+
+    :Endpoint: The endpoint url where Firely Server can redirect the requests to.
+    :Username: If the terminology service uses Basic Authentication, you can set the required username here. 
+    :Password: If the terminology service uses Basic Authentication, you can set the required password here.
+
+Notes:
+
+* The Endpoint, Username and Password settings are not valid for the Local Terminology Server, just for the Remote services.
+* If a Remote Terminology Service has different endpoints for different FHIR versions, configure each endpoint separately.
+* The ``SupportedInformationModels`` cannot be broader than the corresponding ``Fhir.Rx`` plugins configured in the PipelineOptions.
+
+A sample Terminology section in the appsettings can look like this:
+
+.. code-block:: JavaScript
+
+   "Terminology": {
+      "LocalTerminologyService": {
+         "Order": 10,
+         "PreferredSystems": [ "http://hl7.org/fhir" ],
+         "SupportedInteractions": [ "ValueSetValidateCode", "Expand" ],
+         "SupportedInformationModels": [ "Fhir3.0", "Fhir4.0", "Fhir5.0" ]
+      }, 
+      "RemoteTerminologyServices": [
+      {
+         "Order": 20,
+         "PreferredSystems": [ "http://snomed.info/sct" ],
+         "SupportedInteractions": [ "ValueSetValidateCode", "Expand", "Translate", "Subsumes", "Closure" ],
+         "SupportedInformationModels": [ "Fhir4.0" ],
+         "Endpoint": "https://r4.ontoserver.csiro.au/fhir/",
+         "MediaType": "application/fhir+xml"
+      },
+      {
+         "Order": 30,
+         "PreferredSystems": [ "http://loinc.org" ],
+         "SupportedInteractions": [ "ValueSetValidateCode", "Expand", "Translate" ],
+         "SupportedInformationModels": [ "Fhir3.0", "Fhir4.0" ],
+         "Endpoint": "https://fhir.loinc.org/",
+         "Username": "",
+         "Password": ""
+      }
+      ]
+   },
+
+This means if you execute a terminology operation request, Firely Server will check whether the request is correct, redirect it to the preferred terminology service and finally return the result. 
+
+License
+-------
+
+The Terminology plugin itself is licensed with the license token ``http://fire.ly/vonk/plugins/terminology``.
+
+When you configure Remote Terminology Services it is your responsibility to check whether you are licensed to use those services.