Stand der Dokumentation: 28.02.2023

UC-Analytics Version: 13.4.2.06

Vorraussetzungen für die Auswertung von MS Teams Kommunikationsdaten

Freischaltecode / Lizenzierung: Die MS-Teams Datenquelle ist ein kostenpflichtiges Zusatzmodul und kann optional nachgeordert werden. Wenden Sie sich an Ihren Distributor oder an das aurenz Vertriebs-Team.
Administrativen Zugriff auf das Microsoft Azure Portal.
Es gibt 3 verschiedene Anbindungsvarianten. Bitte prüfen Sie vorab, welche Variante Ihre Anforderungen erfüllt bzw. technisch realisierbar ist.
- Call-Records-Schnittstelle:
  Diese Schnittstelle liefert Teams-interne Kommunikationsdaten unabhängig des Anschlusses an das PSTN/ den ITSP.
  --> Achtung: erfordert eine an UC-Analytics angebundene MS SQL Datenbank!
- Direct Routing Calls Schnittstelle:
  Dies ist die korrekte Schnittstelle, wenn MS Teams Telefonie über einen Session Border Controller erfolgt (Direct Routing)
- PSTN Calls Schnittstelle:
  Dies ist die korrekte Schnittstelle, wenn MS Teams Telefonie über einen ITSP Anschluss bei Microsoft erfolgt (Operator Connect oder Dialplan)

Berechtigung in MS-Teams

Microsoft Teams befindet sich in der Cloud. Damit aurenz Zugriff auf die MS-Teams Daten bekommt, müssen entsprechende Berechtigungen erstellt werden. Rufen Sie dazu das Azure Portal auf:

https://portal.azure.com

Melden Sie sich am Portal als Administrator an.

App-Registrierung durchführen

Wählen Sie hier Azure Active Directory

Notieren Sie sich an dieser Stelle die Mandaten-ID. Diese wird später bei der Einrichtung in UC-Analytics/AlwinPro benötigt.

Für den Zugriff auf MS-Teams wird eine spezielle Berechtigung benötigt, die UC-Analytics/AlwinPro als Applikation ausweist und nicht als Anwender. Wählen Sie daher jetzt App-Registrierungen.

Wählen Sie jetzt Neue Registrierung um einen neuen Zugang für eine Applikation anzulegen

Geben Sie nun einen Namen für die Applikation ein. Wählen Sie als Kontotyp Nur Konten in diesem Organisationsverzeichnis. Klicken Sie anschließend auf Registrieren.

Ihnen wird jetzt eine Zusammenfassung der neuen Registrierung angezeigt. Notieren Sie sich hier schon einmal die Anwendungs-ID (Client). Diese wird später in AlwinPro benötigt.
Wählen Sie darin den Link Ein Zertifikat oder Geheimnis hinzufügen.

Als nächstes haben Sie die Auswahl, ob Sie ein Zertifikat hochladen möchten oder einen geheimen Clientschlüssel erstellen wollen. Wählen Sie hier Neuer geheimer Clientschlüssel.

Legen Sie jetzt einen Namen und eine Gültigkeitsdauer des geheimen Schlüssels fest.
Es ist nicht möglich einen Schlüssel zu erstellen, der dauerhaft gültig ist. Schlüssel müssen daher von Zeit zu Zeit neu erstellt und auch in UC-Analytics/AlwinPro aktualisiert werden.

Es werden jetzt der geheime Wert und die geheime ID des Schlüssel angezeigt. Kopieren Sie sich jetzt den geheimen Wert. Der geheime Wert kann zu einem späteren Zeitpunkt nicht mehr angezeigt werden. Sollten Sie den geheimen Wert verlieren, dann müssen Sie den geheimen Schlüssel löschen und einen neuen geheimen Schlüssel erzeugen.

Sie müssen jetzt folgende Werte notiert haben:

Mandanten-ID
Anwendungs ID (Client)
Geheimer Wert

Berechtigung hinzufügen

Im letzten Kapitel haben wir eine App Registrierung für den Zugang zu Microsoft Teams angelegt. Im nächsten Schritt muss dieser App jetzt das Recht für den Zugriff auf die Daten gewährt werden.

Wählen Sie jetzt API-Berechtigungen

Sie sehen jetzt die bereits bestehenden Berechtigungen. Diese reichen aber zum Abruf von Gesprächsdaten nicht aus. Wählen Sie daher Berechtigung hinzufügen.

Sie erhalten jetzt eine Auswahl aller Microsoft APIs, für die eine Berechtigung vergeben werden kann. Wählen Sie hier Microsoft Graph.

