Start / Administration

Administration und Betrieb

Für IT und Betrieb · Aufbau, Sicherheit, Dienste, Updates, Fehlersuche

Inhalt

Aufbau und Datenflüsse
Sicherheitskonzept
Hintergrunddienste und Zeitpläne
Der Listener im Betrieb
Updates
Testsysteme und Backups
Einstellungen im Überblick
Fehlersuche

1. Aufbau und Datenflüsse

Browser

ERPNext-Oberfläche, Popup über die Echtzeitverbindung des ERP

↔

ERPNext

App frappe_3cx, Scheduler-Jobs, Listener als Supervisor-Programm

→

3CX V20

XAPI (REST) und Call Control API (REST und WebSocket)

Alle Verbindungen zwischen ERP und 3CX baut das ERP auf, per HTTPS auf Port 443. Die Telefonanlage meldet sich nie von sich aus beim ERP. Dadurch kann das ERP im internen Netz bleiben, und auf der 3CX läuft keine Zusatzsoftware, die ein Update der Anlage überstehen müsste.

Datenfluss	Richtung	Schnittstelle	Häufigkeit
Anrufereignisse (klingelt, angenommen, beendet)	3CX → ERP	Call Control API, WebSocket	laufend
Anrufliste (Berichte)	3CX → ERP	XAPI `ReportCallLogData`	alle 5 Minuten
Kontakte ins Firmentelefonbuch	ERP → 3CX	XAPI `Contacts`	alle 15 Minuten
Anruf starten (Click-to-Call)	ERP → 3CX	Call Control API	bei Bedarf
Nebenstellen, Gruppen, Warteschleifen	3CX → ERP	XAPI	beim Abgleich und beim Start des Listeners

2. Sicherheitskonzept

Thema	Umsetzung
Netz	Nur ausgehende Verbindungen vom ERP zur 3CX. Keine Portfreigabe ins ERP, kein Reverse Proxy, kein VPN auf der Telefonanlage.
Anmeldung an der 3CX	Eigener API-Zugang (Dienstprinzipal) mit Client-ID und Schlüssel. Der Schlüssel liegt verschlüsselt in den ERP-Einstellungen. Das daraus abgeleitete Zugangstoken ist kurzlebig und wird im Redis-Cache des ERP geteilt, damit Scheduler, Listener und Webserver sich nicht gegenseitig abmelden.
Rechte in der 3CX	Die Rolle Systemeigentümer ist nötig, weil die 3CX die Anrufberichte nur dieser Rolle herausgibt. Die Call Control API ist auf die ausgewählten Nebenstellen beschränkt.
Rechte im ERP	Anrufen, Annehmen, Auflegen und Weiterleiten sind nur von eigenen Nebenstellen möglich, der Server prüft das bei jedem Aufruf. Popup-Übersicht und Schnellwahl lesen mit den Rechten des Benutzers. Einstellungen und Listener-Status sind dem System Manager vorbehalten.
Popups	Anrufereignisse gehen gezielt an die Benutzer der klingelnden Nebenstelle, nicht an alle angemeldeten Benutzer.
Alte Webhook-Schnittstelle	Die App enthält noch Endpunkte für das CRM-Template der 3CX, das eine Verbindung von der 3CX ins ERP bräuchte. Sie sind standardmäßig gesperrt: Solange das Feld Webhook-Secret leer ist, weisen sie jede Anfrage ab. Für den hier beschriebenen Betrieb bleibt das Feld leer.

Standard-Nebenstelle: Ist in den Einstellungen eine Standard-Nebenstelle eingetragen, telefonieren alle Benutzer ohne eigene Zuordnung von dieser Nebenstelle aus. Das Feld bleibt leer, solange das nicht ausdrücklich gewollt ist.

3. Hintergrunddienste und Zeitpläne

Dienst	Läuft als	Aufgabe
Anrufliste abgleichen	Scheduler, alle 5 Minuten	Holt Anrufe seit dem jüngsten Eintrag, legt neue an, ergänzt Live-Einträge.
Telefonbuch abgleichen	Scheduler, alle 15 Minuten (Warteschlange long)	Überträgt geänderte ERP-Kontakte in die 3CX.
Listener	Supervisor-Programm `frappe-3cx-callcontrol`	Hält die WebSocket-Verbindung, erzeugt Popups und Live-Einträge im Anrufprotokoll.

