Service Desk Chat Relay

Beschreibung

Das Relay ermöglicht eine bidirektionale Kommunikation zwischen Microsoft Teams und Ihrer Matrix42 Umgebung oder zwischen Ihrer Webseite und Ihrer Matrix42 Umgebung. Es kann entweder als Windows-Dienst oder als Docker-Container gehostet werden. Das Relay kann ebenfalls von Matrix42 System genutzt werden, welche keinen direkten Internetzugriff haben.

Hosting-Optionen

Windows-Dienst

Der Windows-Dienst kann in der Public Cloud auf einem Windows Server in der DMZ oder auf dem App Server gehostet werden, wenn dieser aus dem Internet erreichbar ist.

Docker-Container

Der Docker-Container kann in Azure oder in der DMZ gehostet werden.

Anforderungen

Der Applikationsserver benötigt Zugriff auf das Relay.
Das Relay muss sowohl vom Matrix42 Applikationsserver als auch ggf. von Microsoft erreichbar sein.
Die Veröffentlichung sollte über TLS/Https erfolgen, idealerweise über einen Loadbalancer mit WebSocket-Reverse-Proxy-Funktion.
Service Desk Chat Relay Binaries
- Kontaktieren Sie den Produktsupport von Labtagon, um die Relay Binaries zu erhalten. Sollten Sie einen Docker-Container hosten wollen, können Sie entweder „labtagon/service-desk-chat-relay:latest“ als Image nutzen oder Sie kontaktieren unseren Produktsupport, um Informationen zur neusten Version zu erhalten. Beachten Sie, dass bei „labtagon/service-desk-chat-relay:latest“ das Image automatisch upgedatet wird, sobald wir eine neue Version veröffentlichen.

Erstellen des Azure Bots für das Microsoft Teams Relay

Sie können den Azure Bot über Ihr Azure Portal erstellen. Falls Sie zu unserer Dokumentation noch Hilfe benötigen, bietet sich folgender Artikel von Microsoft an (Create a bot in Azure – Bot Framework Composer | Microsoft Learn). Sollten Sie weiterhin Hilfe benötigen, können Sie unseren Support gerne kontaktieren. Folgende Schritte müssen Sie durchführen, um Ihren Azure Bot zu erstellen:

