diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 696 |
1 files changed, 60 insertions, 636 deletions
@@ -1,673 +1,97 @@ -# ETL-Processor für das MV gem. §64e und DNPM:DIP -[](https://github.com/pcvolkmer/etl-processor/actions/workflows/test.yml) +# ETL-Prozessor für das Modellvorhaben Genomsequenzierung gem. §64e SGB V + +[](https://github.com/pcvolkmer/etl-processor/actions/workflows/ci.yml) +[](https://github.com/pcvolkmer/mv64e-etl-processor/actions/workflows/github-code-scanning/codeql) ETL-Anwendung zur Pseudonymisierung von klinischen Daten für das Modellvorhaben Genomsequenzierung gem. §64e SGB V -im DNPM-Datenmodell 2.1 unter Beachtung des Consents. +im DNPM-Datenmodell 2.1 unter Beachtung und Verwendung der Teilnahmeerklärung und des Broad-Consents. -Pseudonymisierte und mit Consent versehene Daten können sowohl an DNPM:DIP als auch an nNGM weitergeleitet werden. +Pseudonymisierte und mit Consent versehene Datensätze können sowohl an DNPM:DIP als auch an nNGM weitergeleitet werden. Eine Differenzierung anhand der Erkrankung und ICD10-Code ist dabei möglich. -So können zum Beispiel alle Lungenfälle an nNGM, sonstige Fällen an DNPM:DIP weitergeleitet werden. +So können zum Beispiel alle Lungenfälle an nNGM, sonstige Fällen an DNPM:DIP ausgeleitet werden. -Zur Pseudonymgenerierung und Consentverwaltung werden die [Greifswalder Tools gPAS und gICS](https://www.ths-greifswald.de/) +Zur Pseudonymgenerierung und Consentverwaltung werden +die [Greifswalder Tools gPAS und gICS](https://www.ths-greifswald.de/) unterstützt. -Diese Anwendung erlaubt das Entgegennehmen von Datensetzen im DNPM-Datenmodell 2.1 aus dem Onkostar-Plugin -**[mv64e-onkostar-plugin-export](https://github.com/pcvolkmer/mv64e-onkostar-plugin-export)**. +Diese Anwendung erlaubt das Entgegennehmen von Datensetzen im DNPM-Datenmodell 2.1 aus +dem [Onkostar](https://www.it-choice.de/produkte/onkostar/)-Plugin +[mv64e-onkostar-plugin-export](https://github.com/pcvolkmer/mv64e-onkostar-plugin-export).  -## Wichtige Änderungen in den letzten Versionen - -### 🔥 Wichtige Änderungen in Version 0.18 - -Ab Version 0.18 kann diese Anwendung zur Datenausleitung über die nNGM-REST-API verwendet werden. -Dazu kann auch die Konfiguration des in dieser Version eingeführten [Routing-Mechanismus](#routed-rest) verwendet werden. - -### 🔥 Wichtige Änderungen in Version 0.17 - -Ab Version 0.17 verwendet diese Anwendung [pcvolkmer/mv64e-mtb-model](https://github.com/pcvolkmer/mv64e-mtb-model) und ersetzt -damit die bisher genutzte und veraltete Implementierung des DNPM-Datenmodells 2.1. - -### 🔥 Wichtige Änderungen in Version 0.16 - -#### Erkennung von Follow-Ups - -Ab Version 0.16 werden Meldungen als Follow-Ups erkannt und entsprechend weiterleiten, wenn - -* die zu bearbeitende Meldung Follow-Ups enthält und das neueste Follow-Up nach der letzten Meldung für den Patienten datiert ist. -* zuvor eine initiale Meldung bereits erfolgte, die akzeptiert wurde. - -Dies erfordert das Aktivieren der Funktion [Blockieren weiterer initialer Submissions](#blockieren-weiterer-initialer-submissions) - -#### Monitoring von ungültigen Anfragen - -Ungültige Anfragen werden nun protokolliert und können in der Übersicht eingesehen werden. -Zuvor wurden diese ignoriert. - -### 🔥 Wichtige Änderungen in Version 0.15 - -#### Konfiguration von Benutzern - -Zusätzlich zu einem Administrator-Account können nun [weitere Benutzer](#weitere-benutzer) -mit nicht administrativen Rechten in der Konfiguration angelegt werden. - -#### TAN-Speicherung - -Ab Version 0.15 wird zu jeder Anfrage die generierte TAN zusätzlich zur Request-ID gespeichert. -Die TAN wird nur für MTB-Anfragen gespeichert, da sie für Lösch-Anfragen nicht relevant ist. - -Hierdurch wird es möglich, die in Version 0.14 eingeführte Blockierung weiterer Submissions anhand der TAN -(z.B. aus der Meldebestätigung) für einen Patienten freizugeben. - -## Funktionsweise - -### Duplikaterkennung - -Die Erkennung von Duplikaten ist normalerweise immer aktiv, kann jedoch über den -Konfigurationsparameter -`APP_DUPLICATION_DETECTION=false` deaktiviert werden. - -### Modelvorhaben genomDE §64e - -#### Vorgangsummern -Zusätzlich zur Patienten Identifier Pseudonymisierung müssen Vorgangsummern generiert werden, die -jede Übertragung eindeutig identifizieren aber gleichzeitig dem Patienten zugeordnet werden können. -Dies lässt sich durch weitere Pseudonyme abbilden, allerdings werden pro Originalwert mehrere -Pseudonyme benötigt. -Zu diesem Zweck muss in gPas eine **Multi-Pseudonym-Domäne** konfiguriert werden (siehe auch -*APP_PSEUDONYMIZE_GPAS_CCDN*). - -**WICHTIG:** Deaktivierte Pseudonymisierung ist nur für Tests nutzbar. Vorgangsummern sind zufällig -und werden anschließend verworfen. - -#### Blockieren weiterer initialer Submissions - -Diese Anwendung blockiert weitere initiale Submissions nach der ersten erfolgreichen Übertragung in DNPM:DIP. -Sobald für einen Patienten eine Übertragung ohne Issues oder mit maximal Warnungen erfolgte und damit von -DNPM:DIP akzeptiert wurde, werden weitere Meldungen solange verworfen, bis ein Administrator den Patienten -wieder freigegeben hat. - -**ACHTUNG**: Diese Funktionalität ist ab Version 0.14 verfügbar, jedoch nicht standardmäßig aktiviert und -muss erst aktiviert werden. - -`APP_POST_INITIAL_SUBMISSION_BLOCK` -> `true` | `false` (falls fehlt, wird `false` angenommen) - -Nach Aktivierung des Features wird es für ältere Meldungen erforderlich sein, bereits durchgeführte -Initialmeldungen als solche zu kennzeichnen. Dies **muss** manuell in der Datenbank gemacht werden. - -Gezielt Meldungen kennzeichnen: - -```sql -UPDATE request SET submission_type = "INITIAL" - WHERE id IN (...); -``` - -Alle MTB-File Meldungen (ohne Lösch-Request) kennzeichnen, die erfolgreich an DNPM:DIP gesendet wurden: - -```sql -UPDATE request SET submission_type = "INITIAL" - WHERE (status = "WARNING" OR status = "SUCCESS") - AND type = "MTB_FILE"; -``` - -#### Test Betriebsbereitschaft -Um die volle Betriebsbereitschaft herzustellen, muss eine erfolgreiche Übertragung mit dem -Submission-Typ *Test* erfolgt sein. Über die Umgebungsvariable wird dieser Übertragungsmodus -aktiviert. Alle Datensätze mit erteilter Teilnahme am Modelvorhaben werden mit der Test-Submission-Kennung -übertragen, unabhängig vom ursprünglichen Wert. - -`APP_GENOM_DE_TEST_SUBMISSION` -> `true` | `false` (falls fehlt, wird `false` angenommen) - -**ACHTUNG**: Diese Einstellung funktioniert nur, wenn, wie in Marburg, eine vollständige Consent-Abfrage über gICS für -MV-Consent und Broad Consent erfolgt. - -Soll eine Testsubmission ohne diese Anbindung durchgeführt werden, kann eine Transformation als Work-Around umgesetzt werden: - -``` -APP_TRANSFORMATION_0_PATH: "metadata.type" -APP_TRANSFORMATION_0_FROM: "initial" -APP_TRANSFORMATION_0_TO: "test" -``` - -### Datenübermittlung über HTTP/REST - -Anfragen werden, wenn nicht als Duplikat behandelt, nach der Pseudonymisierung direkt an DNPM:DIP -gesendet. - -Ein HTTP-Request kann, angenommen die Installation erfolgte auf dem Host `dnpm.example.com` an -nachfolgende URLs gesendet werden: - -| HTTP-Request | URL | Bemerkung | -|--------------|-----------------------------------------|----------------------------------------------------------------| -| `POST` | `https://dnpm.example.com/mtb` | Die Anwendung verarbeitet den eingehenden Datensatz | -| `DELETE` | `https://dnpm.example.com/mtb/12345678` | Die Anwendung sendet einen Lösch-Request für Pat-ID `12345678` | - -Anstelle des Pfads `/mtb` kann auch, wie in Version 0.9 und älter üblich, `/mtbfile` verwendet -werden. Siehe auch: https://github.com/pcvolkmer/mv64e-etl-processor/pull/196 - -### Datenübermittlung mit Apache Kafka - -Anfragen werden, wenn nicht als Duplikat behandelt, nach der Pseudonymisierung an Apache Kafka -übergeben. -Eine Antwort wird dabei ebenfalls mithilfe von Apache Kafka übermittelt und nach der Entgegennahme -verarbeitet. - -Siehe hierzu auch: https://github.com/pcvolkmer/mv64e-rest-to-kafka-gateway und https://github.com/pcvolkmer/mv64e-kafka-to-rest-gateway. - -## Konfiguration - -### Pseudonymisierung der Patienten-ID - -Wenn eine URI zu einer gPAS-Instanz (Version >= 2023.1.0) angegeben ist, wird diese verwendet. -Ist diese nicht gesetzt. wird intern eine Anonymisierung der Patienten-ID vorgenommen. - -* `APP_PSEUDONYMIZE_PREFIX`: Standortbezogenes Präfix - `UNKNOWN`, wenn nicht gesetzt -* `APP_PSEUDONYMIZE_GENERATOR`: `BUILDIN` oder `GPAS` - `BUILDIN`, wenn nicht gesetzt -* `APP_PSEUDONYMIZE_HMAC_KEY`: Wenn gesetzt, wird anstelle `SHA256` nun `SHA256-HMAC` mit diesem Key verwendet. - -**Hinweis** - -Die Pseudonymisierung erfolgt im ETL-Prozessor nur für die Patienten-ID. -Andere IDs werden mithilfe des standortbezogenen Präfixes (erneut) anonymisiert, um für den -aktuellen Kontext nicht -vergleichbare IDs bereitzustellen. - -#### Eingebaute Anonymisierung - -Wurde keine oder die Verwendung der eingebauten Anonymisierung konfiguriert, so wird für die -Patienten-ID der entsprechende SHA-256-Hash gebildet und Base32-codiert - hierzu werden die ersten 42 Zeichen des Hashes -ohne endende "=" - zuzüglich des konfigurierten Präfixes als Patienten-Pseudonym verwendet. - -Beispiel für ID `123` und Prefix `123`: - -`UNKNOWN_uzs2iwjaiixz2ql6jbt67xcpxcqeuhz774p2a7uzr2` - -Wird `APP_PSEUDONYMIZE_HMAC_KEY` konfiguriert, wird der Hash mit diesem Wert als HMAC-Key gebildet. -Auch hier werden die ersten 42 Zeichen Base64-codiert verwendet. -Hierdurch wird die Nutzung von Rainbow-Tables erschwert, solange der HMAC-Key geheim gehalten wird. - -Beispiel für ID `123` und HMAC-Key `TEST` (gleichzeitig HMAC-Key): - -`UNKNOWN_3u2nc3hzwbe2kylbmcrhoahgkisxl5jfbcwr3wonr3` - -#### Pseudonymisierung mit gPAS - -Wurde die Verwendung von gPAS konfiguriert, so sind weitere Angaben zu konfigurieren. - -Ab Version 2025.1 (Multi-Pseudonym Support) - -* `APP_PSEUDONYMIZE_GPAS_URI`: URI der gPAS-Instanz REST API (e.g. http://127.0.0.1:9990/ttp-fhir/fhir/gpas) -* `APP_PSEUDONYMIZE_GPAS_USERNAME`: gPas Basic-Auth Benutzername -* `APP_PSEUDONYMIZE_GPAS_PASSWORD`: gPas Basic-Auth Passwort -* `APP_PSEUDONYMIZE_GPAS_PATIENT_DOMAIN`: gPas Domänenname für Patienten ID (ebenfalls gültig: `APP_PSEUDONYMIZE_GPAS_PID_DOMAIN`) -* `APP_PSEUDONYMIZE_GPAS_GENOM_DE_TAN_DOMAIN`: gPAS Multi-Pseudonym-Domäne für genomDE Vorgangsnummern ( - Clinical data node) - -Soll anstelle der REST-Schnittstelle von gPAS die SOAP-Schnittstelle verwendet werden, -so ist nicht die URI der gPAS-Instanz anzugeben, sondern der SOAP-Endpoint: - -* `APP_PSEUDONYMIZE_GPAS_SOAP_ENDPOINT`: SOAP-Endpoint der gPAS-Instanz (e.g. http://127.0.0.1:9990/gpas/gpasService) - -### (Externe) Consent-Services - -Consent-Services können konfiguriert werden. - -* `APP_CONSENT_SERVICE`: Zu verwendender (externer) Consent-Service: - * `NONE`: Verwende Consent-Angaben im MTB-File v1 und ändere diese nicht. Für MTB-File v2 wird - die Prüfung übersprungen. - * `GICS`: Verwende gICS der Greiswalder Tools (siehe unten). - -#### Einwilligung gICS - -Ab gIcs Version 2.13.0 kann im ETL-Processor -per [REST-Schnittstelle](https://simplifier.net/guide/ttp-fhir-gateway-ig/ImplementationGuide-markdown-Einwilligungsmanagement-Operations-isConsented?version=current) -der Einwilligungsstatus abgefragt werden. -Vor der MTB-Übertragung kann der zum Sendezeitpunkt verfügbarer Einwilligungsstatus über Endpunkt -*isConsented* (MTB-File v1) und *currentPolicyStatesForPerson* (MTB-File v2) abgefragt werden. - -Falls Anbindung an gICS aktiviert wurde, wird der Einwilligungsstatus der MTB Datei ignoriert. -Stattdessen werden vorhandene Einwilligungen abgefragt und in die MTB Datei eingebettet. - -Es werden zwei Einwilligungsdomänen unterstützt, eine für Broad Consent und als zweites GenomDE -Modelvorhaben §64e. - -##### Hinweise - -1. Die aktuelle Impl. nimmt an, dass die hinterlegten Domänen der Einwilligungen ausschließlich für - die genannten Art von Einwilligungen genutzt werden. Es finde keine weitere Filterung statt. Wir - fragen pro Domäne die Schnittstelle `CurrentPolicyStatesForPerson` - siehe - auch [IG TTP-FHIR Gateway - ](https://www.ths-greifswald.de/wp-content/uploads/tools/fhirgw/ig/2024-3-0/ImplementationGuide-markdown-Einwilligungsmanagement-Operations-currentPolicyStatesForPerson.html) - ab. -2. Die Einwilligung wird für den Patienten-Identifier der MTB abgerufen und anschließend durch das - DNPM Pseudonym ersetzt. -3. Abfragen von Einwilligungen über gesonderte Pseudonyme anstatt des MTB-Identifiers fehlt in der - ersten Implementierung. - -##### Konfiguration - -* `APP_CONSENT_SERVICE`: Folgende Werte sind möglich: - * Der Wert `GICS` aktiviert die Standard-Abfrage bei gICS - * Der Wert `GICS_GET_BC` aktiviert die **experimentelle** Abfrage per HTTP-GET Request **nur** für Broad-Consent. - * Der Wert `NONE` deaktiviert die Abfrage in gICS. -* `APP_CONSENT_GICS_URI`: URI der gICS-Instanz (z.B. `http://localhost:8090/ttp-fhir/fhir/gics`) -* `APP_CONSENT_GICS_USERNAME`: gIcs Basic-Auth Benutzername -* `APP_CONSENT_GICS_PASSWORD`: gIcs Basic-Auth Passwort -* `APP_CONSENT_GICS_PERSONIDENTIFIERSYSTEM`: Derzeit wird nur die PID unterstützt. wenn leer wird - `https://ths-greifswald.de/fhir/gics/identifiers/Patienten-ID` angenommen -* `APP_CONSENT_GICS_BROADCONSENTDOMAINNAME`: Domäne in der gIcs Broad Consent Einwilligungen - verwaltet. Falls Wert leer, wird `MII` angenommen. -* `APP_CONSENT_GICS_GENOMDECONSENTDOMAINNAME`: Domäne in der gIcs GenomDE Modelvorhaben §64e - Einwilligungen verwaltet. Falls Wert leer, wird keine Consent-Information abgerufen. -* `APP_CONSENT_GICS_POLICYCODE`: Die entscheidende Objekt-ID der zu prüfenden Einwilligung-Regel. - Falls leer wird `2.16.840.1.113883.3.1937.777.24.5.3.6` angenommen. -* `APP_CONSENT_GICS_POLICYSYSTEM`: Das System der Einwilligung-Regel der Objekt-IDs. Falls leer wird - `urn:oid:2.16.840.1.113883.3.1937.777.24.5.3` angenommen. -* `APP_CONSENT_GICS_POLICYURI`: Die Version der Einwilligung. Falls leer wird Version 1.6d - (`urn:oid:2.16.840.1.113883.3.1937.777.24.2.1790`) angenommen. - -Die **experimentelle* Abfrage über `GICS_GET_BC` setzt voraus, dass bereits ein MV-Consent im eingehenden Datensatz -vorhanden ist und ergänzt nur den Broad-Consent. - -### Anmeldung mit einem Passwort - -Ein initialer Administrator-Account kann optional konfiguriert werden und sorgt dafür, dass -bestimmte Bereiche nur nach einem erfolgreichen Login erreichbar sind. - -* `APP_SECURITY_ADMIN_USER`: Muss angegeben werden zur Aktivierung der Zugriffsbeschränkung. -* `APP_SECURITY_ADMIN_PASSWORD`: Das Passwort für den Administrator (Empfohlen). - -Ein Administrator-Passwort muss inklusive des Encoding-Präfixes vorliegen. - -Hier Beispiele für das Beispielpasswort `very-secret`: - -* `{noop}very-secret` (Das Passwort liegt im Klartext vor - nicht empfohlen!) -* `{bcrypt}$2y$05$CCkfsMr/wbTleMyjVIK8g.Aa3RCvrvoLXVAsL.f6KeouS88vXD9b6` -* `{sha256}9a34717f0646b5e9cfcba70055de62edb026ff4f68671ba3db96aa29297d2df5f1a037d58c745657` - -Wird kein Administrator-Passwort angegeben, wird ein zufälliger Wert generiert und beim Start der -Anwendung in den Logs angezeigt. - -#### Weitere Benutzer - -Ab Version 0.15.0 können weitere Benutzer-Accounts konfiguriert werden, ohne OpenID Connect zu verwenden. -Diese haben lediglich Benutzerrechte und können keine Konfigurationen einsehen oder ändern. - -Beispiele: - -``` -APP_SECURITY_USERS[0]_USERNAME=myuser -APP_SECURITY_USERS[0]_PASSWORD={noop}very-secret -APP_SECURITY_USERS[1]_USERNAME=otheruser -APP_SECURITY_USERS[1]_PASSWORD={bcrypt}$2y$05$CCkfsMr/wbTleMyjVIK8g.Aa3RCvrvoLXVAsL.f6KeouS88vXD9b6 -... -``` - -#### Weitere (nicht administrative) Nutzer mit OpenID Connect - -Die folgenden Konfigurationsparameter werden benötigt, um die Authentifizierung weiterer Benutzer an -einen OIDC-Provider -zu delegieren. -Ein Admin-Benutzer muss dabei konfiguriert sein. - -* `APP_SECURITY_ENABLE_OIDC`: Aktiviert die Nutzung von OpenID Connect. Damit sind weitere Parameter - erforderlich -* `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_CUSTOM_CLIENT_NAME`: Name. Wird beim zusätzlichen - Loginbutton angezeigt. -* `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_CUSTOM_CLIENT_ID`: Client-ID -* `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_CUSTOM_CLIENT_SECRET`: Client-Secret -* `SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_CUSTOM_CLIENT_SCOPE[0]`: Hier sollte immer `openid` - angegeben werden. -* `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_CUSTOM_ISSUER_URI`: Die URI des Providers, - z.B. `https://auth.example.com/realm/example` -* `SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_CUSTOM_USER_NAME_ATTRIBUTE`: Name des Attributes, welches - den Benutzernamen - enthält. - Oft verwendet: `preferred_username` - -Ist die Nutzung von OpenID Connect konfiguriert, erscheint ein zusätzlicher Login-Button zur Nutzung -mit OpenID Connect -und dem konfigurierten `CLIENT_NAME`. - - - -Weitere Informationen zur Konfiguration des OIDC-Providers -sind [hier](https://docs.spring.io/spring-security/reference/servlet/oauth2/index.html#oauth2-client) -zu finden. - -#### Rollenbasierte Berechtigungen - -Wird OpenID Connect verwendet, gibt es eine rollenbasierte Berechtigungszuweisung. - -Die Standardrolle für neue OIDC-Benutzer kann mit der Option `APP_SECURITY_DEFAULT_USER_ROLE` -festgelegt werden. -Mögliche Werte sind `user` oder `guest`. Standardwert ist `user`. - -Benutzer mit der Rolle "Gast" sehen nur die Inhalte, die auch nicht angemeldete Benutzer sehen. - -Hierdurch ist es möglich, einzelne Benutzer einzuschränken oder durch Änderung der Standardrolle auf -`guest` nur -einzelne Benutzer als vollwertige Nutzer zuzulassen. - - - -Benutzer werden nach dem Entfernen oder der Änderung der vergebenen Rolle automatisch abgemeldet und -müssen sich neu anmelden. -Sie bekommen dabei wieder die Standardrolle zugewiesen. - -#### Auswirkungen auf den dargestellten Inhalt - -Nur Administratoren haben Zugriff auf den Konfigurationsbereich, nur angemeldete Benutzer können die -anonymisierte oder -pseudonymisierte Patienten-ID sowie den Qualitätsbericht von DNPM:DIP einsehen. - -Wurde kein Administrator-Account konfiguriert, sind diese Inhalte generell nicht verfügbar. - -### Tokenbasierte Authentifizierung für MTBFile-Endpunkt - -Die Anwendung unterstützt das Erstellen und Nutzen einer tokenbasierten Authentifizierung für den -MTB-File-Endpunkt. - -Dies kann mit der Umgebungsvariable `APP_SECURITY_ENABLE_TOKENS` aktiviert (`true` oder `false`) -werden -und ist als Standardeinstellung nicht aktiv. - -Ist diese Einstellung aktiviert worden, ist es Administratoren möglich, Zugriffstokens für Onkostar -zu erstellen, die -zur Nutzung des MTB-File-Endpunkts eine HTTP-Basic-Authentifizierung voraussetzen. - - - -In diesem Fall kann der Endpunkt für das Onkostar-Plugin * -*[mv64e-onkostar-plugin-export](https://github.com/pcvolkmer/mv64e-onkostar-plugin-export)** wie folgt -konfiguriert werden: - -``` -https://testonkostar:MTg1NTL...NGU4@etl.example.com/mtbfile -``` - -Ist die Verwendung von Tokens aktiv, werden Anfragen ohne die Angabe der Token-Information -abgelehnt. - -Alternativ kann eine Authentifizierung über Benutzername/Passwort oder OIDC erfolgen. - -### Transformation von Werten - -In Onkostar kann es vorkommen, dass ein Wert eines Merkmalskatalogs an einem Standort angepasst -wurde und dadurch nicht dem Wert entspricht, -der von DNPM:DIP akzeptiert wird. - -Diese Anwendung bietet daher die Möglichkeit, eine Transformation vorzunehmen. Hierzu muss der "Pfad" -innerhalb des JSON-MTB-Files angegeben werden und welcher Wert wie ersetzt werden soll. - -Hier ein Beispiel für die erste (Index 0 - weitere dann mit 1,2, ...) Transformationsregel: - -* `APP_TRANSFORMATIONS_0_PATH`: Pfad zum Wert in der JSON-MTB-Datei. Beispiel: - `diagnoses[*].icd10.version` für **alle** Diagnosen -* `APP_TRANSFORMATIONS_0_FROM`: Angabe des Werts, der ersetzt werden soll. Andere Werte bleiben - dabei unverändert. -* `APP_TRANSFORMATIONS_0_TO`: Angabe des neuen Werts. - -### Mögliche Endpunkte zur Datenübermittlung - -Für REST-Requests als auch zur Nutzung von Kafka-Topics können Endpunkte konfiguriert werden. - -Es ist dabei nur die Konfiguration eines Endpunkts zulässig. -Werden sowohl REST als auch Kafka-Endpunkt konfiguriert, wird nur der REST-Endpunkt verwendet. - -#### REST - -Folgende Umgebungsvariablen müssen gesetzt sein, damit ein MTB-File an DNPM:DIP gesendet wird: - -* `APP_REST_URI`: URI der zu benutzenden API der Backend-Instanz. Zum Beispiel `http://localhost:9000/api` -* `APP_REST_TYPE`: Mögliche Werte `dip` (Standard) für DNPM:DIP und `nngm` für die nNGM-API. -* `APP_REST_USERNAME`: Basic-Auth-Benutzername für den REST-Endpunkt -* `APP_REST_PASSWORD`: Basic-Auth-Passwort für den REST-Endpunkt -* `APP_REST_API_KEY`: Angabe eines API-Keys zur Verwendung mit `APP_REST_TYPE=nngm` für die nNGM-API - -#### Routed REST - -Seit Version 0.18 ist eine Konfiguration des neu eingeführten **Routing**-Mechanismus möglich. -Damit kann für bestimmte Entitäten und Diagnosen ein abweichender REST-Endpunkt definiert werden. - -Beispiel: - -* `APP_ROUTING_NNGM_URI`: URI der nNGM-REST-API. -* `APP_ROUTING_NNGM_API_KEY`: API-Key zur Nutzung der nNGM-REST-API. -* `APP_ROUTING_NNGM_ICD10[0]`: Erster ICD-Code - weitere möglich. - -Mit dieser Konfiguration wird jeder `PatientRecord`, dessen (letzte) Diagnose einen ICD-10-Code hat, dessen Anfang -konfiguriert ist, nicht über den Standard-Weg versendet, sondern an den für nNGM konfigurierten API-Endpunkt. - -Wird zum Beispiel `APP_ROUTING_NNGM_ICD10[0] = C34` konfiguriert, werden Diagnosen wie "C34.0", "C34.1", etc. an das nNGM -übermittelt. - -#### Kafka-Topics - -Folgende Umgebungsvariablen müssen gesetzt sein, damit ein MTB-File an ein Kafka-Topic -übermittelt wird: - -* `APP_KAFKA_OUTPUT_TOPIC`: Zu verwendendes Topic zum Versenden von Anfragen. -* `APP_KAFKA_OUTPUT_RESPONSE_TOPIC`: Topic mit Antworten über den Erfolg des Versendens. - Standardwert: `APP_KAFKA_TOPIC` mit Anhang "_response". -* `APP_KAFKA_GROUP_ID`: Kafka GroupID des Consumers. Standardwert: `APP_KAFKA_TOPIC` mit Anhang "_ - group". -* `APP_KAFKA_SERVERS`: Zu verwendende Kafka-Bootstrap-Server als kommagetrennte Liste - -Wird keine Rückantwort über Apache Kafka empfangen und es gibt keine weitere Möglichkeit den Status -festzustellen, verbleibt der Status auf `UNKNOWN`. - -Weitere Einstellungen können über die Parameter von Spring Kafka konfiguriert werden. - -Lässt sich keine Verbindung zu dem Backend aufbauen, wird eine Rückantwort mit Status-Code `900` -erwartet, welchen es -für HTTP nicht gibt. - -Wird die Umgebungsvariable `APP_KAFKA_INPUT_TOPIC` gesetzt, kann eine Nachricht auch über dieses -Kafka-Topic an den ETL-Prozessor übermittelt werden. - -Soll eine SSL-gesicherte Verbindung zu Kafka verwendet werden, so sind die SSL-Zertifikate in -der Spring-Konfiguration anzugeben. -Ein Beispiel findet sich in [`application-dev.yml`](src/main/resources/application-dev.yml). -Dies kann auch mit Umgebungsvariablen wie `SPRING_KAFKA_SECURITY_...` und `SPRING_KAFKA_SSL_...` -umgesetzt werden. - -##### Retention Time - -Generell werden in Apache Kafka alle Records entsprechend der Konfiguration vorgehalten. -So wird ohne spezielle Konfiguration ein Record für 7 Tage in Apache Kafka gespeichert. -Es sind innerhalb dieses Zeitraums auch alte Informationen weiterhin enthalten, wenn der Consent -später abgelehnt wurde. - -Durch eine entsprechende Konfiguration des Topics kann dies verhindert werden. - -Beispiel - auszuführen innerhalb des Kafka-Containers: Löschen alter Records nach einem Tag - -``` -kafka-configs.sh --bootstrap-server localhost:9092 --alter --topic test --add-config retention.ms=86400000 -``` - -##### Key based Retention - -Möchten Sie hingegen immer nur die letzte Meldung für einen Patienten und eine Erkrankung in Apache -Kafka vorhalten, -so ist die nachfolgend genannte Konfiguration der Kafka-Topics hilfreich. - -* `retention.ms`: Möglichst kurze Zeit in der alte Records noch erhalten bleiben, z.B. 10 Sekunden - 10000 -* `cleanup.policy`: Löschen alter Records und Beibehalten des letzten Records zu einem - Key [delete,compact] - -Beispiele für ein Topic `test`, hier bitte an die verwendeten Topics anpassen. - -``` -kafka-configs.sh --bootstrap-server localhost:9092 --alter --topic test --add-config retention.ms=10000 -kafka-configs.sh --bootstrap-server localhost:9092 --alter --topic test --add-config cleanup.policy=[delete,compact] -``` - -Da als Key eines Records die (pseudonymisierte) Patienten-ID verwendet wird, stehen mit obiger -Konfiguration -der Kafka-Topics nach 10 Sekunden nur noch der jeweils letzte Eintrag für den entsprechenden Key zur -Verfügung. - -Da der Key sowohl für die Records in Richtung DNPM:DIP, als auch für die Rückantwort identisch -aufgebaut ist, lassen sich so -auch im Falle eines Consent-Widerspruchs die enthaltenen Daten als auch die Offenlegung durch -Verifikationsdaten in der -Antwort effektiv verhindern, da diese nach 10 Sekunden gelöscht werden. - -Es steht dann nur noch die jeweils letzten Information zur Verfügung, dass für einen Patienten/eine -Erkrankung -ein Consent-Widerspruch erfolgte. - -Dieses Vorgehen empfiehlt sich, wenn Sie gespeicherte Records nachgelagert für andere Auswertungen -verwenden möchten. - -### Antworten und Statusauswertung - -Seit Version 0.10 wird die Issue-Liste der Antwort verwendet und die darion enthaltene höchste -Severity-Stufe als Ergebnis verwendet. - -| Höchste Severity | Status | -|------------------|-----------| -| `info` | `SUCCESS` | -| `warning` | `WARNING` | -| `error`, `fatal` | `ERROR` | - ## Docker-Images -Diese Anwendung ist auch als Docker-Image -verfügbar: https://github.com/pcvolkmer/mv64e-etl-processor/pkgs/container/mv64e-etl-processor - -### Images lokal bauen - -```bash -./gradlew bootBuildImage -``` - -### Integration eines eigenen Root CA Zertifikats - -Wird eine eigene Root CA verwendet, die nicht offiziell signiert ist, wird es zu Problemen beim -SSL-Handshake kommen, wenn z.B. gPAS zur Generierung von Pseudonymen verwendet wird. - -Hier bietet es sich an, das Root CA Zertifikat in das Image zu integrieren. - -#### Integration beim Bauen des Images +Docker-Images dieser Anwendung werden hier bereitgestellt und sollen das lokale Deployment vereinfachen: +https://github.com/pcvolkmer/mv64e-etl-processor/pkgs/container/mv64e-etl-processor -Hier muss die Zeile `"BP_EMBED_CERTS" to "true"` in der Datei `build.gradle.kts` verwendet werden -und darf nicht als Kommentar verwendet werden. +## Wichtige Änderungen -Die PEM-Datei mit dem/den Root CA Zertifikat(en) muss dabei im vorbereiteten Verzeichnis [ -`bindings/ca-certificates`](bindings/ca-certificates) enthalten sein. +### 🔥 Wichtige Änderungen in Version 0.18 -#### Integration zur Laufzeit +Ab Version 0.18 kann diese Anwendung zur Datenausleitung über die nNGM-REST-API verwendet werden. +Dazu kann auch die Konfiguration des in dieser Version eingeführten [Routing-Mechanismus](#routed-rest) verwendet +werden. -Hier muss die Umgebungsvariable `SERVICE_BINDING_ROOT` z.B. auf den Wert `/bindings` gesetzt sein. -Zudem muss ein Verzeichnis `bindings/ca-certificates` - analog zum Verzeichnis -[`bindings/ca-certificates`](bindings/ca-certificates) mit einer PEM-Datei und der -Datei [`bindings/ca-certificates/type`](bindings/ca-certificates/type) als Docker-Volume eingebunden werden. +### Weitere Änderungen -Beispiel für Docker-Compose: +Siehe [CHANGELOG.md](CHANGELOG.md) -``` -... - environment: - SERVICE_BINDING_ROOT: /bindings - ... - volumes: - - "/path/to/bindings/ca-certificates/:/bindings/ca-certificates/:ro" -... -``` +## Wesentlichen Funktionen für das Modellvorhaben Genomsequenzierung -## Deployment +Diese Anwendung unterstützt die wesentlichen Funktionen für den Betrieb einer ETL-Strecke für das Modellvorhaben +Genomsequenzierung nach der Datenextraktion: -*Ausführen als Docker Container:* +* Generierung von Vorgangsnummern +* Pseudonymisierung der Patienten-ID +* Einbetten von Consent-Informationen -```bash -cd ./deploy -cp env-sample.env .env -``` +Dies ist nach einem Export aus dem Primärsystem (z.B. Onkostar) in der Regel noch nicht erfolgt und kann mit dieser +Anwendung realisiert werden. -Wenn gewünscht, Änderungen in der `.env` vornehmen. +### Vorgangsummern -```bash -docker compose up -d -``` +Jede Datenübertragung benötigt eine eindeutige Vorgangsnummer. +Diese Anwendung stellt die erforderlichen Schnittstellen bereit, um eine Vorgangsnummer zu generieren und in den +Datensatz +zu integrieren. -### Einfaches Beispiel für ein eigenes Docker-Compose-File +Weitere Informationen zur Konfiguration der Generierung von Vorgangsnummern gibt es hier: +[docs/configuration.md - Vorgangsnummern](docs/configuration.md#vorgangsnummern). -Die Datei [`docs/docker-compose.yml`](docs/docker-compose.yml) zeigt eine einfache Konfiguration für -REST-Requests basierend -auf Docker-Compose mit der gestartet werden kann. +### Pseudonymisierung der Patienten-ID -### Betrieb hinter einem Reverse-Proxy +Diese Anwendung nutzt die Pseudonymisierungsfunktion von gPAS. Wenn eine URI zu einer gPAS-Instanz (Version >= 2023.1.0) +angegeben ist, wird diese verwendet. +Ist diese nicht gesetzt, wird intern eine Anonymisierung der Patienten-ID vorgenommen. -Die Anwendung verarbeitet `X-Forwarded`-HTTP-Header und kann daher auch hinter einem Reverse-Proxy -betrieben werden. +Weitere Informationen zur Konfiguration der Pseudonymisierung gibt es hier: +[docs/configuration.md - Pseudonymisierung der Patienten-ID](docs/configuration.md#pseudonymisierung-der-patienten-id). -Dabei werden, je nachdem welche Header durch den Reverse-Proxy gesendet werden auch Protokoll, Host -oder auch Path-Präfix -automatisch erkannt und verwendet werden. Dadurch ist z.B. eine abweichende Angabe des Pfads -problemlos möglich. +### Einbetten von Consent-Informationen -#### Beispiel *Traefik* (mit Docker-Labels): +Einbettung von Consent-Informationen kann optional mithilfe von gICS geschehen. -Das folgende Beispiel zeigt die Konfiguration in einer Docker-Compose-Datei mit Service-Labels. +Weitere Informationen zur Konfiguration der Integration und Einbettung von Consent-Informationen gibt es hier: +[docs/configuration.md - Teilnahmeerklärung und Broad Consent mit gICS](docs/configuration.md#teilnahmeerklärung-und-broad-consent-mit-gics). -``` -... - deploy: - labels: - - "traefik.http.routers.etl.rule=PathPrefix(`/etl-processor`)" - - "traefik.http.routers.etl.middlewares=etl-path-strip" - - "traefik.http.middlewares.etl-path-strip.stripprefix.prefixes=/etl-processor" -... -``` +## Weitere Funktionen -#### Beispiel *nginx* +Neben den wesentlichen Funktionen unterstützt diese Anwendung zudem: -Das folgende Beispiel zeigt die Konfiguration einer _location_ in einer nginx-Konfigurationsdatei. +* Konfiguration der Datenein- und Ausgabe zur Unterstützung von REST-Schnittstellen und Message-oriented Middleware + (MoM) mit Apache Kafka. +* Absicherung des Zugriffs durch Anmeldung und Authentifizierung – inklusive der Nutzung von OpenID-Connect. +* Ausleitung von Datensätzen sowohl an DNPM:DIP, als auch die nNGM-API für das Modellvorhaben Genomsequenzierung. +* Duplikaterkennung zum Verhindern von mehrmaliger Übertragung unveränderter Datensätze. +* Blockieren von weiteren Übertragungen ohne bestätigte, initiale Meldung mit Meldebestätigung. +* Automatische FollowUp-Erkennung (nach einer initialen Meldung). +* Eine einfache Weboberfläche zur Nachverfolgung von Datensätzen. -``` -... - location /etl-processor { - set $upstream http://<beispiel:8080>/; - proxy_set_header Host $host; - proxy_set_header X-Forwarded-Scheme $scheme; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header X-Forwarded-For $remote_addr; - proxy_set_header X-Real-IP $remote_addr; - proxy_pass $upstream; - } -... -``` +Alle Informationen zur Konfiguration dieser Funktionen gibt es hier: +[docs/configuration.md](docs/configuration.md). ## Entwicklungssetup -Zum Starten einer lokalen Entwicklungs- und Testumgebung kann die beiliegende Datei -`dev-compose.yml` verwendet werden. -Diese kann zur Nutzung der Datenbanken **MariaDB** als auch **PostgreSQL** angepasst werden. - -Zur Nutzung von Apache Kafka muss dazu ein Eintrag im hosts-File vorgenommen werden und der Hostname -`kafka` auf die lokale -IP-Adresse verweisen. Ohne diese Einstellung ist eine Nutzung von Apache Kafka außerhalb der -Docker-Umgebung nicht möglich. - -Zum Bereitstellen von JavaScript- und CSS-Bundles muss der Befehl `npm run build` ausgeführt werden. -Ein kontinuierliches Neubauen bei Änderungen in CSS und JS-Dateien ist mit `npm run dev` möglich. -Dies setzt eine NodeJS-Umgebung voraus. - -Beim Start der Anwendung mit dem Profil `dev` wird die in `dev-compose.yml` definierte Umgebung beim -Start der Anwendung mit gestartet: - -```bash -SPRING_PROFILES_ACTIVE=dev ./gradlew bootRun -``` - -Die Datei `application-dev.yml` enthält hierzu die Konfiguration für das Profil `dev`. - -Beim Ausführen der Integrationstests wird eine Testdatenbank in einem Docker-Container gestartet. -Siehe hier auch die Klasse `AbstractTestcontainerTest` unter `src/integrationTest`. - -Ein einfaches Entwickler-Setup inklusive DNPM:DIP ist mit Hilfe -von https://github.com/pcvolkmer/dnpmdip-devenv realisierbar. +Informationen für ein Entwicklungssetup sind in [docs/development.md](docs/development.md) zu finden. +Dort sind auch Informationen zur Anpassung des Docker-Images zu hinterlegt. |