Die 3CX Telefonanlage lässt sich einfach und komfortabel per Webadminitration verwalten. Doch ab einer gewissen Größe oder bei häufigen Änderungen kann es dennoch viel Zeit und Nerven kosten. Hierfür gibt es die Call Control API, mit der wir die 3CX vollständig verwalten können. Und da die API auf .Net und C# basiert, können wir auch PowerShell nutzen um auf die API zuzugreifen.
Mit der Call Control API lassen sich viele Szenarien realisieren. So können Sie zum Beispiel einen Import von Nebenstellen aus einer beliebigen Quelle nach exakt Ihren Vorgaben regelmäßig und automatisiert umsetzen. Oder es lassen sich Nebenstellen zu Signalisierungsgruppen nach einem Dienstplan hinzufügen oder der Status von Nebenstellen lässt sich anhand eines Zeiterfassungssystem automatisch anpassen. Die Möglichkeiten sind vielfälltig.
Aber Schritt für Schritt. Zunächst gibt es ein paar Einschränkungen zu beachten. Die API ist nur auf dem Server verfügbar und akzeptiert Verbindungen nur von der IP 127.0.0.1. Die API steht zudem nur den "kommerziellen" Versionen zur Verfügung. Was das genau das bedeutet ergibt sich aus der Beschreibung von 3CX jedoch nicht. Früher stand die API erst ab der Pro zur Verfügung.
Fangen wir an - 3CX Call Control API initialisieren
Zunächst muss die API in der PowerShell (ab V16 muss es die Power Shell Core-Konsole sein) Konsole geladen werden. Dazu definieren wir den Pfad zur API-DLL in einer Variable und nutzen die PowerShell-Funktion Add-Type.
$path="C:\Program Files\3CX Phone System\Instance1\Bin\3cxpscomcpp2.dll"
Add-Type -Path $path
Damit kennt nun die PowerShell die API und bietet uns auch die Autovervollstänigung an.
Nun kommt das eigentliche Initialisieren. Dazu brauchen wir ein paar Informationen. Diese finden sich unter Windows standardmäßig unter C:\Program Files\3CX Phone System\Instance1\Bin\3CXPhoneSystem.ini im Abschnitt [ConfService]. Wir initialiseren die API in PowerShell wie folgt:
$ps = [TCX.Configuration.PhoneSystem]
$ps::CfgServerHost = "127.0.0.1" #Standadwert
$ps::CfgServerPort = 5485 #Standadwert
$ps::CfgServerUser = "ConfUser" #Hier ist der entsprechende Wert zu ersetzen
$ps::CfgServerPassword = "confPass" #Hier ist der entsprechende Wert zu ersetzen
$ps::ApplicationName = "My3CXApp" #Hier geben Sie Ihrem Scipt einen eindeutigen Namen. In diesem Context laufen alle Ihre Änderungen
Damit sind wir eigentlich bereit, alle Möglichkeiten der Call Control API mit PowerShell zu nutzen. Eine Übersicht der API und etliche Codebeispiele, allerdings für C#, finden sich im 3CX API Documentation Package for 3CX V18.
Ein einfaches Beispiel - Eine Nebenstelle einer Signalisierungsgruppe hinzufügen
Um den Einstieg zu erleichtern, möchten wir ein kurzes Beispiel zeigen. Hier fügen wir einer bestehenden Signalisierungsgruppe einfach eine neue Nebenstelle hinzu.
$t = $ps::Root.GetTenants()[0] # Läd sozusagen den Mandanten, der die wichtigsten Funktionen bereitstellt
$rg = $t.GetRingGroups() # Lädt alle Signalisierungsgruppen in eine Variable
$ext = $t.GetExtensions() # Lädt alle Nebenstellen in eine Variable
$rg[0].Members += ($ext[5]) # Fügt der ersten Signalisierungsgruppe im Array $rg die Nebenstelle an Position 5 des Arrays mit den Nebenstellen hinzu.
$rg[0].Save() # Speichert die Änderung an der Signalisierungsgruppe
Das ist ein sehr einfaches Beispiel. Es lassen sich aber beliebig komplexe Szenarien realisieren.
Ein Problem über das wir gleich zu Anfang gestolpert sind, war, dass Arrays in Powershell. eine fixe Größe haben. Wir können also weder die Funktion Add noch Remove nutzen, stattdessen müssen wir das Array noch definieren und überschreiben. Eine gute Erklärung zu genau diesem Verhalten mit Arrays in Powershell findet sich hier: https://www.sapien.com/blog/2014/11/18/removing-objects-from-arrays-in-powershell/
Jeder der etwas Erfahrung mit PowerShell und C# hat, wird sich recht schnell mit der Call Control API zurechtfinden und kann dann die 3CX ganz nach seinem Belieben automatisieren. Natürlich können per C# auch direkt Anwendungen entwickelt werden. Der Charm, dies mit PowerShell zu realsieren, liegt eher darin begründet, dass sich diese Methode eher an Administratoren richtet und Skripte leicht angepasst werden können ohne eine Entwicklungsumgebung wie Visual Studio zu benötigen.
Schreibt uns gerne Eure Erfahrungen mit der Call Control API und auch ob PowerShell für Euch eine attraktive Möglichkeit ist.