# Mail2FaxBlock - STARFACE Custom Block

Ein Custom Block für den STARFACE Module Designer, der E-Mails abruft und PDF-Anhänge als Fax versendet.

## Features

- **IMAP/POP3 Unterstützung** mit SSL/TLS
- **POP3**: E-Mails werden IMMER nach erfolgreichem Versand gelöscht (+ Tracking um Duplikate zu vermeiden)
- **IMAP**: E-Mails werden als gelesen markiert (optional löschen)
- **Retry-Logik**: Bei besetzter Leitung oder Fehler wird automatisch erneut versucht
- **Konfigurierbare Wiederholungen**: Anzahl und Wartezeit einstellbar
- **PIN-Schutz**: Optionale Sicherheits-PIN im E-Mail-Text erforderlich
- **Betreff-Präfix**: Mehrere Fax-Instanzen durch Präfix im Betreff (z.B. "FAXMaik:")

## Kompatibilität

- STARFACE 8.x, 9.x, 10.x (Java 21)

## Dateien

```
v8-9-10/
├── Mail2FaxBlock.java    # Quellcode des Custom Blocks (Hauptfunktion)
├── Mail2FaxCleanup.java  # Cleanup-Block (für activate Event)
├── build-block.sh        # Kompilier-Script
├── libs/starface/        # STARFACE API JARs
└── README.md
```

## Build

### 1. STARFACE APIs holen (falls noch nicht geschehen)

Das Script lädt die STARFACE APIs herunter und installiert automatisch die JavaMail-Bibliothek auf der STARFACE:

```bash
cd ..
./fetch-starface-libs.sh <starface-ip>
```

**Was macht das Script:**
- Lädt STARFACE Module-APIs herunter (via SSH/SCP)
- Prüft ob JavaMail auf STARFACE vorhanden ist
- Installiert JavaMail automatisch falls fehlend:
  - `javax.mail.jar` (1.6.2)
  - `activation.jar` (1.1.1)
- Kopiert die Bibliotheken nach `/opt/tomcat/webapps/localhost/starface/WEB-INF/lib/`

**Nach Installation:** STARFACE-Dienst neustarten:
```bash
ssh root@<starface-ip> 'systemctl restart tomcat'
```

### 2. Block kompilieren

```bash
./build-block.sh
```

Ergebnis: `Mail2FaxBlock.class` und `Mail2FaxCleanup.class`

### JavaMail-Installation für fertige Module (ohne Kompilierung)

Wenn du das **fertige `.sfm` Modul** importierst und die `.class` Dateien nicht selbst kompilieren möchtest, brauchst du nur JavaMail zu installieren:

```bash
cd ..
./install-javamail.sh <starface-ip>
```

Das Script:
- Lädt JavaMail-Bibliotheken herunter (`javax.mail.jar`, `activation.jar`)
- Kopiert sie auf die STARFACE
- Prüft ob JavaMail bereits installiert ist (überspringt dann die Installation)

**Danach:** STARFACE neustarten und `.sfm` importieren!

### Manuelle JavaMail-Installation (Alternative)

Falls du die STARFACE APIs manuell heruntergeladen hast oder das Standalone-Script nicht verwenden möchtest:

```bash
# Lokal herunterladen (wird auch vom build-block.sh gemacht)
cd v8-9-10
./build-block.sh  # lädt javax.mail.jar nach libs/deps/

# Auf STARFACE kopieren
scp libs/deps/javax.mail.jar root@<starface-ip>:/opt/tomcat/webapps/localhost/starface/WEB-INF/lib/
scp libs/deps/activation.jar root@<starface-ip>:/opt/tomcat/webapps/localhost/starface/WEB-INF/lib/

# STARFACE neustarten
ssh root@<starface-ip> 'systemctl restart tomcat'
```

## Installation im Module Designer

**📖 Detailliertes Handbuch mit Screenshots: [INSTALLATION.md](INSTALLATION.md)**

### Schnellübersicht

