MII Feasibility Backend

Configuration Base

Running the DIRECT Path

The DIRECT path can be run either with FLARE or with a CQL compatible server, not with both. Result counts from the direct path can be obfuscated for privacy reasons. The current implementation handles obfuscation by adding or subtracting a random number <=5.

This is irrelevant if _BROKER_CLIENT_DIRECTENABLED is set to false.

Running the DIRECT Path with Local FLARE

In order to run the backend using the DIRECT broker path with FLARE, the _FLARE_WEBSERVICE_BASEURL environment variable needs to be set to a running instance of a FLARE instance the backend is allowed to connect to.

Running the DIRECT Path with Local CQL Server

In order to run the backend using the DIRECT broker path with CQL, the _CQL_SERVER_BASEURL environment variable needs to be set to a running instance of a CQL compatible FHIR server.

Running the AKTIN Broker Path

In order to run the backend using the AKTIN broker path, the following environment variables need to be set:

When using API-key authentication, please make sure that the broker server has a corresponding API-key entry with OU=admin contained in the DN-string.

Running the DSF Path

In order to run the backend using the DSF path, the following environment variables need to be set:

Privacy and Obfuscation

In order to prevent potentially malicious attempts to obtain critical patient data, several countermeasures have been implemented. Users are restricted to creating a certain amount of queries per timeframe. Permanently pushing this limit will get a user blacklisted and needs manual intervention if the user shall be de-listed again. Moreover, retrieving detailed results for queries (including a breakdown by (obfuscated) site names) is also limited.

If the number of responding sites is below the configured threshold, only the total number of results will be provided. If the number of total results is below threshold, no result will be provided.

Support for self-signed certificates

The feasibility backend supports the use of self-signed certificates from your own CAs. On each startup, the feasibility backend will search through the folder /app/certs inside the container, add all found CA *.pem files to a java truststore and start the application with this truststore.

Using docker-compose, mount a folder from your host (e.g.: ./certs) to the /app/certs folder, add your *.pem files (one for each CA you would like to support) to the folder and ensure that they have the .pem extension.

Setting up Development

In order to run this project the following steps need to be followed:

1. Add GitHub package repositories
2. Build the project
3. Setup database

Adding GitHub Package Repositories

This project uses dependencies (HiGHmed DSF and sq2cql) which are not hosted on maven central but on GitHub.

In order to download artifacts from GitHub package repositories, you need to add your GitHub login credentials to your central maven config file.

For more information take a look at this GitHub documentation about authentication.

In order to install the packages using maven in your own projects you need a personal GitHub access token. This GitHub documentation shows you how to generate one.

After that, add the following <server> configurations to the <servers> section in your local .m2/settings.xml. Replace USERNAME with your GitHub username and TOKEN with the previously generated personal GitHub access token. The token needs at least the scope read:packages.

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <servers>
    <server>
      <id>codex</id>
      <username>USERNAME</username>
      <password>TOKEN</password>
    </server>
    <server>
      <id>highmed</id>
      <username>USERNAME</username>
      <password>TOKEN</password>
    </server>
  </servers>
</settings>

Building the Project

Since Release 4.0.0, this project is packaged without ontology files. They have to be downloaded first from the corresponding GitHub repository. This can be done by enabling the maven profile "download-ontology" when building the project. This wipes any existing ontology files in your project. So if you are working with your own ontology files, do not execute this.

Navigate to the root of this repository and execute mvn install -Pdownload-ontology (or omit the -Pdownload-ontology part when working with your own).

You can change your run configuration in intellij to execute maven goals before running. So if you want to always just grab the latest ontology from GitHub, you can Edit your run configuration, go to modify options and select add before launch task and run maven goal with clean package -Pdownload-ontology. This is however not necessary, and your mileage may vary in other IDEs if they offer such an option.

Be aware that Step 1 "Add GitHub package repositories" needs to be executed before.

Setting up the Database

The project requires a PSQL database. The easiest way to set this up is to use the docker-compose file provided:

docker-compose up -d

Note that this starts an empty psql database as well as a containerized version of the backend. The containerized version of the backend will then connect to the backend database. One can then connect to the same database when starting the backend in an IDE.

Working with the Backend

This backend provides a rest webservice which connects the MII feasibility gui and the corresponding middlewares.

To send a query to the backend, use the following example query:

curl --location --request POST 'http://localhost:8090/api/v3/query' \
--header 'Content-Type: application/json' \
--data-raw '{
    "version": "http://to_be_decided.com/draft-1/schema#",
    "display": "",
    "inclusionCriteria": [
      [
        {
          "termCode": {
            "code": "29463-7",
            "system": "http://loinc.org",
            "version": "v1",
            "display": "Body Weight"
        },
        "valueFilter": {
            "type": "quantity-comparator",
            "unit": {
              "code": "kg",
              "display": "kilogram"
            },
            "comparator": "gt",
            "value": 90
          }
        }
      ]
    ]
  }'

another example

curl --location --request POST 'http://localhost:8090/api/v3/query' \
--header 'Content-Type: application/json' \
--data-raw '{
    "version": "http://to_be_decided.com/draft-1/schema#",
    "display": "xxx",
    "inclusionCriteria": [
      [
        {
          "termCode": {
            "code": "J98.4",
            "system": "urn:oid:1.2.276.0.76.5.409",
            "version": "v1",
            "display": "xxx"
        }

        }
      ]
    ]
  }'

The response to this call will return a location header, which links to the endpoint where the result for the query can be collected with one of the available sub-paths. For a full description of the api, please refer to the swagger documentation (either in static/v3/api-docs/swagger.yaml or at http://localhost:8090/swagger-ui/index.html when running)

Starting with Docker

Creating the Docker Image

mvn install
docker build -t feasibility-gui-backend .

Starting the Backend and the Database

docker-compose up -d

Note: If you need the database to run using another port than 5432 then set the corresponding environment variable like:

FEASIBILITY_DATABASE_PORT=<your-desired-port> docker-compose up -d

Testing if the Container is Running Properly

GET http://localhost:8090/api/v3/terminology/root-entries

Should reply with status 200 and a JSON object

Query Result Log Encryption

Generating a Public/Private Key Pair

According to BSI TR-02102-1, we have to use RSA keys with a minimum size of 3000 bit. We will use 3072 because that is the next possible value.

Generate the private key:

openssl genrsa -out key.pem 3072

Extract the public key from the private key in Base64-encoded DER format to put into QUERYRESULT_PUBLIC_KEY:

openssl rsa -in key.pem -outform DER -pubout | base64

If you like to use the Decryptor class, you have to convert the private key into the PKCS#8 format:

openssl pkcs8 -topk8 -inform PEM -outform DER -in key.pem -nocrypt | base64

You can use the following Java code to create a PrivateKey class for use with Decryptor:

var keyFactory = KeyFactory.getInstance("RSA");
var privateKey = keyFactory.generatePrivate(new PKCS8EncodedKeySpec(Base64.getDecoder().decode("...")));