Im Kontext des TI-Messenger-Dienstes wird zwischen den folgenden Ausprägungen des TI-Messenger-Clients unterschieden:
-
TI-Messenger-Clients für Akteure und
-
TI-Messenger-Clients mit Administrationfunktionen.
Beide Arten von Clients basieren auf dem offenen Kommunikationsprotokoll Matrix und werden auf dem Endgerät eines Akteurs verwendet. In der folgenden Dokumentation werden die zwei Ausprägungen der Clients beschrieben.
|
❗
|
Die Seite ergänzt die Spezifikation gemäß [gemSpec_TI-Messenger-Client], die als Grundlage für das Verständnis vorrausgesetzt wird. |
Der TI-Messenger-Client für Akteure unterstützt die meisten aller, durch die Matrix-Spezifikation festgelegten Funktionalitäten eines Matrix-Messengers und weitere durch die gematik definierten Vorgaben. Die Funktionalität des TI-Messenger-Clients für Akteure kann in drei abstrakte Module unterteilt werden. In der folgenden Abbildung wird dies verdeutlicht.
Über das TI-Messenger Modul werden alle Funktionalitäten, die zur Ad-Hoc Kommunikation benötigt werden sowie der Administration der Freigabeliste eines Akteurs, durchgeführt. Hierfür werden am Messenger-Proxy zwei APIs vom TI-Messenger Modul des TI-Messenger-Clients angesprochen. Der TI-Messenger-Client kommuniziert mit dem Messenger-Proxy eines Messenger-Services über die [Matrix - Client-Server API], um Matrix-Events an den zuständigen Matrix-Homeserver auszutauschen. Für die Administration der Freigabeliste kommuniziert das TI-Messenger Modul mit der Schnittstelle I_TiMessengerContactManagement des Messenger-Proxy.
|
ℹ️
|
Der Aufruf der vom Matrix-Homeserver angebotenen Schnittstellen der [Matrix - Client-Server API] erfolgt immer über den Messenger-Proxy. |
In den folgenden Kapiteln werden die vom TI-Messenger Modul zu verwendenen Schnittstellen sowie die vom TI-Messenger-Client bereitzustellenden Funktionen beschrieben.
Der Matrix-Homeserver muss die REST-Schnittstellen gemäß der Matrix [Client-Server API] für den TI-Messenger-Client zur Verfügung stellen. Diese müssen für die TI-Messenger-Clients aus dem Internet angeboten werden. Für die Verarbeitung der Matrix-Events muss der TI-Messenger-Client die in der [Matrix-Client-Server API] clientspezifischen Verhaltensweisen implementieren. Diese sind in der API mit dem Keyword behaviour gekennzeichnet. Unter folgendem Link ist ein Beispiel dargestellt.
Für ein Überblick und für Testzwecke der REST-Schnittstellen der [Matrix-Client-Server API] kann der von der Matrix Foundation bereitgestellte API Playground verwendet werden.
|
🔥
|
Der Playground bildet immer die aktuellste Version der Matrix-Spezifikation ab und stimmt somit ggf. nicht mit der aktuell von der gematik geforderten Version der Matrix-API überein. |
Im Rahmen der Verwendung des Matrix-Protokolls im deutschen Gesundheitswesen ist es notwendig, dies um zusätzliche Vorgaben zu erweitern. Hierzu trifft die gematik die folgenden weiteren Festlegungen zum Umgang mit dem Matrix-Protokoll.
Beim Anlegen eines Raumes über den /_matrix/client/v3/createRoom Endpunkt (siehe: createRoom) über die [Client-Server-API] ist darauf zu achten, dass im invite-Feld maximal eine Matrix-ID (MXID) eines einzuladenden Akteurs angegeben werden darf. Die Vorgabe muss eingehalten werden, damit diese bei der Proxy Berechtigungsprüfung validiert werden kann.
Das Matrix-Protokoll erlaubt während der Erstellung eines Chatraumes einen eigene Raumtyp (Custom Room Type) für diesen mit Hilfe einer Typinitialisierung im /createRoom-Endpunkt zu definieren, um spezielle Raumeigenschaften (Room State Events) für diesen Custom Room Type zu verwenden. Die gematik definiert für föderierte und fallbezogene Kommunikation die folgenden Raumtypen.
-
de.gematik.tim.roomtype.default.v1 -
de.gematik.tim.room.casereference.v1
Es ist vorgesehen den Raumtyp de.gematik.tim.roomtype.default.v1 für alle föderierten Kommunikation beim Anlegen entsprechend zu setzen.
Der Raumtyp de.gematik.tim.room.casereference.v1 ist für die spätere Verwendung im Context von Fallbezogenen Kommunikationen vorgesehen.
|
💡
|
Weitere Informationen mit den Umgang der Raumtypen können in [gemSpec_Ti-Messenger-Client#5.4.17] und [gemSpec_Ti-Messenger-Client#5.4.16] nachgelesen werden. |
|
ℹ️
|
In der veröffentlichten und zulassungsrelevanten Spezifikationsversion v1.1.1 wird die produktive Verwendung der Custom Room Types aktuell nicht gefordert, da die notwendigen Vorbedingungen für den produktiven Einsatz seitens des Matrix-Protokolls noch nicht vollständig erfüllt sind. |
Das Matrix-Protokoll erlaubt die Eigenschaften eines Chatraumes mit State Events zu erweitern bzw. zu ändern. Typische State Events, die ein Room State definieren und die durch das Matrix-Protokoll definiert sind, sind zum Beispiel m.room.name oder m.room.topic. Das Matrix-Protokoll erlaubt auch benutzerdefinierte State Events (Custom State Events) zu verwenden. In der vorliegenden Dokumentation werden bereits erste Custom Room Types sowie Custom State Events mit von der gematik definierten Event Types und Event Content definiert.
-
de.gematik.tim.room.name -
de.gematik.tim.room.topic -
de.gematik.tim.room.default.v1 -
de.gematik.tim.room.casereference.v1
Für die fallbezogene Kommunikation sind die beiden Custom State Events de.gematik.tim.room.name und de.gematik.tim.room.topic vorgesehen, um eine verschlüsselte Abbildung der beiden Standardfelder m.room.name und m.room.topic zu realisieren, da in dieser spezifischen Kommunikation hohe Datenschutzanforderungen bestehen. Im Kontext der fallbezogenen Kommunikation ist es notwendig, zusätzliche patientenbezogene Informationen bereitzustellen. Hierfür ist das Custom State Event de.gematik.tim.room.casereference.v1 vorgesehen, um in diesem den folgenden FHIR-Datensatz zu hinterlegen.
Das Custom State Event de.gematik.tim.room.default.v1 ist vorgesehen, um verschlüsselte Information im Kontext von föderierter und intersektoraler Kommunikation zu ermöglichen. In diesem Fall sind die Informationen zu "Name" und "Topic" des Raumes ebenfalls über die Events de.gematik.tim.room.topic und de.gematik.tim.room.name abzubilden.
|
💡
|
Weitere Informationen zu den Custom State Events können in [gemSpec_Ti-Messenger-Client]#5.4.17 und [gemSpec_Ti-Messenger-Client#5.4.16] nachgelesen werden. |
|
ℹ️
|
In der veröffentlichten und zulassungsrelevanten Spezifikationsversion v1.1.1 wird die produktive Verwendung der Custom State Events aktuell nicht gefordert, da die notwendigen Vorbedingungen für den produktiven Einsatz seitens des Matrix-Protokolls noch nicht vollständig erfüllt sind. |
Über die vom Messenger-Proxy bereitgestellte Schnittstelle I_TiMessengerContactManagement wird die für einen Akteur im Proxy vorgehaltene Freigabeliste administriert. Die Freigabeliste wird in AF10061 - Einladung von Akteuren außerhalb einer Organisation benötigt, wenn zwei Akteure ihre Kontaktdaten mittels QR-Scan austauschen möchten. Weitere Informationen zu der Schittstelle sind hier zu finden.
Über das VZD-FHIR-Directory Modul wird die Suche und die Pflege von Einträgen im FHIR-Directory ermöglicht. Hier werden die folgenden Endpunkte der Teilkomponenten Auth-Services und FHIR-Proxy des VZD-FHIR-Directory vom VZD-FHIR-Directory Modul des TI-Messenger-Clients angesprochen:
-
Auth-Service
-
/tim-authenticate -
/owner-authenticate
-
-
FHIR-Proxy
-
/search -
/owner
-
Für den Aufruf der beiden Endpunkte /search und /owner am FHIR-Proxy für die Suche und Pflege von Einträgen werden Zugriffstoken benötigt, um die Berechtigung für den Zugriff nachzuweisen. Daher muss der TI-Messenger-Client zuvor am Auth-Service des VZD-FHIR-Directory die notwendigen Token anfragen. Im folgenden werden die Aufrufe der Endpunkte weiter beschrieben.
Der Auth-Service des VZD-FHIR-Directory bietet die zwei Endpunkte an, die die beiden Zugriffstoken (search-accesstoken und owner-accesstoken) ausstellen. Die zwei Endpunkte werden in den folgenden Kapiteln weiter beschrieben.
Für den Zugriff auf die Suchfunktionalität von FHIR-Ressourcen (/search-Endpunkt) authentisiert sich der TI-Messenger-Client gegenüber dem VZD-FHIR-Directory mit einem 3rd-Party-Token (Matrix-OpenID Token), das er von seinem Matrix-Homeserver anfordern kann (siehe Matrix OpenID Token). Dieses 3rd-Party-Token benötigt der TI-Messenger-Client, um es beim /tim-authenticate-Endpunkt des VZD-FHIR-Directory gegen ein search-accesstoken einzutauschen. Bei Aufruf des Endpunktes /tim-authenticate ist es erforderlich, das 3rd-Party-Token (Matrix-OpenID-Token) im Header sowie die URL des Matrix-Homeservers im Parameter MXID zu übergeben. Der Aufruf des /tim-authenticate-Endpunktes ist hier beschrieben.
Für die Pflege von FHIR-Ressourcen (/owner-Endpunkt) authentisiert sich der TI-Messenger-Client gegenüber dem VZD-FHIR-Directory unter Verwendung einer Smartcard (HBA), um ein owner-accesstoken vom Auth-Service zu erhalten. Für die Authentisierung mittels Smartcard ist der von der gematik bereitgestellte zentrale IDP-Dienst zu verwenden. Details sind dem Anwendungsfall AF10058 - Akteur (User-HBA) im Verzeichnisdienst hinzufügen zu entnehmen. Nach erfolgreicher Authensierung erhält der TI-Messenger-Client vom Auth-Service ein owner-accesstoken. Der Aufruf des /owner-authenticate-Endpunktes ist hier beschrieben.
|
💡
|
Für die Interaktion mit den Smartcards und dem zentralen IDP-Dienst ist der gematik authenticator vorgesehen. Es können auch eigene Authenticator-Lösungen verwendet werden. |
Der durchzuführende Authorization Code Flow ist hier beschrieben.
Der FHIR-Proxy bietet zwei Endpunkte zur Suche und Pflege von FHIR-Ressourcen an, die nur unter Verwendung eines gültigen Zugriffstoken aufgerufen werden können. Die zwei Endpunkte werden in den folgenden Kapiteln weiter beschrieben.
Der FHIR-Proxy bietet über die Schnittstelle FHIRDirectorySearchAPI den Endpunkt /search an, um FHIR-Ressourcen zu suchen. Um diesen Endpunkt aufrufen zu können, wird ein search-accesstoken im Authorization Header benötigt. Eine beispielhafte Verwendung der Schnittstelle für die Suche von FHIR-Ressourcen ist in search API examples beschrieben.
Der FHIR-Proxy bietet über die Schnittstelle FHIRDirectoryOwnerAPI den Endpunkt /owner an, um FHIR-Ressourcen zu suchen und eigene Einträge zu pflegen. Um diesen Endpunkt aufrufen zu können, wird ein owner-accesstoken im Authorization Header benötigt. Eine beispielhafte Verwendung der Schnittstelle zur Pflege der FHIR-Ressourcen ist in owner API examples beschrieben.
Über das Auth Modul wird die Kommunikation mit Smartcards (HBA) realisiert, um diese zur Authentisierung am /owner-authenticate-Endpunkt zu ermöglichen. Dies wird als Grundlage für den Anwendungsfall AF_10058 Akteur(User-HBA) im Verzeichnisdienst hinzufügen benötigt. Im Folgenden wird der Prozess kurz skizziert, nachdem beim Aufruf des /owner-authenticate-Endpunktes das Auth Modul einen Redirect zum Authorization Endpoint des IDP-Dienstes vom Auth-Service erhalten hat.
Nach Erhalt des Redirects ruft das Auth Modul des TI-Messenger-Clients den {Authorization Endpoint} am zentralen IDP-Dienst auf, um das Challenge-Response-Verfahren durchzuführen und abschließend den AuthorizationCode sowie den Redirect zum /signin-gematik-idp-dienst-Endpunkt zu erhalten.
An dem Endpunkt /signin-gematik-idp-dienst übergibt das Auth Modul des TI-Messenger-Clients den AuthorizationCode um sich ein owner-accesstoken ausstellen zu lassen. Der AuthorizationCode wird vom Auth-Service an den zentralen-IDP-Dienst weitergeleitet, um das für die passende Smartcard gehörende ID_TOKEN zu erhalten. Die darin enthaltenen TelematikID und ProfessionOID werden im Rahmen der Ausstellung des owner-accesstoken verwendet.
TI-Messenger-Clients müssen über eine Funktion verfügen die die Sichtbarkeit eines Akteurs für den TI-Messenger-Dienst im Personenverzeichnis über den /owner-Endpunkt des VZD-FHIR-Directory ein bzw. ausschalten kann. Wenn ein Akteur den Status seines Endpunktes von active nach off ändert, muss der TI-Messenger-Client prüfen, ob diese MXID auch im Organisationsverzeichnis eingetragen ist. Wird die MXID ebenfalls im Organisationsverzeichnis gefunden und ist der hinterlegte Status in diesem Verzeichnis active, dann ist im TI-Messenger-Client dem Akteur ein entsprechender Hinweis anzuzeigen, dass eine Inkonsistenz in der hinterlegten Sichtbarkeit vorliegt.
|
❗
|
Aus dem Hinweis muss hervorgehen, dass ein Kontaktieren des Administrators seiner Organisation notwendig ist, um die gewünschte Sichtbarkeit ebenfalls im Organisationsverzeichnis zu hinterlegen. |
Der TI-Messenger-Client muss eine Funktion bereitstellen, um Kontaktdaten mittels 2D-Barcodes austauschen zu können.
Hierbei muss der 2D-Code in eine QR-Code-Darstellung gemäß [ISO/IEC 18004:2006] kodiert werden. Im folgenden wird das zu verwendene vCard-Object dargestellt:
BEGIN:VCARD
VERSION:4.0
N:<Nachname>;<Vorname>;<zusätzliche Vornamen>;<Titel>;<Namenszusätze>
FN:<Vorname><Nachname>
IMPP:matrix://<MXID>
END:VCARDDer Aufbau der Matrix-URI muss gemäß Matrix-Appendices gebildet werden.
|
💡
|
Bei dem gezeigten vCard-Object handelt es sich um die geforderte Mindestbefüllung, die Verwendung weiterer Felder ist zulässig. |
Der TI-Messenger-Client muss den eingescannten 2D-Code gemäß [ISO/IEC 18004:2006] decodieren und mindestens den vollständigen Namen sowie die MXID aus den Parameter N und IMPP dem Akteur anzeigen, damit dieser die Aufnahme in die Freigabeliste bestätigen oder ablehnen kann (siehe AF_10061 - Einladung von Akteuren außerhalb einer Organisation).
Der TI-Messenger-Client muss bei der initialen Vergabe des Displayname die folgende Bildungsregel durchsetzen: [Name], [Vorname]. Der TI-Messenger-Client darf dem Akteur nach der initialen Vergabe des Displaynamen nicht die Möglichkeit anbieten, diesen zu ändern. Hierfür darf der TI-Messenger-Client nicht die REST-Schnittstelle /_matrix/client/v3/profile/{userId}/displayname der [Client-Server API] aufrufen.
|
🔥
|
Das Ändern des Displaynamens eines Akteurs ist nur mittels des TI-Messenger-Clients mit Administrationsfunktionen möglich. |
Der TI-Messenger-Client mit Administrationsfunktionen ist ein Client für Akteure in der Rolle "Org-Admin" einer Organisation. Dieser wird im Kontext des TI-Messenger-Dienstes auch als Org-Admin-Client bezeichnet. Der Org-Admin-Client dient zur komfortablen Verwaltung der Messenger-Services bei einem TI-Messenger-Fachdienst. Die im folgenden beschriebenen Funktionalitäten für einen Org-Admin-Client können separat oder im TI-Messenger-Client für Akteure integriert sein. Hierbei ist darauf zu achten, dass separate User-Interfaces für die jeweilige Rolle (die gerade angemeldet ist) angeboten werden, die nur die relevanten Informationen für die Rolle bereitstellen.
Mit dem Org-Admin-Client haben Administratoren einer Organisation die Möglichkeit Akteure und Endgeräte auf dem jeweiligen Messenger-Service der Organisation zu verwalten. Zu dem Funktionsumfag des Org-Admin-Clients gehören:
-
Benutzerverwaltung (Auflistung aller Akteure, Anlegen, Bearbeiten, Löschen),
-
Geräteverwaltung (Anzeigen, Abmelden, Löschen aller Geräte eines Messenger-Service seiner Organisation),
-
die Verwaltung von Einträgen im VZD-FHIR-Directory,
-
Systemmeldungen an Akteure eines Messenger-Services senden (z. B. Wartungsfenster bekannt machen) und
-
Einrichtung von Funktionsaccounts.
Der Administrator einer Organisation (in der Rolle "Org-Admin") verwaltet mittels des Org-Admin-Clients die FHIR-Ressourcen für seine Organisation im VZD-FHIR-Directory (siehe AF_10059 - Organisationsressourcen im Verzeichnisdienst hinzufügen).
Authentisierung
Für den Zugriff auf die /owner-Schnittstelle am FHIR-Proxy wird ein owner-accesstoken benötigt, das vom /owner-authenticate-Endpunkt des Auth-Service ausgestellt wird. Zur Authentisierung am Endpunkt fragt der Org-Admin-Client beim zuständigen Registrierungs-Dienst einen RegService-OpenID-Token an, welcher am /owner-authenticate-Endpunkt gegen ein owner-accesstoken ausgetauscht wird. Ein Beispiel für die Authentisierung ist hier zu finden.
Bearbeitung
Zur Pflege der FHIR-Ressourcen ist es erforderlich, dass der Org-Admin-Client den Endpunkt /owner unter Verwendung des owner-accesstoken (welches im Authorization Header mit übergeben werden muss) aufruft. Eine beispielhafte Verwendung der Schnittstelle zur Pflege der FHIR-Ressourcen ist in der owner API examples beschrieben. Der vom Org-Admin-Client angebotene Funktionsumfang ist:
-
Verwaltung von HealthcareServices und
-
Verwaltung von Endpoints.
Einrichtungen im Gesundheitswesen sind sehr unterschiedlich strukturiert und wollen hinsichtlich ihrer Erreichbarkeit flexibel eigene Strukturen abbilden können. Daher sind beim TI-Messenger-Dienst Funktionsaccounts notwendig, die es ermöglichen, Akteure unterhalb der Struktur erreichbar zu machen. Hierfür ist es erforderlich das über den Org-Admin-Client ein Endpoint im FHIR-Directory angelegt wird.
|
💡
|
Für den Endpoint sollte ein sprechender Name verwendet werden. Sprechende Namen wären zum Beispiel Kardiologie für eine Abteilung oder Krankenhaus am Feld für ein Krankenhaus.
|
Wenn der Funktionsaccount über ein Chatbot realisiert wird, ist folgende Bildungsregel für den Displaynamen zu verwenden:
[Name des Funktionsaccounts] (Chatbot).