Teams UserCallingSettings

Anwender können in Teams einstellen, wie eingehende Anrufe z.B. weitergeleitet werden. Bei Skype for Business und Lync musste ein Administrator das Programm SEFAUtil einrichten. In Teams geht das per PowerShell.

Benutzeransicht

Die folgenden Einstellungen kann ein Anwender in seinem Teams-Client nutzen, wenn Sie mit Teams Telefonieren, d.h. eine "Phone System"-Lizenz haben.

Der Benutzer hat die "Hoheit" über seinen eigenen Telefonanschluss. Das ist mit den Posteingangsregeln für das eigene Postfach vergleichbar.

Teams PowerShell

Es gibt aktuell keine GUI für den Administrator zur Einstellung dieser Umleitungen beim Benutzer. Aber über die neue Teams PowerShell gibt es in einigen Versionen die passenden Commandlets:

Allerdings ist aktuell (Jan 2022) der Zugang etwas knifflig, denn auch wenn Skype for Business Online mittlerweile Geschichte ist und es eigentlich nur noch die Teams PowerShell geben sollte, nutzen viele Administratoren noch die Skype for Business Powershell oder verschiedene Versionen der Teams Powershell. Wenn Sie auf ihrem Admin-PC immer nur ein "Install-Module MicrosoftTeams" machen, dann sieht es schnell wie bei mir aus.

PS C:\> Get-installedModule microsoftteams -AllVersions | ft version,name,installedlocation

Version       Name           InstalledLocation
-------       ----           -----------------
2.5.1         MicrosoftTeams C:\....\WindowsPowerShell\Modules\MicrosoftTeams\2.5.1
2.6.0         MicrosoftTeams C:\....\WindowsPowerShell\Modules\MicrosoftTeams\2.6.0
3.0.1-preview MicrosoftTeams C:\....\WindowsPowerShell\Modules\MicrosoftTeams\3.0.1
3.1.0         MicrosoftTeams C:\....\WindowsPowerShell\Modules\MicrosoftTeams\3.1.0

Leider sind die Befehle relativ neu und nicht in jeder PowerShell vorhanden.

2.5.1 GA        nicht enthalten
2.6.0 GA        nicht enthalten
2.6.1 Preview   Get-CsUserCallingSettings dazu gekommen
2.6.2 Preview > Set-CsUserCallingSettings dazu gekommen
3.0.0 GA        nicht enthalten
3.0.1 Preview   Get/Set-CsUserCallingSettings wieder enthalten
3.1.0 GA        nicht enthalten

Sie sehen schon, dass es die Commandlets noch nicht in die finale GA-Version geschafft haben. Oft ist das ein Zeichen, dass der Code oder das Backend noch nicht robust oder statisch genug sind. Auch in der Dokumentation steht immer noch ein "Preview":

Für uns Administratoren bedeutet dies einfach nur, dass wir neben der primären PowerShell ggfls. noch eine "preview"-Version nebendran installieren müssen. Das funktionierte bei mir übrigens problemlos, dass ich ein "Connect-MicrosoftTeams" mit der Version 3.1.0 gemacht habe und dann die Preview-Commandlets genutzt habe, die in der GA-Version nicht vorhanden sind. Allerdings kann ich so nicht die Commandlets der 3.0.1 nutzen, die den gleichen Namen wie in der 3.1.0 tragen. Wenn ich das wollte, müsste ich eine der beiden Module mit einem Prefix versehen.

Für die Installation der "Preview"-Version müssen Sie den Parameter "-AllowPrerelease" nutzen. Wenn es schon eine neuere Teams PowerShell gibt, brauchen Sie noch ein "-Force", damit die ältere Preview daneben installiert wird.

Find-Module MicrosoftTeams -AllowPrerelease
Install-Module MicrosoftTeams -AllowPrerelease -Force
Get-Module MicrosoftTeams -ListAvailable

Lesen und Setzen als Admin

Nachdem die Umgebung dann geschaffen ist, kann ich sehr einfach z.B. die Rufeinstellungen eines Benutzers anzeigen lassen

