11 KiB

Raw Blame History

Mail2Fax - Installations- und Konfigurationshandbuch

Detaillierte Schritt-für-Schritt-Anleitung zur Installation und Konfiguration des Mail2Fax-Moduls für STARFACE.

Aktuelle Version: v54 (fax2Mail_v54.sfm) Enthält alle Features: PIN-Schutz, Betreff-Präfix (Multi-Instanz), Retry-Logik, etc.

Inhaltsverzeichnis

Voraussetzungen
Teil 1: Modul-Erstellung im Module Designer
Teil 2: Modul-Konfiguration
Fertig-Modul importieren
Mehrere Instanzen für verschiedene Benutzer

Voraussetzungen

STARFACE 8.x, 9.x oder 10.x
Admin-Zugriff auf STARFACE (SSH-Zugang für JavaMail-Installation)
JavaMail-Bibliothek muss auf STARFACE installiert sein

JavaMail installieren (vor dem Import!)

Einfachste Methode - Automatisches Script:

cd ..
./install-javamail.sh <starface-ip>
ssh root@<starface-ip> 'systemctl restart tomcat'

Manuelle Installation:

# Bibliotheken herunterladen
curl -L -o javax.mail.jar https://repo1.maven.org/maven2/com/sun/mail/javax.mail/1.6.2/javax.mail-1.6.2.jar
curl -L -o activation.jar https://repo1.maven.org/maven2/javax/activation/activation/1.1.1/activation-1.1.1.jar

# Auf STARFACE kopieren
scp javax.mail.jar root@<starface-ip>:/opt/tomcat/webapps/localhost/starface/WEB-INF/lib/
scp activation.jar root@<starface-ip>:/opt/tomcat/webapps/localhost/starface/WEB-INF/lib/

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

Teil 1: Modul-Erstellung im Module Designer

Schritt 1: Neues Modul erstellen

Öffne den STARFACE Module Designer und erstelle ein neues Modul.

Auszufüllen:

Modul-Name: Mail2Fax (oder beliebiger Name)
Beschreibung: "Ruft E-Mails ab und sendet PDF-Anhänge als Fax"
Version: 1.0.0

Schritt 2: Class-Dateien hochladen

Lade beide kompilierten .class Dateien als Ressourcen hoch.

Hochzuladen:

Mail2FaxBlock.class (Hauptfunktion)
Mail2FaxCleanup.class (Cleanup-Funktion)

Tab: Ressourcen → "Datei hochladen"

Schritt 3: Cleanup-Funktion im Entrypoint einrichten

Verknüpfe die Cleanup-Klasse mit dem activate Event.

Konfiguration:

Tab: Entrypoints
Event: activate
Klasse: Mail2FaxCleanup.class

Dies stellt sicher, dass beim Modul-Start die Cleanup-Routine ausgeführt wird.

Schritt 4: Haupt-Funktion erstellen

Erstelle die Hauptfunktion, die vom Timer aufgerufen wird.

Konfiguration:

Tab: Funktionen
Neuer Funktionsbaustein: "Mail2Fax"
Klasse: Mail2FaxBlock.class

Schritt 5: Timer einrichten

Konfiguriere einen Timer, der die Hauptfunktion regelmäßig ausführt.

Konfiguration:

Tab: Timer
Neuer Schedule: [+] klicken
Intervall: 60 Sekunden (empfohlen)
Verknüpfte Funktion: Mail2Fax (Hauptfunktion)

Hinweis: Der eingebaute Lock-Mechanismus verhindert parallele Ausführungen automatisch.

Schritt 6: GUI-Elemente erstellen

Erstelle die Eingabefelder für die Konfiguration.

Zu erstellende Felder:

Feldname	Typ	Label	Beschreibung
mailServer	STRING	Mail Server	IMAP/POP3 Server-Adresse
mailPort	NUMBER	Port	Server-Port (993 für IMAPS)
mailProtocol	STRING	Protokoll	"IMAP" oder "POP3"
mailUsername	STRING	Benutzername	E-Mail-Benutzername
mailPassword	PASSWORD	Passwort	E-Mail-Passwort
mailUseSsl	BOOLEAN	SSL verwenden	SSL/TLS aktivieren
mailFolder	STRING	Ordner	E-Mail-Ordner (z.B. INBOX)
deleteAfterProcess	BOOLEAN	Nach Verarbeitung löschen	E-Mails löschen (nur IMAP)
faxAccountId	STARFACE_USER	Fax-Benutzer	Benutzer für Fax-Versand
faxSenderNumber	STRING	Absender-Faxnummer	Ausgehende Faxnummer
authorizedSenders	STRING	Erlaubte Absender	Komma-getrennte Liste (optional)
subjectPrefix	STRING	Betreff-Präfix	Präfix für Multi-Instanz (optional)
pin	STRING	PIN	Sicherheits-PIN (optional)
maxRetries	NUMBER	Max. Wiederholungen	Anzahl Wiederholungsversuche
retryDelayMinutes	NUMBER	Wartezeit (Minuten)	Minuten zwischen Versuchen

