docs: detailed Starface module rebuild guide using HttpRequest
This commit is contained in:
parent
1e66646f52
commit
f89b9b4626
234
docs/starface-modul-umbau.md
Normal file
234
docs/starface-modul-umbau.md
Normal file
@ -0,0 +1,234 @@
|
|||||||
|
# Starface Modul "Busylight 2" → Umbau auf HTTP-Webhook
|
||||||
|
|
||||||
|
## Übersicht
|
||||||
|
|
||||||
|
Das bestehende Modul "Busylight 2" schreibt Telefonstatus in eine MS SQL Datenbank.
|
||||||
|
Wir bauen es so um, dass es stattdessen HTTP-Requests an den Busylight-Webhook sendet.
|
||||||
|
|
||||||
|
**Vorher:** Starface → MS SQL DB → altes Python-Script → WLED
|
||||||
|
**Nachher:** Starface → HTTP-Webhook → Busylight-Server → WLED
|
||||||
|
|
||||||
|
## Was wir ändern
|
||||||
|
|
||||||
|
1. Die Funktion `UpdateDB` durch eine neue Funktion `CallWebhook` ersetzen
|
||||||
|
2. Die GUI-Variablen vereinfachen (kein DB-Server/User/Passwort mehr)
|
||||||
|
3. Im switch/case nur noch INCOMING/OUTGOING/CONNECTED → callstart und HANGUP → callend
|
||||||
|
|
||||||
|
## Schritt-für-Schritt Anleitung
|
||||||
|
|
||||||
|
### Schritt 1: Modul im Modulcreator öffnen
|
||||||
|
|
||||||
|
1. Starface Admin → Module → Modulcreator
|
||||||
|
2. Modul "Busylight 2" öffnen
|
||||||
|
3. Tab **Development** auswählen
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Schritt 2: GUI-Tab anpassen
|
||||||
|
|
||||||
|
1. Tab **GUI** öffnen
|
||||||
|
2. Folgende Felder **löschen** (werden nicht mehr gebraucht):
|
||||||
|
- GUI_SERVER
|
||||||
|
- GUI_PORT
|
||||||
|
- GUI_USERNAME
|
||||||
|
- GUI_PASSWORT
|
||||||
|
- GUI_RINGING (brauchen wir nicht für Webhook)
|
||||||
|
- GUI_RINGBACK
|
||||||
|
- GUI_PARKED
|
||||||
|
- GUI_CONFERENCE_ACTIVE
|
||||||
|
- GUI_LOGIN_LOGOUT
|
||||||
|
- GUI_MUSICONHOLD_TEST
|
||||||
|
- GUI_VOICEMAIL_MAIN
|
||||||
|
- GUI_VOICEMAIL_LINKED
|
||||||
|
- GUI_CONSULT
|
||||||
|
- GUI_CONFERENCE_CONSULT
|
||||||
|
- GUI_CONFERENCE_INACTIVE
|
||||||
|
- GUI_CCBS
|
||||||
|
|
||||||
|
3. **Neues Feld hinzufügen:**
|
||||||
|
- Name: `GUI_WEBHOOK_URL`
|
||||||
|
- Typ: String
|
||||||
|
- Standardwert: `http://100.95.224.14:8081`
|
||||||
|
- Beschreibung: `URL des Busylight Webhook-Servers (ohne / am Ende)`
|
||||||
|
|
||||||
|
4. Die verbleibenden Felder behalten:
|
||||||
|
- `GUI_INCOMING` = `1` (aktiv)
|
||||||
|
- `GUI_OUTGOING` = `1` (aktiv)
|
||||||
|
- `GUI_CONNECTED` = leer (nicht nötig, da INCOMING/OUTGOING schon callstart senden)
|
||||||
|
- `GUI_HANGUP` = `0` (aktiv, sendet callend)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Schritt 3: Neue Funktion "CallWebhook" erstellen
|
||||||
|
|
||||||
|
1. Tab **Development** → Links unter "Functions" auf **+** klicken
|
||||||
|
2. Name: `CallWebhook`
|
||||||
|
3. **Function Settings** → Input-Variablen anlegen:
|
||||||
|
- `loginId` (Typ: String) – Die Durchwahl des Users
|
||||||
|
- `action` (Typ: String) – "callstart" oder "callend"
|
||||||
|
|
||||||
|
4. In den **Edit**-Bereich wechseln und folgende Bausteine nacheinander einfügen:
|
||||||
|
|
||||||
|
#### Baustein 1: Append (URL zusammenbauen)
|
||||||
|
|
||||||
|
- Aus **Components** → **String** → **Append** in den Edit-Bereich ziehen
|
||||||
|
- Konfiguration der Input-Variable "Strings" (mehrere Werte):
|
||||||
|
- Wert 1: `GUI_WEBHOOK_URL` (By Reference ✓ – auf die Modul-Variable zeigen)
|
||||||
|
- Wert 2: `/` (By Reference ✗ – fester Text)
|
||||||
|
- Wert 3: `loginId` (By Reference ✓ – auf die Input-Variable der Funktion zeigen)
|
||||||
|
- Wert 4: `/` (By Reference ✗ – fester Text)
|
||||||
|
- Wert 5: `action` (By Reference ✓ – auf die Input-Variable der Funktion zeigen)
|
||||||
|
- Output: `result` → wird die URL z.B. `http://100.95.224.14:8081/222/callstart`
|
||||||
|
|
||||||
|
#### Baustein 2: CreateHttpUrlWithParams (URL-Objekt erstellen)
|
||||||
|
|
||||||
|
- Aus **Components** → **Net.HTTP** → **CreateHttpUrlWithParams** in den Edit-Bereich ziehen
|
||||||
|
- Input "url": `result` (By Reference ✓ – Output vom Append)
|
||||||
|
- Output: `httpUrl`
|
||||||
|
|
||||||
|
#### Baustein 3: HttpRequest (HTTP-Request senden)
|
||||||
|
|
||||||
|
- Aus **Components** → **Net.HTTP** → **HttpRequest** in den Edit-Bereich ziehen
|
||||||
|
- Input "httpUrl": `httpUrl` (By Reference ✓ – Output von CreateHttpUrlWithParams)
|
||||||
|
- Input "method": `GET` (By Reference ✗ – fester Text)
|
||||||
|
- Die anderen Inputs (body, headers etc.) leer lassen
|
||||||
|
|
||||||
|
#### Baustein 4: Log (optional, zum Debuggen)
|
||||||
|
|
||||||
|
- Aus **Components** → **System** → **Log** in den Edit-Bereich ziehen
|
||||||
|
- Log Level: `INFO`
|
||||||
|
- Message (mehrere Werte):
|
||||||
|
- `Busylight Webhook: ` (fester Text)
|
||||||
|
- `result` (By Reference ✓ – die URL die aufgerufen wurde)
|
||||||
|
|
||||||
|
**Die fertige Funktion sieht so aus:**
|
||||||
|
```
|
||||||
|
CallWebhook(loginId, action):
|
||||||
|
1. Append([GUI_WEBHOOK_URL, "/", loginId, "/", action]) → result
|
||||||
|
2. CreateHttpUrlWithParams(result) → httpUrl
|
||||||
|
3. HttpRequest(httpUrl, "GET")
|
||||||
|
4. Log("INFO", ["Busylight Webhook: ", result])
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Schritt 4: Funktion "UpdateDB" löschen
|
||||||
|
|
||||||
|
1. Links unter "Functions" die Funktion **UpdateDB** auswählen
|
||||||
|
2. **Löschen** (X-Button)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Schritt 5: Call-Funktion anpassen
|
||||||
|
|
||||||
|
In der Funktion **Call** den `switch(_uciCallState)` Block anpassen:
|
||||||
|
|
||||||
|
#### case 'INCOMING' ändern:
|
||||||
|
- Den alten `UpdateDB(_loginId, GUI_INCOMING)` Aufruf **löschen**
|
||||||
|
- Stattdessen: **CallWebhook** reinziehen
|
||||||
|
- `loginId` = `_loginId` (By Reference ✓)
|
||||||
|
- `action` = `callstart` (By Reference ✗, fester Text)
|
||||||
|
|
||||||
|
#### case 'OUTGOING' ändern:
|
||||||
|
- Den alten `UpdateDB(_loginId, GUI_OUTGOING)` Aufruf **löschen**
|
||||||
|
- Stattdessen: **CallWebhook** reinziehen
|
||||||
|
- `loginId` = `_loginId` (By Reference ✓)
|
||||||
|
- `action` = `callstart` (By Reference ✗, fester Text)
|
||||||
|
|
||||||
|
#### case 'CONNECTED' ändern:
|
||||||
|
- Den alten `UpdateDB` Aufruf **löschen**
|
||||||
|
- Diesen case kann man auch komplett löschen (INCOMING/OUTGOING decken den Start ab)
|
||||||
|
- ODER: CallWebhook mit `callstart` einsetzen (schadet nicht, ist idempotent)
|
||||||
|
|
||||||
|
#### case 'HANGUP' ändern:
|
||||||
|
- Den alten `UpdateDB(_loginId, GUI_HANGUP)` Aufruf **löschen**
|
||||||
|
- Stattdessen: **CallWebhook** reinziehen
|
||||||
|
- `loginId` = `_loginId` (By Reference ✓)
|
||||||
|
- `action` = `callend` (By Reference ✗, fester Text)
|
||||||
|
|
||||||
|
#### Alle anderen cases löschen:
|
||||||
|
- case 'RINGING' → **löschen** (wird nicht gebraucht)
|
||||||
|
- case 'RINGBACK' → **löschen**
|
||||||
|
- case 'PARKED' → **löschen**
|
||||||
|
- case 'CONFERENCE_ACTIVE' → **löschen**
|
||||||
|
- case 'LOGIN_LOGOUT' → **löschen**
|
||||||
|
- case 'MUSICONHOLD_TEST' → **löschen**
|
||||||
|
- case 'VOICEMAIL_MAIN' → **löschen**
|
||||||
|
- case 'VOICEMAIL_LINKED' → **löschen**
|
||||||
|
- case 'CONSULT' → **löschen**
|
||||||
|
- case 'CONFERENCE_CONSULT' → **löschen**
|
||||||
|
- case 'CONFERENCE_INACTIVE' → **löschen**
|
||||||
|
- case 'CCBS' → **löschen**
|
||||||
|
|
||||||
|
#### Ergebnis nach Umbau:
|
||||||
|
|
||||||
|
```
|
||||||
|
switch(_uciCallState):
|
||||||
|
case 'INCOMING':
|
||||||
|
CallWebhook(_loginId, "callstart")
|
||||||
|
|
||||||
|
case 'OUTGOING':
|
||||||
|
CallWebhook(_loginId, "callstart")
|
||||||
|
|
||||||
|
case 'HANGUP':
|
||||||
|
CallWebhook(_loginId, "callend")
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Schritt 6: if-Bedingungen in den cases vereinfachen
|
||||||
|
|
||||||
|
Im alten Modul steht vor jedem UpdateDB ein `if(!empty(GUI_xxx))`.
|
||||||
|
Das kann vereinfacht werden zu einem einzigen Check:
|
||||||
|
|
||||||
|
```
|
||||||
|
case 'INCOMING':
|
||||||
|
CallWebhook(_loginId, "callstart")
|
||||||
|
```
|
||||||
|
|
||||||
|
Die if-Abfrage ist nicht mehr nötig, da wir keine GUI-Variablen mehr pro Status haben.
|
||||||
|
Wenn du die if-Abfragen drin lassen willst, ändere sie auf `if(!empty(GUI_WEBHOOK_URL))`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Schritt 7: Register/Unregister Funktionen
|
||||||
|
|
||||||
|
Die Funktionen **Register** und **Unregister** (links unter Functions) bleiben **unverändert**.
|
||||||
|
Sie registrieren den Call-Event-Listener beim Aktivieren/Deaktivieren des Moduls.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Schritt 8: Speichern und Testen
|
||||||
|
|
||||||
|
1. **Save** klicken
|
||||||
|
2. **Apply** klicken
|
||||||
|
3. Unter **Module** → **Modulinstanzen** die Instanz öffnen
|
||||||
|
4. `GUI_WEBHOOK_URL` auf `http://100.95.224.14:8081` setzen
|
||||||
|
5. **Aktivieren**
|
||||||
|
6. Testanruf machen und im Busylight-Dashboard prüfen ob der Telefon-Badge erscheint
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Zusammenfassung der Änderungen
|
||||||
|
|
||||||
|
| Vorher | Nachher |
|
||||||
|
|--------|---------|
|
||||||
|
| UpdateDB → MS SQL Server | CallWebhook → HTTP GET |
|
||||||
|
| GUI_SERVER, GUI_PORT, GUI_USERNAME, GUI_PASSWORT | GUI_WEBHOOK_URL |
|
||||||
|
| 16 switch-cases | 3 switch-cases (INCOMING, OUTGOING, HANGUP) |
|
||||||
|
| SQL: `UPDATE [Users] SET [StatusStarface] = ...` | HTTP: `GET /222/callstart` |
|
||||||
|
|
||||||
|
## Fehlerbehebung
|
||||||
|
|
||||||
|
### Webhook kommt nicht an
|
||||||
|
- Log File im Modulcreator prüfen (Tab "Log File")
|
||||||
|
- Die URL im Log muss so aussehen: `http://100.95.224.14:8081/222/callstart`
|
||||||
|
- Vom Starface-Server testen: `curl http://100.95.224.14:8081/222/callstart`
|
||||||
|
|
||||||
|
### Falscher User wird rot
|
||||||
|
- `_loginId` prüfen - das ist die Starface Login-ID (= Durchwahl)
|
||||||
|
- Diese muss im Busylight-Portal unter "Benutzer" → "Durchwahl" eingetragen sein
|
||||||
|
|
||||||
|
### Türschild bleibt rot nach Anruf
|
||||||
|
- HANGUP-Event prüfen - wird `callend` aufgerufen?
|
||||||
|
- Manuell zurücksetzen: `curl http://100.95.224.14:8081/222/callend`
|
||||||
Loading…
x
Reference in New Issue
Block a user