Merge remote-tracking branch 'origin/develop'

docs/Anwendungsfaelle.adoc

@@ -82,6 +82,8 @@ Im folgenden Sequenzdiagramm ist die Interaktion zwischen Administrationsmodul u
 </p>
 ++++
 
+Zusätzlich zu den hier beschriebenen Operationen `getAccount()` und `setAccount()` besteht die Möglichkeit durch den Aufruf der Operation `listAccounts()`, am Account Manager, eine Liste aller, für eine Telematik ID, existierenden Accounts zu erhalten.
+
 === Portierung einer Telematik-ID
 Am Administrationsmoduls kann ein KIM-Teilnehmer eine Portierung seiner KIM-E-Mail-Adresse zu einer anderen Telematik-ID (neue Smartcard) durchführen. Dafür ruft das Administrationsmodul die Operationen `getOTP()` und `setTID()` mit einer TLS gesicherten Verbindung am Account Manager auf.  
 
@@ -106,28 +108,6 @@ Im folgenden Sequenzdiagramm ist die Interaktion zwischen Administrationsmodul u
 </p>
 ++++
 
-== Anwendungskennzeichen
-KIM-Teilnehmer können über das Frontend (GUI) des Administrationsmoduls Anwendungskennzeichen für ihren e-Mail Account konfigurieren oder einsehen. Für das konfigurieren eines Anwendungskennzeichens ruft das Administrationsmodul `setAccount()` am Account Manager auf. Für das Abfragen von konfigurierten Anwendungskennzeichen wird die Operation `getAccount()` am Account Manager verwendet. Für jede Operation baut das Administrationsmodul eine TLS-Verbindung zum Account Manager auf. 
-
-Im folgenden Sequenzdiagramm ist die Interaktion zwischen Administrationsmodul und dem Account Manager dargestellt.
-
-++++
-<p align="center">
-  <img width="55%" src=../images/diagrams/Fachdienst/Seq_acc_anwendungskennzeichen.svg>
-</p>
-++++
-
-== Abwesenheitnotizen
-KIM-Teilnehmer können über das Frontend (GUI) des Administrationsmoduls Abwesenheitsnotizen für einen definierten Zeitraum konfigurieren oder einsehen. Für das konfigurieren einer Abwesenheitsnotiz ruft das Administrationsmodul `updateOutOfOffice()` am Account Manager auf. Für das Abfragen von konfigurierten Abwesenheitsnotizen wird die Operation `getOutOfOffice()` am Account Manager verwendet. Für jede Operation baut das Administrationsmodul eine TLS-Verbindung zum Account Manager auf. 
-
-Im folgenden Sequenzdiagramm ist die Interaktion zwischen Administrationsmodul und dem Account Manager dargestellt.
-
-++++
-<p align="center">
-  <img width="55%" src=../images/diagrams/Fachdienst/Seq_acc_abwesenheitsnotiz.svg>
-</p>
-++++
-
 == KIM-Nachrichten
 Das Senden bzw. Empfangen von KIM-Mails wird durch die Schnittstelle `I_Message_Service` am Mail Server ermöglicht. Für den Umgang mit Client-Mails, die größer 15 MiB sind, bietet der KIM-Fachdienst einen KOMLE-Attachment Service (KAS) an. Auf diesen werden über den Aufruf der Schnittstelle `I_Attatchment_Service` die großen Client-E-Mails (E-Mail-Daten) verschlüsselt ausgelagert und später auf Empfängerseite, nach dem Herunterladen vom KAS des Absenders, wieder entschlüsselt und an das Clientsystems des Empfängers übergeben. Das dem Nutzer zu Verfügung stehende Speichervolumen für das Hochladen der verschlüsselten Client-Mails wird über die Schnittstelle `I_AccountLimit_Service` am Account Manager abgefragt. Somit sind alle drei Teilkomponenten des Fachdienstes an den Anwendungsfällen "Mail senden" und "Mail empfangen" beteiligt. Die durch das Clientmodul am Fachdienst im Rahmen des jeweiligen Anwendungsfalles aufgerufenen Operationen sind in der folgenden Abbildung dargestellt.
 
@@ -163,12 +143,31 @@ Das folgende Sequenzdiagramm stellt den Ablauf des Empfanges einer Nachricht dar
 </p>
 ++++
 