Die Scheduler-Jobs laufen nur, wenn der Frappe-Scheduler der Site aktiv ist (bench --site … scheduler status).

4. Der Listener im Betrieb

Steuern

sudo supervisorctl status frappe-3cx-callcontrol
sudo supervisorctl restart frappe-3cx-callcontrol

Ein Neustart ist jederzeit unkritisch. Beim Beenden gibt der Listener seine Sperre sofort frei, der neue Prozess übernimmt ohne Wartezeit. Beim Start liest er die gerade laufenden Gespräche ein, sodass auch Anrufe während des Neustarts korrekt enden.

Nur ein aktiver Listener

Je Site ist immer nur ein Listener aktiv, abgesichert über eine Sperre im Redis-Cache. Startet ein zweiter Prozess, etwa auf einem weiteren Anwendungsserver, wartet er im Zustand Bereitschaft und springt ein, wenn der erste ausfällt.

Verbindungsabbrüche

Reißt die Verbindung zur 3CX ab, zum Beispiel bei einem Update der Anlage, versucht der Listener es erneut: zuerst nach 5 Sekunden, dann mit wachsendem Abstand bis höchstens 5 Minuten. Anrufe aus dieser Zeit ergänzt der 5-Minuten-Abgleich.

Status und Protokolle

Den aktuellen Zustand zeigt Status des Listeners in den Einstellungen:

Status	Bedeutung
Verbunden	Alles in Ordnung. Angezeigt werden verbunden seit, überwachte Nummern, aktive Gespräche, Server und Prozess.
Verbindet neu	Verbindung verloren, der Listener versucht es erneut. Der letzte Fehler steht darunter.
Bereitschaft	Ein anderer Prozess ist aktiv, dieser wartet (Standby).
Deaktiviert	Der Listener läuft, aber Live-Anrufereignisse ist ausgeschaltet.
Läuft nicht	Kein Listener-Prozess, Supervisor-Programm prüfen.

Datei	Inhalt
`logs/frappe_3cx.callcontrol.log`	Verbindungsaufbau und jedes Anrufereignis (klingelt auf welcher Nebenstelle, welche Benutzer bekommen ein Popup, angenommen, beendet).
`logs/threecx-callcontrol.error.log`	Ausgaben des Prozesses bei Abstürzen.
ERP: Error Log	Fehler bei Abgleichen und Anrufaktionen, erkennbar an „3CX" im Titel.

Zum Mitlesen bei einem Testanruf:

tail -f ~/frappe-bench/logs/frappe_3cx.callcontrol.log

5. Updates

cd ~/frappe-bench
bench --site erp.example.com backup
cd apps/frappe_3cx && git pull && cd ../..
bench --site erp.example.com migrate
bench build --app frappe_3cx
sudo supervisorctl restart all

supervisorctl restart all startet auch den Listener neu. Die Oberflächen-Dateien tragen nach dem Build einen neuen Namen, deshalb laden die Browser die neue Version beim nächsten Seitenaufruf automatisch.

6. Testsysteme und Backups

Die 3CX akzeptiert je API-Zugang nur das jüngste Token. Meldet sich ein zweites ERP mit denselben Zugangsdaten an, verliert das erste seine Verbindung. Beide wechseln sich dann ständig ab.

Für ein Testsystem in der 3CX einen eigenen API-Zugang anlegen.
Wird ein Backup des Produktivsystems als Testsystem eingespielt, übernimmt es die produktiven Zugangsdaten. Direkt nach dem Einspielen dort die Integration deaktivieren oder die Zugangsdaten austauschen, bevor Scheduler und Listener laufen.
Den Telefonbuch-Abgleich immer nur von einem System aus betreiben. Zwei Systeme würden sich die verwalteten Einträge gegenseitig überschreiben.

7. Einstellungen im Überblick

