Skip to content

DSF Middleware Setup

Jump to bottom
Mathias Rühle edited this page Sep 16, 2024 · 43 revisions

DSF Middleware Setup

The DSF middleware connects your site to the central platform. This allows it to receive feasibility query requests as well as reporting back any results of these queries.

Prerequisites

Make sure to have a working DSF installation by following the DSF Installation Guide.

Step 1 - Adjust FHIR configuration

Register your organisation in the Allow List Management Portal and assign it as member to the parent organization medizininformatik-initiative.de. After approval upload the new allow list to your DSF FHIR instance.

Step 2 - Install feasibility plugin

Download the latest release version of the feasibility DSF plugin (version 1.0.0.7) and mount it to your DSF BPE instance.

Important

Make sure to mount the plugin to /opt/bpe/process/ within the container.

Warning

Remove any old version of the plugin. Be aware that versions before 1.0.0.6 have a different filename (feasibility-dsf-process-[VERSION].jar).

Step 3 - Reconfigure DSF BPE installation

Add the following additional environment variables to your DSF BPE instance as you see fit, according to your infrastructure setup.

Important

The feasibility DSF plugin gets configured using environment variables. All environment variables within this step require you to add the prefix DE_MEDIZININFORMATIK_INITIATIVE_FEASIBILITY_DSF_PROCESS_ to them. It has simply been left out for brevity.

Environment Variable Description
CLIENT_STORE_PROXY_HOST Forward proxy host.
CLIENT_STORE_PROXY_PORT Forward proxy port.
CLIENT_STORE_PROXY_USERNAME Username for a forward proxy if it requires one.
CLIENT_STORE_PROXY_PASSWORD Password for a forward proxy if it requires one.
CLIENT_STORE_AUTH_BEARER_TOKEN Bearer token used for authentication against a client target. Do not prefix this with Bearer !
CLIENT_STORE_AUTH_BASIC_USERNAME Username for basic authentication against a FHIR server client target.
CLIENT_STORE_AUTH_BASIC_PASSWORD Password for basic authentication against a FHIR server client target.
CLIENT_STORE_AUTH_OAUTH_ISSUER_URL URL of OpenID Connect provider (e.g. https://auth.example.com/realms/foo/)
CLIENT_STORE_AUTH_OAUTH_CLIENT_ID Client ID for authentication against a OpenID Connect provider to gain access token for FHIR server client target.
CLIENT_STORE_AUTH_OAUTH_CLIENT_PASSWORD Client Password for authentication against a OpenID Connect provider to gain access token for FHIR server client target.
CLIENT_STORE_AUTH_OAUTH_PROXY_HOST Forward proxy host for connecting to OpenID Connect provider.
CLIENT_STORE_AUTH_OAUTH_PROXY_PORT Forward proxy port for connecting to OpenID Connect provider.
CLIENT_STORE_AUTH_OAUTH_PROXY_USERNAME Username for a forward proxy for connecting to OpenID Connect provider if it requires one.
CLIENT_STORE_AUTH_OAUTH_PROXY_PASSWORD Password for a forward proxy for connecting to OpenID Connect provider if it requires one.
CLIENT_STORE_TIMEOUT_CONNECT Timeout for establishing a connection to a FHIR server client target in ms.
CLIENT_STORE_TIMEOUT_CONNECT_REQUEST Timeout for requesting a connection to a FHIR server client target in ms.
CLIENT_STORE_TIMEOUT_SOCKET Timeout for blocking a read / write network operation to a FHIR server without failing in ms.
CLIENT_STORE_KEY_STORE_PATH Path to a Java key store used for authenticating against a FHIR server or proxy using a client certificate.
CLIENT_STORE_KEY_STORE_PASSWORD Password for opening the Java key store used for authenticating against a FHIR server or proxy.
EVALUATION_OBFUSCATE Defines whether the feasibility evaluation result shall be obfuscated.
EVALUATION_OBFUSCATION_SENSITIVITY Sets the sensitivity of the Laplace distribution function used for obfuscating the result.
EVALUATION_OBFUSCATION_EPSILON Sets the epsilon value of the Laplace distribution function used for obfuscating the result.
RATE_LIMIT_COUNT Sets the hard limit for the maximum allowed number of requests during the configured rate limit interval after no further requests will be processed.
RATE_LIMIT_INTERVAL_DURATION Sets the size of the time window used for calculating the request rate. The value is required to be given in the ISO 8601 format (e.g. "PT1H30M10S").

Tip

Check out the official plugin documentation for more information on these settings and their default values.

The plugin consists of 2 seperate BPE processes where only one of them needs to be running. Which process is needed depends on the role of the DSF organization in the Medizininformatik-Initiative. The BPE provides the option to exclude processes from being actively deployed by specifying the process identifier and version (first 2 version numbers of the feasibility plugin, e.q. 1.0 for plugin version 1.0.0.5) as value of the BPE environment variable DEV_DSF_BPE_PROCESS_EXCLUDED. Below are the exclusions listed by organization role:

  • DIC:
       DEV_DSF_BPE_PROCESS_EXCLUDED: |
         medizininformatik-initiativede_feasibilityRequest|1.0
  • HRP:
       DEV_DSF_BPE_PROCESS_EXCLUDED: |
         medizininformatik-initiativede_feasibilityExecute|1.0

Note

Additional processes may be listed in your process exclude config.

Connect to a FHIR server serving a self-signed certificate

Important

This only applies to setups that do not use the FLARE component!

Connecting to a FHIR server serving a self-signed certificate requires an adjusted Java trust store. The store has to contain the certificate chain for said self-signed certificate.

  1. Create a Java trust store in PKCS12 format containing the certificate chain. A tool for doing so can be found in this repository in util/certs.
  2. Mount the trust store to your DSF BPE instance (depending on your infrastructure setup)
  3. Add the following environment variables to your DSF BPE instance to configure usage of the trust store.
Environment Variable Value
CLIENT_STORE_TRUST_STORE_PATH Path to the mounted trust store within the DSF BPE instance.
CLIENT_STORE_TRUST_STORE_PASSWORD Password for the mounted trust store within the DSF BPE instance.

Connect to FHIR server with CQL support

Using a FHIR server that does support CQL allows for direct communication with it using the feasibility DSF plugin.

Add the following environment variables to your DSF BPE instance to bind the feasibility process directly to your FHIR server.

Environment Variable Value
CLIENT_STORE_BASE_URL Base URL to the FHIR server.
EVALUATION_STRATEGY cql

Connect to FHIR server without CQL support

Using a FHIR server that does not support CQL requires the usage of the FLARE component as a mediator. It will take care of translating feasibility queries into a FHIR search format. This format allows to communicate with FHIR servers that do not support CQL.

  1. Consult the official documentation on how to configure the FLARE component.

  2. Add the following environment variables to your DSF BPE instance to bind the feasibility process to your FLARE instance.

Optional Environment Variable Value
CLIENT_FLARE_BASE_URL Base URL to the FLARE component.
* CLIENT_FLARE_TIMEOUT_CONNECT Connection timeout in ms.
EVALUATION_STRATEGY structured-query

Step 4 - Start / Restart DSF instance

Simply restart your DSF instance according to your infrastructure setup.

If you chose to connect to a FHIR server through FLARE you may need to start / restart this component as well.

Clone this wiki locally