+== Anwendungskennzeichen
+KIM-Teilnehmer können über das Frontend (GUI) des Administrationsmoduls Anwendungskennzeichen für ihren e-Mail Account konfigurieren oder einsehen. Für das konfigurieren eines oder mehrerer Anwendungskennzeichen ruft das Administrationsmodul die Operation `setAccount()` an der Schnittstelle `I_AccountManager_Service` des Account Managers seines KIM Fachdienstes auf, der diese dann im Verzeichnisdienst in den KIM-Fachdaten für die betroffene Mail-Adresse einträgt. Für das Abfragen von konfigurierten Anwendungskennzeichen wird die Operation `getAccount()` an der Schnittstelle `I_AccountManager_Service` am Account Manager verwendet. Für jede Operation baut das Administrationsmodul eine TLS-Verbindung zum Account Manager auf. 
+
+Im folgenden Sequenzdiagramm ist die Interaktion zwischen Administrationsmodul und dem Account Manager dargestellt.
+
+++++
+<p align="center">
+  <img width="55%" src=../images/diagrams/Fachdienst/Seq_acc_anwendungskennzeichen.svg>
+</p>
+++++
+
 == KIM-Dienstkennung
 Der KIM-Teilnehmer kann eine zu versendende Nachricht mit einer Dienstkennung - z. B. "eAU;Lieferung;v1.0" - versehen. Wird durch den Mailclient in der für den Versand durch das Clientmodul übergebenen Mail keine Dienstkennung eingetragen, wird vom Clientmodul ein default-Dienstkennung nachträglich ergänzt ("KIM-Mail;Default;V1.0").
 Die Dienstkennung wird in den Nachrichten-Header eingetragen, und kann auf der Empfängerseite für eine automatisierte Bearbeitung verwendet werden. Der Bezeichner des hierfür vorgesehenen Header-Feldes lautet `X-KIM-Dienstkennung`. Die Dienstkennung der ursprünglichen Mail wird nach der Verschlüsselung in den Header der verschlüsselten Mail übernommen. Ein Empfänger kann auf Basis der Dienstkennung entscheiden, wie er mit den zur Abholung auf dem Mail-Server bereitstehenden Nachrichten verfahren möchte. 
 
-== KIM Anwendungskennzeichen
-Der KIM-Teilnehmer kann für seinen e-Mail Account Anwendungskennzeichen konfigurieren, die dann durch den Acount Manager seines KIM Fachdienstes im Verzeichnisdienst in den KIM-Fachdaten für die betroffene Mail-Adresse eintragen werden. Der KIM-Teilnehmer nutzt dazu die in seinem KIM Clientmodule angebotene Konfigurations-Option. Für die Übertragung zum Verzeichnisdienst stellt der KIM Fachdienst eine Operation an der Schnittstelle `I_AccountManager_Service` des Account Manager zur Verfügung.
+== Abwesenheitnotizen
+KIM-Teilnehmer können über das Frontend (GUI) des Administrationsmoduls Abwesenheitsnotizen für einen definierten Zeitraum konfigurieren oder einsehen. Für das konfigurieren einer Abwesenheitsnotiz ruft das Administrationsmodul `updateOutOfOffice()` am Account Manager auf. Für das Abfragen von konfigurierten Abwesenheitsnotizen wird die Operation `getOutOfOffice()` am Account Manager verwendet. Für jede Operation baut das Administrationsmodul eine TLS-Verbindung zum Account Manager auf. 
+
+Im folgenden Sequenzdiagramm ist die Interaktion zwischen Administrationsmodul und dem Account Manager dargestellt.
+
+++++
+<p align="center">
+  <img width="55%" src=../images/diagrams/Fachdienst/Seq_acc_abwesenheitsnotiz.svg>
+</p>
+++++
 
 == Multikonnektor Umgebungen
 Ab KIM 1.5 ist es möglich, dass mehrere Konnektoren in einer Umgebung von einem Clientmodul unterstützt werden. Dies ist vor allem im Krankenhausumfeld im Interesse einer notwendigen Lastverteilung sinnvoll. Das folgende Bild veranschaulicht den Einsatz von mehreren Konnektoren in einer Umgebung:

docs/KIM_API.adoc

@@ -24,6 +24,11 @@ Für die automatisierte Auswertung der KIM-Mails auf Seiten des Empfängers werd
 
 Eine Übersicht über alle Dienstkennungen kann hier eingesehen werden: link:https://fachportal.gematik.de/toolkit/dienstkennung-kim-kom-le[Dienstkennungen]
 
