259 lines
9.4 KiB
Markdown
259 lines
9.4 KiB
Markdown
# 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_v54.sfm`](../fax2Mail_v54.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.
|
|
|
|
> **⚠️ WICHTIG für Multi-Instanz-Betrieb:**
|
|
> - **Nur IMAP wird empfohlen** (POP3 löscht Emails und ist nicht zuverlässig für mehrere Instanzen)
|
|
> - **Separate Ordner verwenden** für beste Zuverlässigkeit (siehe Setup unten)
|
|
> - **Technisch möglich**: Mehrere Instanzen auf demselben Ordner, aber separate Ordner sind deutlich zuverlässiger und performanter
|
|
|
|
**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)
|