# 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:**
```bash
# 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.
</content>