Schritt 7: GUI-Vorschau prüfen

Überprüfe die GUI-Elemente in der Vorschau.

Stelle sicher, dass alle Felder korrekt angezeigt werden und sinnvoll beschriftet sind.

Schritt 8: Mail2Fax Block zur Hauptfunktion hinzufügen

Füge den Mail2Fax-Block zur Hauptfunktion hinzu.

Im Funktions-Editor:

Block "Mail2FaxBlock" aus der Palette ziehen
In den Ablauf der Hauptfunktion einfügen

Schritt 9: GUI-Felder zuweisen

Weise die GUI-Felder den Block-Parametern zu.

Mapping:

Jedes GUI-Element mit dem entsprechenden Block-Parameter verbinden
Alle @InputVar Felder des Blocks müssen mit GUI-Elementen verknüpft werden

Schritt 10: Modul speichern

Speichere das Modul und aktiviere es.

Das Modul ist jetzt bereit zur Konfiguration!

Teil 2: Modul-Konfiguration

Schritt 1: Neue Konfiguration hinzufügen

Erstelle eine neue Instanz des Mail2Fax-Moduls.

Navigation:

Module → Modulkonfigurationen → [+] Neu

Schritt 2: Mail2Fax Modul auswählen

Wähle das zuvor erstellte Mail2Fax-Modul aus.

Schritt 3: Instanz benennen

Gib der Modul-Instanz einen eindeutigen Namen.

Beispiele:

"Mail2Fax - Hauptbüro"
"Mail2Fax - Maik"
"Mail2Fax - Vertrieb"

Schritt 4: Felder ausfüllen

Fülle alle erforderlichen Konfigurationsfelder aus.

Beispiel-Konfiguration:

E-Mail-Einstellungen

Mail Server: mail.example.com
Port: 993
Protokoll: IMAP
Benutzername: fax@example.com
Passwort: ********
SSL verwenden: ✓ Ja
Ordner: INBOX
Nach Verarbeitung löschen: ☐ Nein (für IMAP)

Fax-Einstellungen

Fax-Benutzer: (Aus Dropdown wählen - z.B. "Stefan Hacker")
Absender-Faxnummer: +49721123456

Sicherheit (optional)

Erlaubte Absender: info@example.com, team@example.com
Betreff-Präfix: FAXStefan: (für Multi-Instanz)
PIN: 1234 (wenn PIN-Schutz gewünscht)

Retry-Einstellungen

Max. Wiederholungen: 3
Wartezeit (Minuten): 5

Schritt 5: Modul aktivieren

Aktiviere die Modul-Instanz.

Fertig! Das Modul läuft jetzt und prüft alle 60 Sekunden auf neue E-Mails.

Fertig-Modul importieren

Alternativ zur manuellen Erstellung kannst du das fertig konfigurierte Modul importieren:

Datei: ../fax2Mail_v54.sfm

Import:

STARFACE Admin → Module → Module Designer
"Modul importieren"
.sfm Datei hochladen
Modul wird automatisch erstellt (inkl. aller Felder und Funktionen)
Weiter mit Teil 2: Modul-Konfiguration

Hinweis:

Du musst trotzdem die .class Dateien und JavaMail-Bibliothek installieren!
Das Modul enthält alle aktuellen Features inkl. subjectPrefix und pin Parameter

Mehrere Instanzen für verschiedene Benutzer

Du kannst mehrere Instanzen des Moduls für verschiedene Benutzer erstellen.

⚠️ WICHTIG für Multi-Instanz-Betrieb:

Voraussetzungen:

Nur IMAP verwenden (POP3 ist NICHT geeignet für mehrere Instanzen)

Separate Ordner empfohlen für beste Zuverlässigkeit und Performance

Warum separate Ordner?

Keine Race Conditions möglich

Jede Instanz sieht nur relevante E-Mails

Bessere Performance (keine unnötigen Prüfungen)