PS C:\> get-CsUserCallingSettings -Identity frank.carius@msxfaq.de

SipUri                    : sip:frank.carius@msxfaq.de
IsForwardingEnabled       : False
ForwardingType            : Simultaneous
ForwardingTarget          :
ForwardingTargetType      : Voicemail
IsUnansweredEnabled       : False
UnansweredTarget          :
UnansweredTargetType      :
UnansweredDelay           : 00:00:40
Delegates                 :
Delegators                :
CallGroupOrder            : Simultaneous
CallGroupTargets          : {}
GroupMembershipDetails    :
GroupNotificationOverride :

Als PowerShell-Objekt kann ich die Daten natürlich auch anderweitig weiter verarbeiten oder exportieren.

Sie haben sicher auch die "Set-*"-Befehle gesehen, mit denen ich als Administrator die Einstellungen auch anpassen kann. Der Benutzer "sieht" das leider nicht direkt und bekommt darüber auch keine Chat-Nachricht oder andere Benachrichtigung. Insofern sollten Sie damit sensibel und offen umgehen.

Background-API

Natürlich habe ich mit Fiddler der PowerShell nachgespürt und bin sehr einfach fündig geworden. Die PowerShell startet einfach einen HTTP-Request. Die Abfrage des aktuellen Status Ist ein einfacher REST-Aufruf mit einer JSON-Antwort:

Die PowerShell bedient sich dabei der folgenden URL:

https://api.interfaces.records.teams.microsoft.com/Skype.VoiceGroup/userRoutingSettings/<UserUPN-Address>

Als Authentication kommt "Bearer" mit dem Adminuser  zum Einsatz aber keine weitere Payload. Die Antwort ist eine komplette JSON-Struktur mit allen Einstellungen des Benutzers zum Thema Call-Routing. Über die gleiche URL werden auch Änderungen als "POST" abgesetzt, bei der in der Payload eine JSON-Struktur mit den Änderungen steht. Hier habe ich absichtlich einen Fehler produziert:

PS C:\> set-CsUserCallingSettings -Identity user@msxfaq.de -IsUnansweredEnabled $true
ParserException/Expected '{' or '['. Was String: If./   
   bei Microsoft.Teams.ConfigAPI.Cmdlets.Generated.Runtime.Json.JsonParser.ReadNode()
   bei Microsoft.Teams.ConfigAPI.Cmdlets.Generated.Runtime.Json.JsonNode.Parse(SourceReader sourceReader)
   bei Microsoft.Teams.ConfigAPI.Cmdlets.Generated.Runtime.Json.JsonNode.Parse(String text)
   bei Microsoft.Teams.ConfigAPI.Cmdlets.Generated.Runtime.RestException..ctor(HttpResponseMessage response)
Microsoft.Teams.ConfigAPI.Cmdlets.internal\Set-CsUserCallingSettings : If selecting call forward type as simultaneous,
target type cannot be voicemail.
In C:\Users\.....WindowsPowerShell\Modules\MicrosoftTeams\3.0.1\net472\custom\Set-CsUserCallingSettings.ps1:105 Zeichen:12

In der PS1-Datei sind aber nur wenige Parameter-Überprüfungen, um dann die eigentliche Funktion zu starten und auch die anderen PS1, PS1M, PS1D u.a. Dateien nutzen PowerShell-Techniken, die ich gar nicht erst verstehen will. Viel Spaß beim Analysieren.

Den HTTP-Request kann ich aber in Fiddler schon anschauen und hier sehe ich auch die in der Fehlermeldung angezeigte Rückantwort "... String: If./..." als HTTP-Response.

Das ist sicher keine valide JSON-Datei und zumindest zu der Zeit war Microsoft im Backend noch nicht ganz fertig. Insofern ist es verständlich, dass diese Commandlets noch "Preview" sind. Es scheint nur ein Teil korrekt zu arbeiten.

Ein Anfang ist gemacht aber eigentlich hätte ich mir gewünscht, dass diese Informationen direkt per Graph auslesbar und änderbar wären.

Weitere Links