starface-mail2fax/v8-9-10

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
├── build-block.sh        # Kompilier-Script
├── libs/starface/        # STARFACE API JARs
└── README.md

Build

1. STARFACE APIs holen (falls noch nicht geschehen)

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

2. Block kompilieren

./build-block.sh

Ergebnis: Mail2FaxBlock.class

Installation im Module Designer

1. Neues Modul erstellen

• STARFACE Admin → Module → Module Designer
• "Neues Modul erstellen"
• Name: "Mail2Fax"

2. Block hochladen

• Tab "Ressourcen"
• "Datei hochladen" → Mail2FaxBlock.class

3. Funktion erstellen

• Tab "Funktionen"
• Neue Funktion erstellen
• Den hochgeladenen Block als Implementierung auswählen

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. Timer konfigurieren

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)

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.

6. 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.