Da wir eine Berechtigung für eine Anwendung benötigen und nicht für einen Anwender, wählen Sie jetzt Anwendungsberechtigungen.

Sie erhalten jetzt eine Liste aller möglichen Berechtigungen. Hier müssen Sie drei Berechtigungen wählen:

CallRecords.Read.All
CallRecord-PstnCalls.Read.All
User.Read.All

Wenn Sie alle drei Berechtigungen markiert haben, klicken Sie bitte auf Berechtigungen hinzufügen.

Es wird jetzt wieder die Liste der vergebenen Berechtigungen angezeigt. Für die Berechtigungen wird angezeigt, dass die Berechtigung noch von einem Administrator bestätigt werden muss. Klicken Sie auf Administratorzustimmung erteilen um die Berechtigung wirksam werden zu lassen.

Der Status der Berechtigungen ändert sich jetzt auf gewährt.

Die Vergabe der Zugriffsrechte ist damit abgeschlossen und sie können sich vom Azure Portal abmelden.

Einrichtung von AlwinPro

Übersicht der drei MS Teams Anbindungs-Varianten

Microsoft Teams bietet drei Schnittstellen, über die man Gesprächsdaten abrufen kann:

Call Records Schnittstelle:
Diese Schnittstelle liefert Teams-interne Kommunikationsdaten unabhängig des Anschlusses an das PSTN/ den ITSP.
Direct Routing Calls Schnittstelle:
Dies ist die korrekte Schnittstelle, wenn MS Teams Telefonie über einen Session Border Controller erfolgt (Direct Routing)
PSTN Calls Schnittstelle:
Dies ist die korrekte Schnittstelle, wenn MS Teams Telefonie über einen ITSP Anschluss bei Microsoft erfolgt (Operator Connect oder Dialplan)

Call Records Schnittstelle

Diese Schnittstelle wird in allen Teams Installationen unterstützt, es wird daher keine PSTN-Integration benötigt. Auch Gespräche zwischen Teams-Clients sowie Teams-Meetings werden erfasst. Die Daten dieser Schnittstelle können nur über den Teams Explorer ausgewertet werden. In den Standard UC-Analytics Auswertungen sind die Gespräche dieser Schnittstelle nicht enthalten. Zum Speichern dieser Gespräche ist weiterhin ein SQL Server notwendig, der in den Grundeinstellungen konfiguriert sein muss.

Bei dieser Schnittstelle wird aktiv eine Nachricht von Microsoft Teams an AlwinPro gesendet. Daher muss hier ein Tool in der DMZ ihres Unternehmens installiert werden, welches sowohl aus dem öffentlichen Internet als auch von der AlwinPro Installation aus erreicht werden kann. Details hierzu finden Sie im Kapitel Einrichtung der Call Records Schnittstelle.

Direct Routing Calls Schnittstelle

Diese Schnittstelle benötigt eine PSTN-Integration, sonst werden keine Daten erzeugt. Bei dieser Schnittstelle werden auch Gesprächsversuche gespeichert sowie eine Klingeldauer, so dass Analysen hier möglich sind. Diese Schnittstelle greift direkt auf die Gesprächsdaten zu, so dass keine Installation in der DMZ notwendig ist.
Um Daten für die Direct Routing Schnittstelle auslesen zu können, benötigen Sie einen eigenen Session Border Controller, der von Ihrer Teams Installation genutzt wird. Letztendlich werden die Daten ausgewertet, die über den Session Border Controller laufen. Interne Gespräche können daher nicht ausgewertet werden. Ebenso werden Rufumleitungen, Sammelgruppen usw. nicht erfasst, da dies interne Vorgänge sind.

Die Daten dieser Schnittstelle können Sie mit den Standard UC-Analytics Auswertungen verwenden. Die Daten dieser Schnittstelle können jedoch nicht über den Teams Explorer ausgewertet werden.

PSTN Calls Schnittstelle

Diese Schnittstelle benötigt eine PSTN-Integration, sonst werden keine Daten erzeugt. Diese Schnittstelle greift direkt auf die Gesprächsdaten zu, so dass keine Installation in der DMZ notwendig ist.
Die Daten dieser Schnittstelle können Sie mit den Standard UC-Analytics Auswertungen verwenden. Die Daten dieser Schnittstelle können jedoch nicht über den Teams Explorer ausgewertet werden. Hier werden nur die Daten des PSTN Gateways erfasst. Interne Gespräche, Rufumleitungen und Sammelgruppen werden nicht erkannt.

Einrichtung der Call Records Schnittstelle

Einrichtung des AlwinPro Teams Connectivity Server