Klare Trennung und einfacheres Debugging

Alternative (nicht empfohlen): Mehrere Instanzen auf demselben Ordner funktionieren technisch, aber E-Mails werden mehrfach geprüft und es kann zu Verzögerungen kommen.

Beispiel: Zwei Benutzer

Instanz 1: Maik

Name: "Mail2Fax - Maik"
Mail Server: mail.example.com
Ordner: FaxMaik (mit E-Mail-Filter)
Betreff-Präfix: FAXMaik:
Fax-Benutzer: Maik (aus Dropdown)
Absender-Faxnummer: Maiks Nummer

Instanz 2: Olaf

Name: "Mail2Fax - Olaf"
Mail Server: mail.example.com
Ordner: FaxOlaf (mit E-Mail-Filter)
Betreff-Präfix: FAXOlaf:
Fax-Benutzer: Olaf (aus Dropdown)
Absender-Faxnummer: Olafs Nummer

E-Mail-Filter einrichten

Im E-Mail-Client (z.B. Thunderbird, Outlook):

Regel 1:

Wenn Betreff enthält: FAXMaik:
Dann verschiebe nach: FaxMaik

Regel 2:

Wenn Betreff enthält: FAXOlaf:
Dann verschiebe nach: FaxOlaf

Benutzung

Maik sendet Fax:

An: fax@example.com
Betreff: FAXMaik: +49721123456
Anhang: dokument.pdf

Olaf sendet Fax:

An: fax@example.com
Betreff: FAXOlaf: +498999887766
Anhang: rechnung.pdf

Beide E-Mails landen im selben Postfach, werden aber durch Filter in verschiedene Ordner sortiert und von unterschiedlichen Modul-Instanzen verarbeitet.

Logs und Fehlersuche

Log-Dateien:

/var/log/starface/starface.log

Nützliche Log-Meldungen:

# Erfolgreiche Verarbeitung
grep "Mail2Fax: Fax erfolgreich gesendet" /var/log/starface/starface.log

# Fehler
grep "Mail2Fax.*ERROR" /var/log/starface/starface.log

# BUSY (für Retry)
grep "Mail2Fax.*BUSY" /var/log/starface/starface.log

# Präfix-Fehler
grep "Mail2Fax: Betreff-Präfix stimmt nicht" /var/log/starface/starface.log

# PIN-Fehler
grep "Mail2Fax: PIN" /var/log/starface/starface.log

Tracking-Dateien:

/var/starface/module-data/mail2fax_processed.txt  # Verarbeitete E-Mails (POP3)
/var/starface/module-data/mail2fax_retry.txt      # Retry-Queue

Support

Bei Problemen:

Logs prüfen (siehe oben)
JavaMail-Bibliothek installiert? (/opt/tomcat/webapps/localhost/starface/WEB-INF/lib/javax.mail.jar)
Fax-Benutzer hat Fax-Berechtigung?
E-Mail-Server erreichbar? (Firewall, Ports)
PDF-Anhänge vorhanden und gültig?

Weitere Details in der README.md.

11 KiB Raw Blame History

Mail2Fax - Installations- und Konfigurationshandbuch

Inhaltsverzeichnis

Voraussetzungen

JavaMail installieren (vor dem Import!)

Teil 1: Modul-Erstellung im Module Designer

Schritt 1: Neues Modul erstellen

Schritt 2: Class-Dateien hochladen

Schritt 3: Cleanup-Funktion im Entrypoint einrichten

Schritt 4: Haupt-Funktion erstellen

Schritt 5: Timer einrichten

Schritt 6: GUI-Elemente erstellen

Schritt 7: GUI-Vorschau prüfen

Schritt 8: Mail2Fax Block zur Hauptfunktion hinzufügen

Schritt 9: GUI-Felder zuweisen

Schritt 10: Modul speichern

Teil 2: Modul-Konfiguration

Schritt 1: Neue Konfiguration hinzufügen

Schritt 2: Mail2Fax Modul auswählen

Schritt 3: Instanz benennen

Schritt 4: Felder ausfüllen

E-Mail-Einstellungen

Fax-Einstellungen

Sicherheit (optional)

Retry-Einstellungen

Schritt 5: Modul aktivieren

Fertig-Modul importieren

Mehrere Instanzen für verschiedene Benutzer

Beispiel: Zwei Benutzer

E-Mail-Filter einrichten

Benutzung

Logs und Fehlersuche

Support

11 KiB

Raw Blame History