### 1. Neues Modul erstellen
- STARFACE Admin → Module → Module Designer
- "Neues Modul erstellen"
- Name: "Mail2Fax"

### 2. Blöcke hochladen
- Tab "Ressourcen"
- "Datei hochladen" → `Mail2FaxBlock.class`
- "Datei hochladen" → `Mail2FaxCleanup.class`

### 3. Funktionen erstellen
- Tab "Funktionen"
- **Funktion 1**: "Mail2Fax" (Hauptfunktion)
  - Block: Mail2FaxBlock.class
- **Funktion 2**: "Mail2Fax Cleanup" (Cleanup)
  - Block: Mail2FaxCleanup.class

### Alternative: Fertig-Modul importieren
- Datei: [`../fax2Mail_v53.sfm`](../fax2Mail_v53.sfm)
- Import über Module Designer (inkl. aller Felder: `subjectPrefix`, `pin`, etc.)
- Danach Instanz konfigurieren (siehe [INSTALLATION.md](INSTALLATION.md))

### 4. Eingabe-Variablen konfigurieren

| Variable | Typ | Beschreibung | Default |
|----------|-----|--------------|---------|
| mailServer | STRING | IMAP/POP3 Server | |
| mailPort | NUMBER | Port | 993 |
| mailProtocol | STRING | "IMAP" oder "POP3" | IMAP |
| mailUsername | STRING | E-Mail Benutzer | |
| mailPassword | STRING | E-Mail Passwort | |
| mailUseSsl | BOOLEAN | SSL aktivieren | true |
| mailFolder | STRING | Ordner | INBOX |
| deleteAfterProcess | BOOLEAN | E-Mails löschen (nur IMAP) | false |
| faxAccountId | STARFACE_USER | Fax-Benutzer (Dropdown) | |
| faxSenderNumber | STRING | Absender-Faxnummer | |
| authorizedSenders | STRING | Erlaubte Absender (optional) | |
| subjectPrefix | STRING | Betreff-Präfix (optional) | |
| pin | STRING | Sicherheits-PIN (optional) | |
| maxRetries | NUMBER | Max. Wiederholungsversuche | 3 |
| retryDelayMinutes | NUMBER | Minuten zwischen Versuchen | 5 |

### 5. Entrypoint konfigurieren (Cleanup)

Damit nach einem Server-Absturz oder Modul-Reload keine Probleme auftreten:

1. Tab **"Entrypoints"** öffnen
2. Event **"activate"** auswählen
3. **Mail2Fax Cleanup** Funktion verknüpfen

Diese Funktion wird beim Modul-Start ausgeführt und stellt sicher, dass alles sauber initialisiert wird.

### 6. Timer konfigurieren (Hauptfunktion)

Der Block muss regelmäßig ausgeführt werden um E-Mails abzurufen. Dafür den Timer im Module Designer konfigurieren:

1. Tab **"Timer"** öffnen
2. Auf **[+]** klicken um einen neuen Schedule hinzuzufügen
3. Intervall festlegen (empfohlen: alle 60 Sekunden)
4. **Mail2Fax** Funktion (nicht Cleanup!) verknüpfen

**Hinweis:** Der Block hat einen eingebauten Lock-Mechanismus. Wenn der Timer erneut auslöst während der Block noch läuft, wird die neue Ausführung automatisch übersprungen. Keine Gefahr von Duplikaten.

### 7. Modul aktivieren

## Benutzung

1. E-Mail an das konfigurierte Postfach senden
2. **Betreff** = [Präfix] Ziel-Faxnummer (z.B. `FAXMaik: +49721123456` oder nur `+49721123456`)
3. **Anhang** = PDF-Datei(en)
4. **E-Mail-Text** = PIN (falls konfiguriert)

Das Modul ruft regelmäßig E-Mails ab und sendet PDFs als Fax.

## Betreff-Präfix (Multi-Instanz-Betrieb)

Mit dem Betreff-Präfix können mehrere Mail2Fax-Instanzen parallel betrieben werden, z.B. für verschiedene Benutzer oder Abteilungen.

