busylight_modular/docs/starface-modul-anleitung.md

Starface Modulcreator – Busylight Integration

Übersicht

Dieses Modul sendet bei jedem Anruf-Event einen HTTP-Request an den Busylight-Server, damit die Türschilder automatisch den Telefonstatus anzeigen.

Voraussetzungen

• Starface Telefonanlage mit Modulcreator-Lizenz
• Busylight-Server erreichbar unter http://BUSYLIGHT-IP:8081
• Durchwahlen der Mitarbeiter im Busylight-Portal eingetragen

Modul im Modulcreator erstellen

Schritt 1: Neues Modul anlegen

1. Starface Admin-Oberfläche öffnen
2. Admin → Modulcreator (oder Module → Modulcreator)
3. Neues Modul erstellen
4. Modulinformationen:
   • Name: Busylight
   • Beschreibung: Sendet Telefonstatus an Busylight Türschilder
   • Vendor: cynfo GmbH
   • Version: 1.0.0

Schritt 2: Modulkonfiguration (Instanz-Variablen)

Unter Modulkonfiguration folgende Variablen anlegen:

Variable	Typ	Standardwert	Beschreibung
busylight_url	String	http://100.95.224.14:8081	URL des Busylight Webhook-Servers

Schritt 3: Trigger konfigurieren

1. Trigger hinzufügen: Anruf-Trigger (Call Trigger)
2. Trigger-Typ: Bei jedem Anruf oder Call State Changed
3. Richtung: Eingehend + Ausgehend (beide)

Schritt 4: Funktionsablauf erstellen

Der Ablauf hat zwei Zweige:

Zweig A: Anruf beginnt (callstart)

1. Bedingung: Anrufstatus = CONNECTED (Anruf angenommen)
2. Aktion: HTTP Request
   • Methode: GET
   • URL: {busylight_url}/{called_number}/callstart
   • {called_number} = Die Durchwahl des angerufenen Benutzers

Zweig B: Anruf endet (callend)

1. Bedingung: Anrufstatus = HANGUP (Anruf beendet)
2. Aktion: HTTP Request
   • Methode: GET
   • URL: {busylight_url}/{called_number}/callend

Schritt 5: Variablen-Mapping

Die Starface-Variablen müssen auf die URL gemappt werden:

Starface-Variable	Beschreibung	Verwendung
${call.calledNumber}	Durchwahl des Angerufenen	In URL als Durchwahl
${call.callingNumber}	Nummer des Anrufers	Optional für Logging
${call.state}	Aktueller Anrufstatus	Für Bedingung

Hinweis: Die genauen Variablennamen können je nach Starface-Version variieren. Im Modulcreator werden die verfügbaren Variablen als Dropdown angeboten.

Schritt 6: Modul speichern und aktivieren

1. Speichern klicken
2. Modul exportieren als .sfm Datei (für Backup)
3. Unter Module → Modulinstanzen eine neue Instanz anlegen
4. busylight_url auf die IP des Busylight-Servers setzen: http://100.95.224.14:8081
5. Aktivieren

Testen

Von der Kommandozeile testen

# Anruf simulieren (Durchwahl 222 = Nicklas Janzen)
curl http://100.95.224.14:8081/222/callstart
# → Türschild sollte rot werden

# Anruf beenden
curl http://100.95.224.14:8081/222/callend
# → Türschild sollte auf Zeiterfassungs-Status zurückspringen

Im Busylight-Portal prüfen

• Dashboard: Telefon-Badge sollte "Telefoniert" anzeigen
• Protokoll: Einträge mit phone_active und phone_end sollten erscheinen

Alternative: Starface Rufnummernaktionen

Falls kein Modulcreator verfügbar ist, können auch Rufnummernaktionen verwendet werden:

1. Admin → Rufnummern → Durchwahl auswählen
2. Aktionen → Neue Aktion
3. Bei Anrufbeginn: HTTP Request an http://BUSYLIGHT:8081/{durchwahl}/callstart
4. Bei Anrufende: HTTP Request an http://BUSYLIGHT:8081/{durchwahl}/callend

Nachteil: Muss pro Durchwahl einzeln eingerichtet werden.

Fehlerbehebung

Türschild reagiert nicht

1. Busylight-Server erreichbar? curl http://100.95.224.14:8081/
2. Durchwahl im Busylight-Portal beim Benutzer eingetragen?
3. Benutzer laut Zeiterfassung "anwesend" oder "homeoffice"?
4. Starface-Modul aktiviert?
5. Firewall: Port 8081 von der Starface zum Busylight-Server offen?

Falscher Benutzer wird rot

• Prüfen ob die Durchwahl im Busylight-Portal dem richtigen Benutzer zugeordnet ist
• Variable im Modulcreator: ${call.calledNumber} (nicht ${call.callingNumber})

Türschild bleibt nach Anrufende rot

• Prüfen ob das HANGUP-Event im Modul konfiguriert ist
• Im Busylight-Protokoll prüfen ob callend ankommt
• Manuell zurücksetzen: curl http://100.95.224.14:8081/{durchwahl}/callend