Skip to content
This repository has been archived by the owner on Mar 22, 2024. It is now read-only.

Home

Jump to bottom
Reto Wettstein edited this page Feb 16, 2022 · 29 revisions

Projectathon-6 Data Transfer: Process Description

This repository contains the Data Transfer Process used in the Projectathon-6 to send data from a Data Integration Center (DIC) to a Coordinating Site (COS, also called Data Management Site). The infrastructure and communincation messages on which the process is based can be seen in the following figure. The organizations use the Data Sharing Framework (DSF) for deployment and execution of the process.

Projectathon-6 Data Transfer: Process Figure

The Data Transfer Process in v0.1.0 is composed of 2 different subprocesses:

Send Process

The send process is used at a DIC to prepare and initiate data transmission of a specific projectathon projects result to a COS. This subprocess performs the following steps:

  • Read the project results from a dedicated KDS FHIR store
  • Validate the project results and create a data transfer Bundle
  • Download the public-key from the COS and encrypt the transfer Bundle
  • Provide the encrypted transfer Bundle and the local DSF FHIR server for the COS
  • Automatically delete the encrypted transfer Bundle on the local DSF FHIR server after 2 minutes

Prerequisites

In order to start the send process, the following needs to be known and prepared:

  • DIC identifier of the local organization (dic-identifier)
  • COS identifier which should receive the results (coordinating-site-identifier)
  • Project identifier for which results should be transmitted (project-identifier)
  • A DocumentReference and Binary resource on the KDS FHIR store representing the result to be transmitted
    • An example transaction Bundle to load a result onto a KDS FHIR store for the projects WE-STORM and NT-proBNP can be found here
    • Replace the placeholder <REPLACE-WITH-YOUR-ORGANIZATION-IDENTIFIER> with the dic-identifier
    • Replace the placeholder <REPLACE-WITH-DATE-AND-TIME> with the date and time when the result was created in the form yyyy-MM-dd'T'HH:mm:ssX
    • Replace the placeholder <REPLACE-WITH-BASE64-ENCODED-CSV-FILE> with the base64 encoded CSV result file
    • Check the project-identifier which is already set in the example transaction Bundles

Start Send Process

The send process can be started for the projects WE-STORM and NT-proBNP by sending the Task resources that can be found here to the local DSF FHIR server:

  • Replace the placeholder <REPLACE-WITH-YOUR-ORGANIZATION-IDENTIFIER> with the dic-identifier
  • Replace the placeholder <REPLACE-WITH-DATE-AND-TIME> with the date and time when the result was created in the form yyyy-MM-dd'T'HH:mm:ssX
  • Check the coordinating-site-identifier and the project-identifier which are already set in the example Task resources

Receive Process

The receive process is used at a COS to download and store a result of a specific projectathon projects from a participating DIC. This subprocess performs the following steps:

  • During process deployment: store a public-key Bundle on the local DSF FHIR server (if not already exists) to be used by a DIC for encryption of results to be transmitted
  • Download a transfer Bundle from a DIC DSF FHIR server
  • Decrypt the transfer Bundle
  • Validate the transfer Bundle
  • Store the resources contained in the transfer Bundle on the local KDS FHIR Store

Projectathon-6 Data Transfer: Process Configuration

DIC Mandatory

DE_MEDIZININFORMATIK_INITIATIVE_KDS_FHIR_SERVER_BASE_URL

  • Property: de.medizininformatik.initiative.kds.fhir.server.base.url
  • Required: true
  • Processes: medizininformatik-initiativede_dataSend/, medizininformatik-initiativede_dataReceive/
  • Description: The base address of the KDS FHIR server to read/store FHIR resources
  • Example: http://foo.bar/fhir
  • Recommendation: None
  • Default: not set by default

COS Mandatory

