starface-mail2fax/v8-9-10/README.md

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)

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

2. Block kompilieren

./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)