**Verwendung:**
1. Erstelle mehrere Modul-Instanzen im Module Designer
2. Setze für jede Instanz einen eigenen Präfix (z.B. `FAXMaik:`, `FAXOlaf:`)
3. Konfiguriere E-Mail-Filter-Regeln im E-Mail-Client:
   - Regel 1: Wenn Betreff enthält "FAXMaik:" → verschiebe in Ordner "FaxMaik"
   - Regel 2: Wenn Betreff enthält "FAXOlaf:" → verschiebe in Ordner "FaxOlaf"
4. Jede Modul-Instanz überwacht ihren eigenen Ordner

**Beispiel:**
- **Instanz 1** (Benutzer Maik):
  - mailFolder: `FaxMaik`
  - subjectPrefix: `FAXMaik:`
  - faxAccountId: Maik's STARFACE-Benutzer

- **Instanz 2** (Benutzer Olaf):
  - mailFolder: `FaxOlaf`
  - subjectPrefix: `FAXOlaf:`
  - faxAccountId: Olaf's STARFACE-Benutzer

**E-Mail-Beispiele:**
- Betreff: `FAXMaik: +49721123456` → wird von Maik's Instanz verarbeitet
- Betreff: `FAXOlaf: +4989987654` → wird von Olaf's Instanz verarbeitet
- Betreff: `+49721999888` (ohne Präfix) → wird ignoriert, wenn Präfix konfiguriert ist

## PIN-Schutz

Wenn eine PIN konfiguriert ist, muss diese im E-Mail-Text enthalten sein, damit das Fax gesendet wird.

- **PIN nicht gesetzt**: Alle E-Mails werden verarbeitet (nur Absender-Prüfung falls konfiguriert)
- **PIN gesetzt**: Die PIN muss irgendwo im E-Mail-Text (plain text oder HTML) vorkommen
- **PIN nicht gefunden**: E-Mail wird als gelesen markiert, kein Fax gesendet, Log-Eintrag "PIN in Emailtext nicht vorhanden oder falsch"

## Output-Variablen

| Variable | Typ | Beschreibung |
|----------|-----|--------------|
| processedCount | NUMBER | Verarbeitete E-Mails |
| sentFaxCount | NUMBER | Gesendete Faxe |
| errorCount | NUMBER | Fehleranzahl |
| pendingRetries | NUMBER | Wartende Wiederholungsversuche |
| statusMessage | STRING | Status-Meldung |

## Retry-Verhalten

Bei folgenden Fehlern wird automatisch erneut versucht:
- Leitung besetzt
- Keine Antwort
- Übertragungsfehler

Die Retry-Daten werden gespeichert in:
- `/var/starface/module-data/mail2fax_retry.txt`

Nach Erreichen von `maxRetries` wird der Fax-Versuch verworfen.

## POP3-Tracking

Da POP3 keine "gelesen"-Flags unterstützt, speichert der Block verarbeitete Message-IDs in:
- `/var/starface/module-data/mail2fax_processed.txt`

So werden Duplikate vermieden, auch wenn E-Mails nicht sofort gelöscht werden können.

## Lock-Mechanismus und Server-Absturz

Der Block verwendet einen **In-Memory Lock** (`ReentrantLock`), um parallele Ausführungen zu verhindern.

**Wichtig zu wissen:**
- Der Lock existiert nur im RAM, nicht als Datei
- Bei einem Server-Neustart wird der Lock automatisch freigegeben
- Bei einem Absturz während der Ausführung gibt es **keine verwaiste Lock-Datei**
- Der Cleanup-Block beim `activate` Event ist hauptsächlich für Log-Ausgaben und Statusprüfung

**Was passiert bei einem Absturz während des Sendens?**
- Der Lock wird automatisch freigegeben (bei Neustart)
- PDFs in der Retry-Queue bleiben erhalten und werden beim nächsten Durchlauf erneut versucht
- Tracking-Dateien bleiben erhalten (processed.txt, retry.txt)