DE_MEDIZININFORMATIK_INITIATIVE_KDS_FHIR_SERVER_BASE_URL

  • Property: de.medizininformatik.initiative.kds.fhir.server.base.url
  • Required: true
  • Processes: medizininformatik-initiativede_dataSend/, medizininformatik-initiativede_dataReceive/
  • Description: The base address of the KDS FHIR server to read/store FHIR resources
  • Example: http://foo.bar/fhir
  • Recommendation: None
  • Default: not set by default

The following keypair could be generated by using the commands:

openssl genrsa -out cos_keypair.pem 4096
openssl rsa -in cos_keypair.pem -pubout -out cos_public_key.pem
openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in cos_keypair.pem -out cos_private_key.pem

DE_MEDIZININFORMATIK_INITIATIVE_COS_PUBLIC_KEY

  • Property: de.medizininformatik.initiative.cos.public.key
  • Required: true
  • Processes: medizininformatik-initiativede_dataReceive/
  • Description: Location of the COS public-key as 4096 Bit RSA PEM encoded file
  • Example: /run/secrets/cos_public_key.pem
  • Recommendation: Use docker secret file to configure
  • Default: not set by default

DE_MEDIZININFORMATIK_INITIATIVE_COS_PRIVATE_KEY

  • Property: de.medizininformatik.initiative.cos.private.key
  • Required: true
  • Processes: medizininformatik-initiativede_dataReceive/
  • Description: Location of the COS private-key as 4096 Bit RSA PEM encoded, not encrypted file
  • Example: /run/secrets/cos_private_key.pem
  • Recommendation: Use docker secret file to configure
  • Default: not set by default

DIC & COS as Needed

DE_MEDIZININFORMATIK_INITIATIVE_KDS_FHIR_SERVER_TRUST_CERTIFICATES

  • Property: de.medizininformatik.initiative.kds.fhir.server.trust.certificates
  • Required: false
  • Processes: medizininformatik-initiativede_dataSend/, medizininformatik-initiativede_dataReceive/
  • Description: PEM encoded file with one or more trusted root certificate to validate the KDS FHIR server certificate when connecting via https
  • Example: /run/secrets/hospital_ca.pem
  • Recommendation: Use docker secret file to configure
  • Default: not set by default

DE_MEDIZININFORMATIK_INITIATIVE_KDS_FHIR_SERVER_BASICAUTH_USERNAME

  • Property: de.medizininformatik.initiative.kds.fhir.server.basicauth.username
  • Required: false
  • Processes: medizininformatik-initiativede_dataSend/, medizininformatik-initiativede_dataReceive/
  • Description: Basic authentication username, set if the server containing the FHIR KDS data requests authentication using basic auth
  • Example: None
  • Recommendation: None
  • Default: not set by default

DE_MEDIZININFORMATIK_INITIATIVE_KDS_FHIR_SERVER_BASICAUTH_PASSWORD or DE_MEDIZININFORMATIK_INITIATIVE_KDS_FHIR_SERVER_BASICAUTH_PASSWORD_FILE

  • Property: de.medizininformatik.initiative.kds.fhir.server.basicauth.password
  • Required: false
  • Processes: medizininformatik-initiativede_dataSend/, medizininformatik-initiativede_dataReceive/
  • Description: Basic authentication password, set if the server containing the FHIR KDS data requests authentication using basic auth
  • Example: /run/secrets/kds_server_basicauth.password
  • Recommendation: Use docker secret file to configure by using DE_MEDIZININFORMATIK_INITIATIVE_KDS_FHIR_SERVER_BASICAUTH_PASSWORD_FILE. Caution! Editors like nano will add a LF (hex 0A) character at the end of the last line. Make sure that the password file does not end with the LF character. For example by starting nano with nano -L file.password. If you want to check that the file does not end with an LF (hex 0A) character, use xxd file.password to look at a hexdump.
  • Default: not set by default

