403 lines
11 KiB
Markdown
403 lines
11 KiB
Markdown
# 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`](../fax2Mail_v54.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.
|
|
|
|
|
|
|
|
**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`](../fax2Mail_v54.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.
|
|
|
|
> **⚠️ 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:**
|
|
```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).
|