Erstellen einer Ressource:
- Navigieren Sie in das Azure-Portal (https://portal.azure.com/) und erstellen Sie eine neue Ressource.
- Wählen Sie „Bot Services“ aus und erstellen Sie einen neuen Azure Bot.
Bot erstellen:
- Geben sie unter Bot-Handle den technischen Namen des Bots ein. Dieser Name wird den Endnutzern nicht angezeigt.
- Wählen Sie das Abonnement und die Ressourcengruppe aus.
- Ändern Sie die Datenresidenz auf Ihre gewünschte Option.
- Wechseln Sie zu dem kostenfreien Tarif.
- Wählen Sie die Option „Single Tenant“ aus.
- Generieren Sie eine neue Microsoft App ID oder hinterlegen Sie eine vorhandene App. Merken Sie sich die AppId, da sie für die Konfiguration benötigt wird.
- Drücken Sie auf „Überprüfen + erstellen“.
Jährliche Aktualisierung des App Passworts:
- Beachten Sie, dass das App Passwort jedes Jahr erneuert werden muss.
Bot Profil konfigurieren:
- Geben Sie Ihrem Bot einen Namen und wählen Sie ein passendes Icon aus.
- Beachten Sie, dass sich der Name und das Icon im Nachgang nicht mehr ändern lässt.
Konfiguration des Endpoints:
- Gehen Sie zur Konfiguration und kopieren Sie die Endpoint-URL des Relay mit dem Zusatz „/api/messages“. Im unteren Beispiel mit dem Windows Dienst wäre es dann „/teams/api/messages“.
- Aktivieren Sie den Streamingendpunkt.
- Konfigurieren Sie zusätzlich einen Reverse Proxy darauf.
Teams hinzufügen – Commercial:
- Fügen Sie Microsoft Teams als Kanal dem Bot hinzu und wählen Sie die kommerzielle Version aus. Den Kanal finden Sie dann unter verfügbare Kanäle.
Client Secret generieren:
- Gehen Sie zur Konfiguration und wählen Sie „Manage Password“.
- Generieren Sie das Client Secret und kopieren Sie den generierten Wert.

Microsoft Teams App Erstellung

Dieser Guide dient Ihnen zur Erstellung einer Microsoft Teams App. Diese App wird automatisch den Chat des Bots öffnen. Bedenken Sie bitte, dass der Bot erst genutzt werden kann, wenn der Azure Bot und das Relay vollständig konfiguriert ist, ggf. ist der Schritt „Konfiguration eines Windows Dienstes“ noch notwendig.

Öffnen Sie zuerst das Entwicklungsportal von Microsoft in Teams. Sollten Sie das Entwicklungsportal noch nicht installiert haben, laden Sie dieses herunter.

Gehen Sie anschließend im Entwicklungsportal auf den Tab Apps und erstellen Sie eine neue App.

Wenn Sie auf den Button „Neue App“ geklickt haben, öffnet sich folgende Ansicht. Dort müssen Sie den Namen Ihrer App hinterlegen. Dieser Name wird den Endnutzern als App-Namen angezeigt, wie bspw. Kalender.

Danach klicken Sie auf Hinzufügen und im Anschluss öffnet sich dann folgende Ansicht. Dort können Sie unter „Grundlegende Informationen“ die allgemeinen Informationen zu Ihrer App hinterlegen.

Die Anwendungs Client ID können Sie sich aus dem Azure Portal ziehen. Gehen Sie dazu auf Ihren Bot und klicken Sie dort auf Konfiguration. Kopieren Sie die Microsoft App ID und fügen Sie diese unter Anwendungs Client ID ein.

Unter Branding können Sie die Symbole/Icons für die App festlegen.

Danach unter App Features einen Bot hinzufügen.

Nun können Sie unter „Geben Sie eine Bot-ID ein“ die Bot-ID hinterlegen. Diese Bot-ID ist gleichzustellen mit der Microsoft App ID, Portal kopiert hatten. Anschließend muss noch „Personal“ unter der Bereichsauswahl ausgewählt werden. Im Anschluss noch speichern.

Optional können Sie nun noch Sprachen hinzufügen, welche der Bot unterstützt. Diese müssten mit den konfigurierten Sprachen im Bot (aktuell Deutsch und Englisch) und den Sprachen, welche in der Willkommensrelay-Nachricht in der Service Desk Chat Konfiguration in Matrix42 ESM, hinterlegt sind.

Veröffentlichen Sie die App über den Button oben rechts in der Ecke. Dort können Sie dann festlegen, ob Sie die App in Ihrer Organisation oder im Teams Store veröffentlichen wollen.

Sollten Sie die App in Ihrer Organisation veröffentlichen wollen, könnte es sein, dass die App durch Sie noch separat im Microsoft Teams Admin Center unter „Teams Apps“ -> „Manage Apps“ veröffentlicht und entblockt werden muss. Beachte, dass diese Änderungen ggf. erst nach einem halben Tag in Teams ankommen. Es könnte auch sein, dass ein Neustart von Teams erforderlich ist.

Alternativ können Sie die App für sich persönlich austesten, indem Sie beim Veröffentlichen auf „Herunterladen des App-Pakets“ klicken. Folgen Sie danach dem folgenden Guide von Microsoft (Hochladen Ihrer benutzerdefinierten App – Teams | Microsoft Learn).

Konfiguration eines Windows Dienstes

Hinweis: Das Relay kann auf dem Appserver installiert werden, allerdings muss wenigstens auf den virtuell erstellten Ordner Zugriff von Azure aus möglich sein. Bitte entsprechende Firewallregeln / Routen implementieren.

Folgen Sie den nachstehenden Schritten, um das Relay als Windows Dienst zu konfigurieren.

IIS konfigurieren – Application Request Routing 3.0 installieren – Teams Relay

Application Request Routing (kurz ARR) über den Web Plattform Installer direkt im IIS installieren oder bei Microsoft herunterladen (z.B.Download Microsoft Application Request Routing 3.0 (x64) from Official Microsoft Download Center) und installieren.

Um ARR konfigurieren zu können, gehen Sie zuerst auf den Server und
ARR 3.0 wird im IIS auf der Eigenschaftseite des Servers konfiguriert:

IIS konfigurieren – virtuellen Ordner anlegen und konfigurieren – Teams Relay

Legen Sie nun unter der Default Website des Servers einen neuen virtuellen Ordner an. (z.B. /teams)

In diesen virtuellen Ordner „Anonymous Authentication“ unter „Authentication“ aktivieren.

Nun bei URL Rewrite eine neue Inbound Regel hinzufügen und wie im folgendem Bild konfigurieren.

Hinweis: anstelle des hier verwendeten Ports kann auch ein anderer verwendet werden, dann entsprechend die Relay Config anpassen.

Nun sollte die web.config des virtuellen Ordners wie folgt aussehen:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<system.webServer>
<rewrite>
<rules>
<rule name="TeamsEndpoint" patternSyntax="ExactMatch" stopProcessing="true">
<match url="api/messages" />
<action type="Rewrite" url="http://localhost:5001/api/messages" appendQueryString="true" />
</rule>

</rules>
</rewrite>
<security>
<authentication>
<anonymousAuthentication enabled="true" />
</authentication>
</security>
</system.webServer>
</configuration>

Service Desk Relay installieren

Erhaltenes Relay Archiv extrahieren:
- Extrahieren Sie das Archiv an einen beliebigen Ort, z.B. ‚C:/ServiceDeskChatRelay‘
PowerShell als Administrator öffnen:
- Navigieren Sie zum extrahierten Ordner und führen Sie den folgenden Befehl aus, um den Service zu installieren:
- $binaryPath = Resolve-Path .\Labtagon.ServiceDeskChat.Relay.exe $workingFolder = [System.IO.Path]::GetDirectoryName($binaryPath) sc.exe delete LabtagonServiceDeskChatRelay sc.exe create LabtagonServiceDeskChatRelay binpath=“$binaryPath –contentRoot ‚$workingFolder'“ start=auto
Konfigurieren des Relays
- Generieren Sie sich ein beliebiges Relay Secret (Bspw. Über einen Passwortgenerator). Dieses hinterlegen Sie im Anschluss in der appsettings.JSON und in Ihrer Maztrix42 DWP.
- Setzen Sie die erforderlichen Felder in der appsettings.JSON des entpackten Service Desk Chat Relay.
- Erforderlich für das externe Webseiten Relay:
  - „ExternalChatRelay:Enabled“: true
  - „ListenEndpoint“: z.B.: „http://0.0.0.0:5001“ (im IIS festgelegten Port verwenden)
  - „RelaySecret“: ein selbst erstelltes Secret
  - „AllowedOrigins“: Liste aller Adressen, welche Zugriff auf Ressourcen des Relays erhalten sollen. Zum Beispiel: „http://0.0.0.0:5001“. Es ist auch möglich eine Wildcard zu setzen.
- Erforderlich für das Microsoft Teams Relay:
  - „TeamsRelay:Enabled“: true
  - „RelaySecret“: Gerade erstelltes Relay Secret
  - „ListenEndpoint“: z.B.: „http://0.0.0.0:5001“ (im IIS festgelegten Port verwenden)
  - „MicrosoftAppId“,
  - „MicrosoftAppTenantId“,
  - „MicrosoftAppType“
  - Diese Informationen („MicrosoftAppId“, „MicrosoftAppTenantId“, „MicrosoftAppType“) können Sie im Azure Portal (https://portal.azure.com/) aus Ihrem Azure Bot entnehmen.
  - „MicrosoftAppPassword“: Kann nur direkt bei Erstellung kopiert werden auf der Azure Portalseite. Andernfalls können Sie ein neues App Passwort erstellen. Dazu gehen Sie in ihrem Bot im Azure Portal unter Konfiguration und klicken unter Microsoft App ID auf „Kennwort verwalten“. Dort können Sie sich einen neuen Clientschlüssel erstellen. Beachte, dass du diesen Clientschlüssel nur nach direkter Anlegung kopieren kannst.
- Weitere Konfigurationsmöglichkeiten (in der appsettings.json konfigurierbar):
  - „KeepAliveInterval“: Dies ist das Zeitintervall, in dem der Server eine „Keep-Alive“-Nachricht an den Client sendet, um die Verbindung aktiv zu halten, auch wenn keine Daten ausgetauscht werden.
  - „ClientTimeoutInterval“: Dieses Intervall gibt an, wie lange der Server wartet, bevor er eine inaktive Client-Verbindung als abgebrochen betrachtet und sie schließt.
  - „HandshakeTimeout“: Dies ist die Zeit, die der Server wartet, um eine erfolgreiche Handshake-Phase (z.B. beim Aufbau einer sicheren Verbindung) abzuschließen. Falls der Handshake innerhalb des festgelegten Zeitlimits nicht abgeschlossen wird (z.B. wegen Netzwerkproblemen oder einer nicht erfolgreichen Authentifizierung), wird die Verbindung abgebrochen.
  - „ClientServerTransportType“: Legt den Transport Typ der Anfragen und Antworten vom Relay zum Matrix42 System fest. Die Transport Typen sind unter diesem Link definiert. Zwischen folgenden Transport Typen können Sie wählen:
    - WebSockets: 1
    - ServerSentEvents: 2
    - LongPolling: 4
Starten des Windows Dienstes

Direkt im Ordner des Relays wird bei erfolgreichem Start ein Ordner „Log“ mit den Logfiles angelegt.

Konfiguration des Docker Containers

Die Konfiguration des Docker Containers ist auf folgender Seite dokumentiert (labtagon/service-desk-chat-relay – Docker Image | Docker Hub).

Beachten Sie, dass bei Verwendung von „labtagon/service-desk-chat-relay:latest“ das Image automatisch upgedatet wird, sobald wir eine neue Version veröffentlichen.

Konfiguration Ihrer Matrix42 DWP

Weitere Informationen zu der Konfiguration des Relays in Ihrer Matrix42 DWP finden Sie unter „Service Desk Chat Konfigurationen“ .

Formatierungsmöglichkeiten in Nachrichten

Folgende Formatierungsmöglichkeiten und Dateianhänge sind zwischen Microsoft Teams und Ihrer Matrix42 Umgebung oder zwischen Ihrer Webseite und Ihrer Matrix42 Umgebung möglich:

Styles	M42 ESM -> Microsoft Teams	Microsoft Teams -> M42 ESM	M42 ESM -> Ihre Webseite	Ihre Webseite -> M42 ESM	Notizen
Fett	✓	✓	✓	❌
Kursiv	✓	✓	✓	❌
Unterstrichen	❌	✓	✓	❌
Textfarbe ändern	✓	✓	✓	❌
Hintergrundfarbe	✓	✓	✓	❌
Tab einrücken	❌	✓	✓	❌
Emojis	✓	✓	✓	✓
Gifs	❌	✓	❌	❌
Bilder	✓	❌	❌	❌	Bild darf max. 15MB groß sein
Videos	❌	❌	❌	❌
Links	✓	✓	✓	❌