Einstellung	Wirkung
Aktiviert	Hauptschalter der Integration.
PBX-URL, Client-ID, Client Secret	Zugang zur 3CX (siehe Installation).
Click-to-Call aktivieren	Telefonsymbole, Button Anrufen und Schnellwahl.
Popup für eingehende Anrufe aktivieren	Popups systemweit. Pro Benutzer und Nebenstelle zusätzlich schaltbar.
Anrufprotokollierung aktivieren	Anrufliste alle 5 Minuten und Live-Einträge.
Telefonbuch-Abgleich aktivieren	Abgleich alle 15 Minuten.
Live-Anrufereignisse aktivieren	Listener arbeitet (Popup und Live-Protokoll).
Mindestanzahl Ziffern, Landesvorwahl	Rufnummernzuordnung, siehe Funktionen im Detail.
Standard-Nebenstelle	Ersatz für Benutzer ohne eigene Nebenstelle, siehe Sicherheitskonzept.
Webhook-Secret	Nur für die alte CRM-Template-Anbindung. Leer lassen.
Warteschlangenverwaltung, Aufnahme-Links	Warteschlangen-Anmeldung steht derzeit nur als Programmierschnittstelle zur Verfügung, ohne eigene Oberfläche. Aufnahme-Links werden bei der hier beschriebenen Anbindung nicht befüllt.

8. Fehlersuche

Symptom	Ursache	Lösung
In der 3CX lässt sich der API-Zugang nicht speichern, ohne Meldung.	Lizenz-Upgrade, die Oberfläche kennt noch die alte Edition.	3CX-Verwaltung komplett neu laden oder neu anmelden.
Verbindungstest schlägt fehl.	URL, Client-ID oder Schlüssel falsch, oder das ERP erreicht die 3CX nicht.	Werte prüfen. Vom ERP-Server aus `curl -I https://ihre-firma.3cx.de` testen.
Anrufliste bleibt leer, Error Log zeigt 403.	API-Zugang hat die Rolle Systemadministrator.	In der 3CX auf Systemeigentümer umstellen.
Immer wieder 401 im Error Log, Listener verbindet sich ständig neu.	Ein zweites System nutzt denselben API-Zugang.	Eigenen Zugang je System anlegen (siehe Testsysteme).
Kein Popup für einen Benutzer.	Keine oder falsche Zuordnung, Popup ausgeschaltet oder kein ERP-Tab offen.	Zuordnung prüfen. Im Listener-Protokoll steht bei jedem Klingeln, welche Benutzer ein Popup bekommen. Steht dort `popup users=-`, fehlt die Zuordnung oder das Popup ist aus.
Kein Popup für niemanden, Status „Läuft nicht".	Supervisor-Programm fehlt oder startet nicht.	`supervisorctl status` und `threecx-callcontrol.error.log` prüfen.
Popup ohne Namen, obwohl der Kontakt existiert.	Nummer im ERP abweichend gepflegt oder kürzer als die Mindestziffern.	Nummer im Kontakt korrigieren, danach Kontakte in Anrufprotokollen neu verknüpfen.
Click-to-Call meldet „Die Nebenstelle … ist Ihrem Benutzer nicht zugeordnet".	Gewünschte Nebenstelle gehört nicht zum Benutzer.	Zuordnung ergänzen oder andere Nebenstelle wählen.
Telefonsymbole und Menüeinträge fehlen nach der Installation.	Browser hat die Seite vor dem Einschalten geladen.	Seite neu laden. Menüeinträge legt `bench migrate` an.
Telefonbuch-Abgleich meldet den Löschschutz.	Es würden ungewöhnlich viele Einträge gelöscht.	Ursache im ERP klären. Ist die Löschung gewollt, einmalig auf dem Server ausführen: `bench --site erp.example.com execute frappe_3cx.threecx.phonebook.sync_phonebook --kwargs '{"force_delete": 1}'`
Anruf klingelt auf einer Nebenstelle, die niemandem gehört.	Die Nebenstelle ist nicht im API-Zugang ausgewählt oder im ERP nicht zugeordnet.	In der 3CX die Nebenstelle im API-Zugang ergänzen, danach den Listener neu starten.

Hilfe bei der Einrichtung oder im Betrieb gibt es bei itsdave.