DE_MEDIZININFORMATIK_INITIATIVE_KDS_FHIR_SERVER_BEARER_TOKEN

  • Property: de.medizininformatik.initiative.kds.fhir.server.bearer.token
  • Required: false
  • Processes: medizininformatik-initiativede_dataSend/, medizininformatik-initiativede_dataReceive/
  • Description: Bearer token for authentication, set if the server containing the FHIR KDS data requests authentication using a bearer token, cannot be set using docker secrets
  • Example: None
  • Recommendation: None
  • Default: not set by default

DE_MEDIZININFORMATIK_INITIATIVE_KDS_FHIR_SERVER_CERTIFICATE

  • Property: de.medizininformatik.initiative.kds.fhir.server.certificate
  • Required: false
  • Processes: medizininformatik-initiativede_dataSend/, medizininformatik-initiativede_dataReceive/
  • Description: PEM encoded file with client-certificate, if KDS FHIR server requires mutual TLS authentication
  • Example: /run/secrets/kds_server_client_certificate.pem
  • Recommendation: Use docker secret file to configure
  • Default: not set by default

DE_MEDIZININFORMATIK_INITIATIVE_KDS_FHIR_SERVER_PRIVATE_KEY

  • Property: de.medizininformatik.initiative.kds.fhir.server.private.key
  • Required: false
  • Processes: medizininformatik-initiativede_dataSend/, medizininformatik-initiativede_dataReceive/
  • Description: Private key corresponding to the KDS FHIR server client-certificate as PEM encoded file. Use DE_MEDIZININFORMATIK_INITIATIVE_KDS_FHIR_SERVER_PRIVATE_KEY_PASSWORD or DE_MEDIZININFORMATIK_INITIATIVE_KDS_FHIR_SERVER_PRIVATE_KEY_PASSWORD_FILE if private key is encrypted
  • Example: /run/secrets/kds_server_private_key.pem
  • Recommendation: Use docker secret file to configure
  • Default: not set by default

DE_MEDIZININFORMATIK_INITIATIVE_KDS_FHIR_SERVER_PRIVATE_KEY_PASSWORD or DE_MEDIZININFORMATIK_INITIATIVE_KDS_FHIR_SERVER_PRIVATE_KEY_PASSWORD_FILE

  • Property: de.medizininformatik.initiative.kds.fhir.server.private.key.password
  • Required: false
  • Processes: medizininformatik-initiativede_dataSend/, medizininformatik-initiativede_dataReceive/
  • Description: Password to decrypt the KDS FHIR server client-certificate encrypted private key
  • Example: /run/secrets/kds_server_private_key.pem.password
  • Recommendation: Use docker secret file to configure by using DE_MEDIZININFORMATIK_INITIATIVE_KDS_FHIR_SERVER_PRIVATE_KEY_PASSWORD_FILE. Caution! Editors like nano will add a LF (hex 0A) character at the end of the last line. Make sure that the password file does not end with the LF character. For example by starting nano with nano -L file.password. If you want to check that the file does not end with an LF (hex 0A) character, use xxd file.password to look at a hexdump.
  • Default: not set by default

DE_MEDIZININFORMATIK_INITIATIVE_KDS_FHIR_SERVER_PROXY_URL

  • Property: de.medizininformatik.initiative.kds.fhir.server.proxy.url
  • Required: false
  • Processes: medizininformatik-initiativede_dataSend/, medizininformatik-initiativede_dataReceive/
  • Description: Proxy location, set if the server containing the FHIR KDS data can only be reached through a proxy
  • Example: http://proxy.foo:8080
  • Recommendation: None
  • Default: not set by default

DE_MEDIZININFORMATIK_INITIATIVE_KDS_FHIR_SERVER_PROXY_USERNAME

  • Property: de.medizininformatik.initiative.kds.fhir.server.proxy.username
  • Required: false
  • Processes: medizininformatik-initiativede_dataSend/, medizininformatik-initiativede_dataReceive/
  • Description: Proxy username, set if the server containing the FHIR KDS data can only be reached through a proxy which requests authentication
  • Example: None
  • Recommendation: None
  • Default: not set by default

