# 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

## 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)

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

### 2. Block kompilieren

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

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

## Installation im Module Designer

### 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

### 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) | |
| 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** = Ziel-Faxnummer (z.B. `+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.

## 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)