Hacker-Software
/
starface-mail2fax
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
starface-mail2fax/v8-9-10/INSTALLATION.md

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: v53 (fax2Mail_v53.sfm) Enthält alle Features: PIN-Schutz, Betreff-Präfix (Multi-Instanz), Retry-Logik, etc.

Inhaltsverzeichnis

  1. Voraussetzungen
  2. Teil 1: Modul-Erstellung im Module Designer
  3. Teil 2: Modul-Konfiguration
  4. Fertig-Modul importieren
  5. 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.

01. Create Module and Description

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.

02. Upload Classes

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.

03. Set Cleanup Class in Module Settings

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.

04. Create main function

Konfiguration:

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

Schritt 5: Timer einrichten

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

05. Create Timer for function

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.

06. Create GUI elements

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.

07. Preview GUI Elements to see it looks good

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.

08. Add Mail2Fax Block to main function

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.

09. Assign GUI Fields

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.

10. Save Module

Das Modul ist jetzt bereit zur Konfiguration!

Teil 2: Modul-Konfiguration

Schritt 1: Neue Konfiguration hinzufügen

Erstelle eine neue Instanz des Mail2Fax-Moduls.

01. Add new config

Navigation:

  • Module → Modulkonfigurationen → [+] Neu

Schritt 2: Mail2Fax Modul auswählen

Wähle das zuvor erstellte Mail2Fax-Modul aus.

02. Choose Mail2Fax Module

Schritt 3: Instanz benennen

Gib der Modul-Instanz einen eindeutigen Namen.

03. Set module name

Beispiele:

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

Schritt 4: Felder ausfüllen

Fülle alle erforderlichen Konfigurationsfelder aus.

04. Fill out fields

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.

05. Activate module, finish

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_v53.sfm

Import:

  1. STARFACE Admin → Module → Module Designer
  2. "Modul importieren"
  3. .sfm Datei hochladen
  4. Modul wird automatisch erstellt (inkl. aller Felder und Funktionen)
  5. 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:

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:

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

Weitere Details in der README.md.