DE_MEDIZININFORMATIK_INITIATIVE_KDS_FHIR_SERVER_PROXY_PASSWORD or DE_MEDIZININFORMATIK_INITIATIVE_KDS_FHIR_SERVER_PROXY_PASSWORD_FILE

  • Property: de.medizininformatik.initiative.kds.fhir.server.proxy.password
  • Required: false
  • Processes: medizininformatik-initiativede_dataSend/, medizininformatik-initiativede_dataReceive/
  • Description: Proxy password, set if the server containing the FHIR KDS data can only be reached through a proxy which requests authentication
  • Example: None
  • Recommendation: Use docker secret file to configure by using DE_MEDIZININFORMATIK_INITIATIVE_KDS_FHIR_SERVER_PROXY_PASSWORD_FILE. Caution! Editors like nano will add a LF (hex 0A) character at the end of the last line. Make sure that the password file does not end with the LF character. For example by starting nano with nano -L file.password. If you want to check that the file does not end with an LF (hex 0A) character, use xxd file.password to look at a hexdump.
  • Default: not set by default

DE_MEDIZININFORMATIK_INITIATIVE_KDS_FHIR_SERVER_CLIENT

  • Property: de.medizininformatik.initiative.kds.fhir.server.client
  • Required: false
  • Processes: medizininformatik-initiativede_dataSend/, medizininformatik-initiativede_dataReceive/
  • Description: Client implementation used to connect to the KDS FHIR server in order to read/store FHIR resources
  • Example: None
  • Recommendation: Use default value
  • Default: de.medizininformatik_initiative.processes.projectathon.data_transfer.client.fhir.KdsFhirClientImpl

DE_MEDIZININFORMATIK_INITIATIVE_KDS_FHIR_SERVER_CLIENT_VERBOSE

  • Property: de.medizininformatik.initiative.kds.fhir.server.client.verbose
  • Required: false
  • Processes: medizininformatik-initiativede_dataSend/, medizininformatik-initiativede_dataReceive/
  • Description: The KDS client will log additional debug output
  • Example: See default value
  • Recommendation: Change default value only if exceptions occur
  • Default: false

DE_MEDIZININFORMATIK_INITIATIVE_KDS_FHIR_SERVER_TIMEOUT_CONNECT

  • Property: de.medizininformatik.initiative.kds.fhir.server.timeout.connect
  • Required: false
  • Processes: medizininformatik-initiativede_dataSend/, medizininformatik-initiativede_dataReceive/
  • Description: The timeout in milliseconds until a connection is established between the KDS client and the KDS FHIR server
  • Example: See default value
  • Recommendation: Change default value only if timeout exceptions occur
  • Default: 10000

DE_MEDIZININFORMATIK_INITIATIVE_KDS_FHIR_SERVER_TIMEOUT_CONNECTION_REQUEST

  • Property: de.medizininformatik.initiative.kds.fhir.server.timeout.connection.request
  • Required: false
  • Processes: medizininformatik-initiativede_dataSend/, medizininformatik-initiativede_dataReceive/
  • Description: The timeout in milliseconds used when requesting a connection from the connection manager between the KDS client and the KDS FHIR server
  • Example: See default value
  • Recommendation: Change default value only if timeout exceptions occur
  • Default: 10000

DE_MEDIZININFORMATIK_INITIATIVE_KDS_FHIR_SERVER_TIMEOUT_SOCKET

  • Property: de.medizininformatik.initiative.kds.fhir.server.timeout.socket
  • Required: false
  • Processes: medizininformatik-initiativede_dataSend/, medizininformatik-initiativede_dataReceive/
  • Description: Maximum period of inactivity in milliseconds between two consecutive data packets of the KDS client and the KDS FHIR server
  • Example: See default value
  • Recommendation: Change default value only if timeout exceptions occur
  • Default: 10000
Clone this wiki locally