+=== Umgang mit Anwendungskennzeichen (ab KIM 1.5.3)
+
+Für die geziehlte Auswahl einer KIM E-Mail-Adresse können die im TI VZD (LDAP) hinterlegten Adressen mit einem Anwendungskennzeichen versehen werden. So kann z. B. sichergestellt werden, dass eine gesendete Nachricht an diese KIM E-Mail-Adresse durch den Empfänger verarbeitet werden kann. Es können für eine KIM E-Mail-Adresse mehrere Anwendungskennzeichen hinterlegt werden. +
+Neben den auf eine explizite Anwendung bezogenen Anwendungskennzeichen wird ein Standard Anwendungskennzeichen konfiguriert. Dieses ermöglicht es, den Empfang von Nachrichten sicherzustellen, auch wenn kein passendes Anwendungskennzeichen gefunden wurde. Jeder Fachdiensteintrag (FAD) innerhalb eines Verzeichnisdiensteintrages (mit TelematikID) *MUSS eine* KIM E-Mail-Adresse mit einem Standard Anwendungskennzeichen besitzen. Wird eine KIM E-Mail-Adresse, die das Standard Anwendungskennzeichen zugewiesen hat, gelöscht, dann *MUSS* sichergestellt werden, dass eine Zuweisung für eine andere KIM E-Mail-Adresse im selben FAD eine Neuvergabe erfolgt. Das vor Ort befindliche KIM Clientmodul (Administrations-Modul) stellt die dafür notwendige Oberfläche bereit.
+
 === Umgang mit großen Anhängen
 
 E-Mails mit einer Gesamtgröße bis zu 15 MiB werden entsprechend den Festlegungen im KIM 1.0 behandelt. Übersteigt die Größe einer E-Mail die 15 MiB Grenze, wird die gesamte Client-Mail, durch das Clientmodul des Senders verschlüsselt, auf dem KIM-Attachment-Service (KAS) des Fachdiensts des Absenders abgelegt. Das Clientmodul ersetzt den Body der originalen Mail mit der KIM-Attachment Datenstruktur (*[gemSpec_CM_KOMLE#Tabelle 2]*) und versendet diese nach der weiteren Verarbeitung durch das Clientmodul als KIM Nachricht an den Fachdienst. Das KIM-Clientmodul des Empfängers erkennt den `link` in der KIM-Attachment Datenstruktur, lädt die E-Mail-Daten vom KAS des Absenders und entschlüsselt sie. Die damit wieder hergestellte originale Client-Mail wird dem Mail-Client des Empfängers zugestellt. Der Umgang mit großen Anhängen ist in *[gemSpec_CM_KOMLE#3.2]* spezifiziert. Die vom KAS dazu bereitgestellte Schnittstelle wird im folgenden genauer beschrieben.

docs/Primaersystem.adoc

@@ -118,6 +118,21 @@ Es ist erforderlich, dass das Primärsystem dem Benutzer ermöglicht eine KIM-E-
 Die Nachrichten müssen konform zu RFC5322 erzeugt werden (https://www.rfc-editor.org/rfc/rfc5322.html[RFC5322]). Dies gilt insbesondere für die Header-Elemente der Mail-Nachricht.
 Die message-id ist für KIM-Nachrichten nicht optional und muss gemäß https://www.rfc-editor.org/rfc/rfc5322.html#section-3.6.4[RFC5322 Kapitel 3.6.4] erzeugt werden.
 
+* *Anhänge* +
+Werden Anhänge zusammen mit einer KIM-E-Mail übertragen, ist bei der Benahmung der (https://www.rfc-editor.org/rfc/rfc2047.html[RFC2047]) einzuhalten. Das heißt, werden Anhänge deren Dateinamen Umlaute enthalten, genutzt, muss dieser, wie im RFC gefordert, vollständig UTF-8 kodiert in den Nachrichten Body eingetrage werden. Es folgt ein Beispiel mit dem Dateinamen `Handbuch-ÄÜÖß.pdf`.
+
+*Beispiel für eine korrekte UTF-8 Kodierung*
+----
+     Content-Type: application/pdf; name="=?UTF-8?B?SGFuZGJ1Y2gtw4TDnMOWw58ucGRm?="
+
+     Content-Disposition: attachment;
+
+      filename*0*=UTF-8''%48%61%6E%64%62%75%63%68%2D%C3%84%C3%9C%C3%96%C3%9F%2E;
+
+      filename*1*=%70%64%66
+----
+`Hinweis: Im Beispiel wird gezeigt, wie die korrekte Trennung des filename erfolgt, um der Empfehlung nachzukommen, die maximale Zeilelänge zu bgrenzen.` 
+
 * *E-Mail-Kategorisierung im Primärsystem* +
 Es ist erforderlich, dass das Primärsystem dem Benutzer ermöglicht, eine KIM-E-Mail entsprechend zu kategorisieren. Erfolgt keine Kategorisierung durch den Nutzer, wird automatisch vom Clientmodul eine Standard-Kategorie verwendet. Die Kategorien können aus dem link:https://fachportal.gematik.de/service/dienstkennung-kim-kom-le/[Fachportal] der gematik entnommen werden und abhängig von der zu versendenden Nachricht in dem Attribut `X-KIM-Dienstkennung` als zusätzliches Header Element in die Nachricht eingetragen.