Die Einrichtung der AlwinPro Teams Connectivity Server ist nur dann notwendig, wenn Sie die Call Records Schnittstelle nutzen wollen. Bei Verwendung der Direct Routing Calls oder PSTN Calls Schnittstelle entfällt dieser Punkt.

Für den Betrieb von AlwinPro mit der Call Records Schnittstelle ist der AlwinPro Teams Connectivity Server notwendig. Dieser Server wird von Microsoft Teams über die IDs neuer Gesprächsdaten informiert. Dieser Server muss vom öffentlichen Internet und von der AlwinPro Installation aus erreichbar sein. Die Installation erfolgt daher in der Regel auf einem Server in der DMZ des Unternehmens und nicht auf dem AlwinPro Server.

Erzeugen Sie auf dem DMZ-Server ein neues Verzeichnis und kopieren Sie dort den Inhalt des Verzeichnisses AlwinProTeamsServer von der AlwinPro Installations-CD hinein.
Starten Sie AlwinProTeamsServer.exe als Administrator.
Sie sehen jetzt die Einstellmöglichkeiten des Programms:

Legen Sie hier als erstes den Port fest, über den der AlwinPro Teams Connectivity Server erreichbar ist. Ein HTTPS Port muss hier vergeben werden, da Microsoft zurzeit Gesprächsinformationen nur über HTTPS überträgt. Einen HTTP Port können Sie optional zusätzlich festlegen. Klicken Sie anschließend auf Einstellungen speichern.
Für einen HTTPS Zugang ist ein SSL-Zertifikat notwendig. Klicken Sie daher auf SSL-Zertifikat
Für ein SSL-Zertifikat wird ein privater Schlüssel benötigt. Im Auslieferungszustand ist zwar bereits ein privater Schlüssel mit einer Länge von 1024 Bit enthalten, sie sollten aber aus Sicherheitsgründen immer einen eigenen, privaten Schlüssel erzeugen. Wenn Sie eine höhere Sicherheit wünschen, so können Sie hier eine andere Länge des Schlüssels festlegen. Klicken Sie anschließend auf Erzeugen um den privaten Schlüssel zu erzeugen.
Legen Sie im Feld Common Name den Namen fest, unter dem der AlwinPro Teams Connectivity Server vom Internet aus erreichbar ist. Achten Sie darauf, dass der Name wirklich exakt stimmt, sonst ist das Zertifikat später ungültig. Klicken Sie anschließend auf das darunter liegende Erzeugen. Es öffnet sich jetzt ein Fenster, in dem Sie Name und Ort für den erzeugten Zertifikatsrequest angeben können. Lassen Sie diesen Zertifikatsrequest von einer vertrauenswürdigen Zertifizierungsstelle signieren. Sie erhalten damit ein Zertifikat. Achten Sie darauf, dass das Zertifikat im PEM Format erstellt wird (Manchmal auch als Apache-Format bezeichnet). Andere Formate können vom AlwinPro Teams Connectivity Server nicht gelesen werden.
(Optional) Es kann sein, dass die Zertifizierungsstelle von Ihnen verlangt, eine Datei zur Verifikation ihres Servers zur Verfügung zu stellen. Geben Sie dazu bei Web-Pfad den Pfad (ohne Server Namen) an, unter dem die Zertifizierungsstelle die Datei erwartet und laden Sie die Datei mit Hilfe der Upload Schaltfläche hoch. Schließen Sie jetzt die Zertifikatsverwaltung, speichern Sie die Einstellungen und starten Sie den Server, jedoch ohne HTTPS, da zurzeit noch kein gültiges Zertifikat vorhanden ist. Nach Abschluss der Verifikation durch die Zertifizierungsstelle, beenden Sie den Server, aktivieren Sie wieder HTTPS und kehren Sie zur Zertifikatsverwaltung zurück.
Sobald Ihnen ein Zertifikat im PEM-Format vorliegt, Wählen Sie Laden und geben den Dateinamen des Zertifikats an. Das Zertifikat wird jetzt geprüft und im AlwinPro Teams Connectivity Server installiert. Schließen Sie anschließend das Fenster
Sichern Sie jetzt die Dateien alwin.key und alwin.cert aus dem Installationsverzeichnis des AlwinPro Teams Connectivity Servers. Diese Dateien enthalten ihren privaten Schlüssel und ihr Zertifikat. Sollten Sie den AlwinPro Teams Connectivity Server aus irgendeinem Grund neu installieren müssen, müssen Sie auch diese beiden Dateien wieder herstellen, sonst ist ihr Zertifikat verloren und sie müssen ein neues beantragen.
Nachdem Sie wieder ins Hauptfenster zurückgekehrt sind, wählen Sie Einstellungen testen. Sollte dieser Test erfolgreich sein, so können Sie fortfahren, ansonsten müssen Sie den gemeldeten Fehler erst beheben.
Wählen Sie jetzt im Bereich Dienst die Auswahl Installieren.
und im nächsten Schritt dann Starten.
Überprüfen Sie jetzt, ob der Server auch wirklich aus dem Internet und von der AlwinPro Installation aus erreichbar ist. Geben Sie dazu die vergebene URL in einen Web Browser ein. Führen diesen Test unbedingt vom öffentlichen Internet und vom AlwinPro Server aus durch.
Im Erfolgsfall erhalten Sie diese Anzeige:
Der AlwinPro Teams Connectivity Server ist jetzt vollständig installiert. Fahren Sie nun mit der Einrichtung von AlwinPro fort.

