EMMA erweitert EMIL um einen FHIR-R4-Server (FHIR-Version 4.0.1), über den externe Systeme (Klinik-Middleware, Statistik-Software, Studien-Datenbanken, Patienten-Apps) lesend und schreibend auf den Patientenbestand zugreifen können. Der Zugriff ist OAuth2-geschützt; für jedes zugreifende System richten Sie einen eigenen Client mit eigenem Secret ein. Die Einstellungen finden Sie unter Administration|Schnittstellen|FHIR R4 Server.
Dieses Kapitel beschreibt die Einrichtung. Für die Entwickler der anbindenden Systeme folgen in den Unterkapiteln:
•Anmeldung (OAuth2): Token holen per Client-Credentials oder Authorization-Code-Flow mit PKCE.
•Discovery und CodeSystems: CapabilityStatement, SMART-Konfiguration und die Bedeutung der internen IDs.
•Lesen und $bundle-Export: Patienten, Formulardefinitionen, Bilder und Kohorten-Export.
•Schreiben: Observation und QuestionnaireResponse.
•Fehlerreferenz: HTTP-Statuscodes, Meldungen und Abhilfe.
Alle Beispiele sind generische HTTP-Aufrufe. Sie funktionieren mit jedem HTTP-Werkzeug (curl, Postman, Insomnia, HTTPie) und mit jeder Programmiersprache, die einen HTTP-Client hat. Ersetzen Sie EMIL-Server:8443 durch Host und Port Ihres EMIL-Servers und <token> durch den Bearer-Token aus der Anmeldung.
Freischaltung und Lizenz
Einen eigenen Ein-/Aus-Schalter für den FHIR-Server gibt es nicht. Der Endpunkt https://EMIL-Server:8443/fhir ist immer geladen, Zugriff erhält aber nur ein System, das sich mit einem aktiven Client anmeldet. Solange kein Client eingerichtet ist, ist der Server also geschlossen.
Eigene Clients anlegen, bearbeiten und löschen können Sie nur mit aktiver EMMA-Lizenz. Ohne EMMA-Lizenz lehnt der Server die Anmeldung eigener Clients mit 403 ab. Ausgenommen sind die vorkonfigurierten Kanäle fest verdrahteter Schnittstellen (z. B. RheCORD); sie arbeiten auch ohne EMMA.
Vorkonfigurierte Kanäle stehen oben in der Client-Liste und sind schreibgeschützt: Sie können sie weder bearbeiten noch löschen, nur ihr Secret erneuern. Ist einem solchen Kanal keine Studie zugewiesen, hat er keinen Lesezugriff auf Patientendaten (Anzeige Keine (kein Lesezugriff)).
Clients verwalten
1.Client-Liste: alle eingerichteten FHIR-Clients. Jede Zelle ist direkt editierbar; Änderungen werden ohne Bestätigung sofort gespeichert. Die Spalten sind unten beschrieben.
2.Hinzufügen: legt einen neuen Client an. Sie geben eine Client-ID ein, die der Client beim Login als client_id verwendet. Anschließend erzeugt EMIL ein Secret aus 48 Zufallszeichen und zeigt es einmalig zum Kopieren an (siehe Bild unten). Bewahren Sie das Secret sicher auf: Im Klartext wird es nie wieder angezeigt, der Server speichert nur den SHA-3-Hash.
3.Neues Secret: erzeugt nach Rückfrage für den ausgewählten Client ein neues Secret, z. B. bei Verlust oder turnusmäßiger Erneuerung. Das bisherige Secret wird sofort ungültig.
4.Löschen: entfernt den ausgewählten Client nach Bestätigung unwiderruflich. Bereits erteilte Tokens bleiben bis zu ihrer Ablaufzeit (Standard eine Stunde) gültig.
Spalten der Client-Liste
Spalte |
Bedeutung |
Client-ID |
Eindeutiger technischer Name, den der Client beim Login (client_id) verwendet. Empfehlung: Kleinbuchstaben und Bindestriche, sprechend („klinik-meinhof“, „rhdv-statistik“). |
Aktiv |
Ja: Der Client kann sich anmelden. Nein: Die Anmeldung wird mit 403 abgelehnt; die Zeile bleibt erhalten, der Zugriff ist nur ausgesetzt. |
Anonym |
Ja: Patient-Ressourcen kommen ohne Name, Geburtsdatum und externe Identifier (KIS-ID, PVS-ID usw.). Pseudonyme (interne Subject-ID, Studien-Patient-IDs) und alle klinischen Werte bleiben enthalten; Auswertungen sind also weiter möglich, der Personenbezug ist entfernt. Die Bilddaten selbst erhält ein anonymer Client nicht (siehe Patientenbilder lesen). Nein: Patientendaten mit allen Klartextangaben. Beim $bundle-Export lässt sich die Anonymisierung außerdem je Anfrage mit ?anonymize=1 anfordern. |
Erlaubte Studie (outbound) |
Keine Einschränkung: Der Client sieht den gesamten Patientenbestand („Statistiker-Modus“). Oder eine Studie: Der Client sieht nur die eingeschlossenen Patienten dieser Studie, und die Patient-Ressource enthält nur den Studien-Identifier dieser einen Studie. |
Consent |
Nur bei zugewiesener Studie relevant. Ja: Von den eingeschlossenen Patienten werden nur die mit Einverständnis (consent_flag) ausgeliefert. Nein: alle eingeschlossenen Patienten; den Consent-Status meldet der Server über eigene Consent-Ressourcen. Patienten mit Widerspruch (refuse_flag) oder mit Kennzeichen „ignorieren“ (ignore_flag) werden nie exportiert. |
Erlaubte ItemTypen (inbound) |
Whitelist der ItemType-IDs, die dieser Client per POST/PUT schreiben darf. Standard ist leer, also kein Schreibrecht (Anzeige „(alle gesperrt)“). Ein Klick öffnet einen Auswahldialog mit allen ItemTypes (alphabetisch, mit Suche und Bereichsangabe in Klammern, siehe Bild unten). Berechnete Felder (z. B. BMI) fehlen dort, weil der Server sie selbst berechnet. Die Zelle zeigt eine Kurzform „N Items: Titel1, Titel2, Titel3, …“. |
Erlaubte ItemTypen (outbound) |
Legt fest, welche ItemType-IDs dieser Client lesen bzw. über $bundle exportieren darf. Das ist eine harte Grenze: Nur freigegebene Observation, QuestionnaireResponse und MedicationStatement verlassen den Server, alles andere entfernt der Server vor dem Versand. Ein $bundle?type=<id> auf einen nicht freigegebenen Typ liefert 403. Der Auswahldialog bietet zwei Sammeleinträge: Alles (alle Daten inkl. Medikation) und Medikation (die gesamte Medikationshistorie, die an keinem einzelnen ItemType hängt). Mit Medikation allein liefert der Server die Medikationshistorie (history); die Statusmeldungen je Encounter (encounter-status) erscheinen nur, wenn zusätzlich mindestens ein Observation-Typ freigegeben ist, weil sie an einem Encounter hängen. Neue wie bestehende Clients sind mit Alles vorbelegt; schränken Sie ein, wenn ein Client nur bestimmte Felder sehen soll. Ist die Liste leer (Anzeige „(kein Export)“), enthält das Bundle nur das Gerüst (Patient, ResearchSubject, Consent) ohne klinische Werte. Die Patient-Stammdaten richten sich nach den Spalten Studie und Anonym, nicht nach dieser Liste. |
Redirect-URLs (Auth-Code) |
Steuert, ob sich der Client zusätzlich über den SMART-Authorization-Code-Flow mit PKCE anmelden darf. Leer: nur Client-Credentials (Anzeige „(nur Client-Credentials)“). Sind eine oder mehrere Redirect-URLs hinterlegt (eine pro Zeile), ist der Authorization-Code-Flow für diesen Client freigeschaltet, beschränkt auf genau diese Adressen. Ein Klick öffnet einen Editor zum Eintragen der URLs. Benötigt wird das für Werkzeuge, die diesen Flow zwingend verlangen (z. B. REDCap). Anzeige „Auth-Code: N URLs“. |
Wann Änderungen wirken
Aktiv, Anonym, Erlaubte Studie, Consent und Erlaubte ItemTypen (outbound) stehen im Token des Clients. Nach einer Änderung braucht der Client einen neuen Token; spätestens nach Ablauf des alten Tokens (Standard eine Stunde) gilt die neue Einstellung. Erlaubte ItemTypen (inbound) dagegen liest der Server bei jedem Schreibvorgang frisch aus der Datenbank: Änderungen greifen sofort, auch mit altem Token.
Audit-Trail
Jeder FHIR-Client wird im Audit-Trail wie ein Benutzer geführt: Jede Schreibaktion erscheint als „FHIR: <Client-ID>“ in den Historien-Einträgen (Subject – History) und in den Audit-Views der Datenbank. So ist nachvollziehbar, welcher Client wann was geschrieben hat.
Server-Einstellungen in der config.ini
Die folgenden Schlüssel im Abschnitt [FHIR] der config.ini des Servers sind optional. Der Server liest sie bei jeder Anfrage, ein Neustart ist nicht nötig.
Schlüssel |
Standard |
Bedeutung |
TOKENTTL |
3600 |
Gültigkeit der Access-Tokens in Sekunden. Ein beim Client hinterlegter eigener Wert geht vor; in der Client-Liste angelegte Clients erhalten 3600 Sekunden. |
REFRESHTTL |
2592000 (30 Tage) |
Gültigkeit der Refresh-Tokens in Sekunden. |
REFRESHENABLED |
1 |
0 schaltet den Refresh-Token-Mechanismus serverweit ab. |
AUTHCONSENT |
0 |
1 verlangt am Authorize-Endpunkt eine Bestätigungsseite mit Eingabe des Client-Secrets. Standard ist aus, damit unbeaufsichtigte Anbindungen wie REDCap ohne wiederholte Secret-Eingabe funktionieren. |
Fehlversuche am Token-Endpunkt bremst die Anmelde-Drosselung; dort ist auch der Betrieb hinter einem Reverse Proxy beschrieben, wenn nur die FHIR-Schnittstelle von außen erreichbar sein soll.