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
• 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:

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:

ssh root@<starface-ip> 'systemctl restart tomcat'

2. Block kompilieren

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

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:

# 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

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
• Import über Module Designer (inkl. aller Felder: subjectPrefix, pin, etc.)
• Danach Instanz konfigurieren (siehe 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)