Einrichtung der AlwinPro Datenquelle für die Call Record Schnittstelle

Wählen Sie in der Datenaufnahme den Menüpunkt Telefonanlagen > Einstellen und anschließend den Punkt Neu. Wählen Sie nun die Microsoft Teams Datenquelle mit Graph-API
Folgen Sie dem Assistenten und geben Sie die entsprechenden Daten ein
Die Einstellungen der Datenquelle enthält eine Reihe von Registerkarten, wovon nur zwei spezifisch für Microsoft Teams sind:
Verzeichnis Scannen: Hier wird das Verzeichnis angegeben, in dem die von Microsoft heruntergeladenen Gespräche zwischengespeichert werden, bevor sie verarbeitet werden. In der Regel können die Werte so belassen werden, wie sie sind.
Microsoft Teams: Hier sind die Teams-Daten einzutragen
Wählen Sie die Registerkarte Microsoft Teams. Wählen Sie dort als API Call Record.

Die Werte für Mandanten ID, Anwendungs ID und Geheimer Wert entnehmen Sie aus den Einstellungen im Microsoft Azure-Portal, wie oben beschrieben. Für den Zugang zum AlwinPro Teams Connectivity Server geben Sie die jeweilige URL ein, die sie beim Test aus dem letzten Kapitel verwendet haben.
Wählen Sie anschließend Test um die Einstellungen zu überprüfen.
Nach erfolgreichem Test kann die Datenquelle für den Abruf von Daten verwendet werden.

Hinweis: Nach dem Führen eines Gesprächs werden die Daten von Microsoft an den AlwinPro Teams Connectivity Server übertragen. Das Übertragen der Daten erfolgt aber nicht sofort. In unseren Tests haben wir eine Verzögerung von bis zu 20 Minuten festgestellt, wobei die Verzögerung allerdings von Gespräch zu Gespräch stark unterschiedlich war.

Einrichtung der AlwinPro Datenquelle für die Direct Routing Call Schnittstelle oder PSTN Call Schnittstelle

Wählen Sie in der Datenaufnahme den Menüpunkt Telefonanlagen > Einstellen und anschließend den Punkt Neu. Wählen Sie nun die Microsoft Teams Datenquelle mit Graph-API
Folgen Sie dem Assistenten und geben Sie die entsprechenden Daten ein
Die Einstellungen der Datenquelle enthält eine Reihe von Registerkarten, wovon nur zwei spezifisch für Microsoft Teams sind:
Verzeichnis Scannen: Hier wird das Verzeichnis angegeben, in dem die von Microsoft heruntergeladenen Gespräche zwischengespeichert werden, bevor sie verarbeitet werden. In der Regel können die Werte so belassen werden, wie sie sind.
Microsoft Teams: Hier sind die Teams-Daten einzutragen
Wählen Sie die Registerkarte Microsoft Teams. Wählen Sie dort als API Direct routing calls bzw. PSTN Calls

Die Werte für Mandanten ID, Anwendungs ID und Geheimer Wert entnehmen Sie aus den Einstellungen im Microsoft Azure-Portal, wie oben beschrieben.
Wählen Sie anschließend Test um die Einstellungen zu überprüfen.
Nach erfolgreichem Test kann die Datenquelle für den Abruf von Daten verwendet werden.

Hinweis; Microsoft bietet über diese Schnittstelle nicht die Möglichkeit "neue" Gespräche abzurufen. Deshalb werden bei jedem Abwurf alle Gespräche abgerufen, die in den letzten 24 Stunden begonnen haben. Gespräche, die bereits abgerufen wurden, werden anschließend verworfen. Dies bedeutet aber auch, dass Gespräche mit einer Dauer von mehr als 24 Stunden nicht erfasst werden können.

Anschlussbeschreibung Microsoft Teams