starface-blacklist-module/v8-9-10/INSTALLATION.md

Blacklist - Installations- und Konfigurationshandbuch

Schritt-für-Schritt-Anleitung zur Installation des Blacklist-Moduls im STARFACE Module Designer.

---

Voraussetzungen

• STARFACE 8.x, 9.x oder 10.x
• Admin-Zugriff auf STARFACE
• Kompilierte BlacklistBlock.class (siehe ./build-block.sh)

Es ist keine zusätzliche Bibliothek nötig (anders als bei Mail2Fax kein JavaMail). Es wird auch kein SSH-Zugriff zum Installieren von Libs benötigt.

---

Teil 1: Modul-Erstellung im Module Designer

Schritt 1: Neues Modul erstellen

STARFACE Admin → Module → Module Designer → Neues Modul

• Modul-Name: Blacklist
• Beschreibung: "Sperrt/behandelt eingehende Anrufe anhand einer Blacklist und anonyme Anrufe"
• Version: 1.0.0

Schritt 2: Class-Datei hochladen

Tab Ressourcen → Datei hochladen → BlacklistBlock.class

Optional (nur für die Aktion ANNOUNCE): eine Ansage-Audiodatei (WAV) hochladen. Der Dateiname wird später im Feld Ansage-Datei eingetragen.

Schritt 3: Funktion erstellen

Tab Funktionen → neue Funktion Blacklist anlegen und den Block BlacklistBlock in den Ablauf ziehen.

Schritt 4: GUI-Elemente (Eingabefelder) anlegen

Lege die Konfigurationsfelder an und verknüpfe sie mit den @InputVar-Feldern des Blocks:

Feldname	Typ	Label	Auswahlwerte
blacklistEntries	STRING (mehrzeilig)	Blacklist-Einträge
defaultAction	STRING	Standard-Aktion	HANGUP, BUSY, REDIRECT, ANNOUNCE
defaultRedirectTarget	STRING	Standard-Umleitungsziel
announcementFile	STRING	Ansage-Datei
anonymousAction	STRING	Aktion bei anonymen Anrufen	NONE, HANGUP, BUSY, REDIRECT, ANNOUNCE
anonymousRedirectTarget	STRING	Umleitungsziel anonyme Anrufe
countryCode	STRING	Ländervorwahl	(Default 49)
prefixMatch	BOOLEAN	Bereichssperre erlauben	(Default an)

Die Auswahlwerte (possibleValues) sind bereits im Block hinterlegt und erscheinen i.d.R. automatisch als Dropdown. Falls nicht, als normales Textfeld anlegen.

Schritt 5: GUI-Felder zuweisen

Jedes GUI-Element mit dem gleichnamigen Block-Parameter verbinden. Alle @InputVar-Felder sollten verknüpft sein.

Schritt 6: Modul speichern

Modul speichern.

---

Teil 2: Modul als Anruf-Modul aktivieren

Damit der Block bei eingehenden Anrufen läuft, muss das Modul als Call-Processing-Modul eingebunden werden.

Variante A: Für alle eingehenden Anrufe

1. Module → Modulkonfigurationen → [+] Neu
2. Modul Blacklist auswählen, Instanz benennen (z.B. "Blacklist - Zentrale")
3. Felder ausfüllen (siehe Teil 3)
4. Bei den Modul-Einstellungen den Typ Call-Processing wählen und die Aktivierung auf "bei allen eingehenden Anrufen" setzen.
5. Modul aktivieren.

Variante B: Pro Benutzer/Gruppe (Rufverteilung)

Alternativ kann das Modul gezielt in die Rufverteilung eines Benutzers oder einer Gruppe eingehängt werden (Administration → Benutzer/Gruppe → Rufverteilung → Modul einfügen, vor der eigentlichen Zustellung). So gilt die Blacklist nur für diese Nummern.

Wichtig: Bei einem Treffer mit Aktion HANGUP/BUSY/REDIRECT/ANNOUNCE wird der Anruf beendet bzw. umgeleitet und erreicht die nachgelagerte Zustellung nicht mehr. Bei ALLOW/NONE/keinem Treffer läuft der Anruf normal weiter.

---

Teil 3: Konfiguration (Beispiel)

Blacklist-Einträge:

# Werbeanrufe-Bereiche komplett sperren
0190;BUSY
0900;BUSY
# einzelner Störer: auflegen
+49301234567;HANGUP
# Ausnahme: dieser eine Anschluss aus dem 089-Raum ist ok
+4989123456;ALLOW
089;ANNOUNCE
# nervige Nummer auf die Zentrale umleiten
+4972198765;REDIRECT;100

Standard-Aktion (Blacklist): HANGUP Standard-Umleitungsziel: 100 Ansage-Datei: blacklist_ansage.wav (zuvor als Ressource hochgeladen)

Aktion bei anonymen Anrufen: BUSY (oder REDIRECT mit Ziel, oder NONE zum Durchstellen)

Ländervorwahl: 49 Bereichssperre erlauben: ✓ an

Mit dieser Konfiguration:

• 0190…/0900…/anonyme Anrufer hören Besetzt
• +49 30 1234567 wird aufgelegt
• der gesamte 089…-Bereich bekommt eine Ansage – außer +49 89 123456 (Ausnahme oben)
• +49 721 98765 wird auf Nebenstelle 100 umgeleitet

---

Logs und Fehlersuche

Log-Datei:

/var/log/starface/starface.log

Nützliche Meldungen:

# alle Blacklist-Entscheidungen
grep "Blacklist:" /var/log/starface/starface.log

# Treffer
grep "Blacklist-Treffer" /var/log/starface/starface.log

# anonyme Anrufe
grep "Blacklist: Anonymer Anruf" /var/log/starface/starface.log

Häufige Punkte:

1. Block tut nichts / "kein Anruf-Kontext": Das Modul ist nicht als Call-Processing / "bei allen eingehenden Anrufen" eingebunden.
2. REDIRECT ohne Wirkung: Zielrufnummer/Nebenstelle prüfen, ggf. mit Amtskennziffer.
3. ANNOUNCE ohne Ton: Audiodatei als Ressource hochgeladen und Dateiname im Feld korrekt?
4. Nummer wird nicht erkannt: countryCode prüfen und im Log die normalisierte intl='…'-Form mit dem Eintrag vergleichen.