added documentation

2026-01-10 14:58:33 +01:00
parent 1c8635dee0
commit 372e9d9815
21 changed files with 663 additions and 5 deletions
@@ -0,0 +1,388 @@
+# 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`](../fax2Mail_v53.sfm))
+**Enthält alle Features**: PIN-Schutz, Betreff-Präfix (Multi-Instanz), Retry-Logik, etc.
+
+---
+
+## Inhaltsverzeichnis
+
+1. [Voraussetzungen](#voraussetzungen)
+2. [Teil 1: Modul-Erstellung im Module Designer](#teil-1-modul-erstellung-im-module-designer)
+3. [Teil 2: Modul-Konfiguration](#teil-2-modul-konfiguration)
+4. [Fertig-Modul importieren](#fertig-modul-importieren)
+5. [Mehrere Instanzen für verschiedene Benutzer](#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:
+```bash
+cd ..
+./install-javamail.sh <starface-ip>
+ssh root@<starface-ip> 'systemctl restart tomcat'
+```
+
+**Manuelle Installation:**
+```bash
+# 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](docu/Modul%20Creation/01.%20Create%20Modul%20and%20Description.png)
+
+**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](docu/Modul%20Creation/02.%20Upload%20Classes.png)
+
+**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](docu/Modul%20Creation/03.%20Set%20Cleanup%20Class%20in%20Modul%20Settings.png)
+
+**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](docu/Modul%20Creation/04.%20Create%20main%20function.png)
+
+**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](docu/Modul%20Creation/05.%20Create%20Timer%20for%20function.png)
+
+**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](docu/Modul%20Creation/06.%20Create%20GUI%20elements.png)
+
+**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](docu/Modul%20Creation/07.%20Preview%20GUI%20Elemets%20to%20see%20it%20looks%20good.png)
+
+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](docu/Modul%20Creation/08.%20Add%20Mail2FAx%20Block%20to%20main%20funtion.png)
+
+**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](docu/Modul%20Creation/09.%20Assign%20GUI%20Fields.png)
+
+**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](docu/Modul%20Creation/10.%20Save%20Modul.png)
+
+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](docu/Modul%20Konfiguration/01.%20Add%20new%20config.png)
+
+**Navigation:**
+- Module → Modulkonfigurationen → [+] Neu
+
+---
+
+### Schritt 2: Mail2Fax Modul auswählen
+
+Wähle das zuvor erstellte Mail2Fax-Modul aus.
+
+![02. Choose Mail2Fax Module](docu/Modul%20Konfiguration/02.%20Choose%20fax2mail%20Modul.png)
+
+---
+
+### Schritt 3: Instanz benennen
+
+Gib der Modul-Instanz einen eindeutigen Namen.
+
+![03. Set module name](docu/Modul%20Konfiguration/03.%20Set%20modul%20name.png)
+
+**Beispiele:**
+- "Mail2Fax - Hauptbüro"
+- "Mail2Fax - Maik"
+- "Mail2Fax - Vertrieb"
+
+---
+
+### Schritt 4: Felder ausfüllen
+
+Fülle alle erforderlichen Konfigurationsfelder aus.
+
+![04. Fill out fields](docu/Modul%20Konfiguration/04.%20Fill%20out%20fields.png)
+
+**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](docu/Modul%20Konfiguration/05.%20Aktivate%20modul%2C%20finish.png)
+
+**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`](../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](#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:**
+```bash
+# 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](README.md).
@@ -31,11 +31,26 @@ v8-9-10/

 ### 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:
+
 ```bash
 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:
+```bash
+ssh root@<starface-ip> 'systemctl restart tomcat'
+```
+
 ### 2. Block kompilieren

 ```bash
@@ -44,8 +59,45 @@ cd ..

 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:
+
+```bash
+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:
+
+```bash
+# 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](INSTALLATION.md)**
+
+### Schnellübersicht
+
 ### 1. Neues Modul erstellen
 - STARFACE Admin → Module → Module Designer
 - "Neues Modul erstellen"
@@ -63,6 +115,11 @@ Ergebnis: `Mail2FaxBlock.class` und `Mail2FaxCleanup.class`
 - **Funktion 2**: "Mail2Fax Cleanup" (Cleanup)
  - Block: Mail2FaxCleanup.class

+### Alternative: Fertig-Modul importieren
+- Datei: [`../fax2Mail_v53.sfm`](../fax2Mail_v53.sfm)
+- Import über Module Designer (inkl. aller Felder: `subjectPrefix`, `pin`, etc.)
+- Danach Instanz konfigurieren (siehe [INSTALLATION.md](INSTALLATION.md))
+
 ### 4. Eingabe-Variablen konfigurieren

 | Variable | Typ | Beschreibung | Default |