# 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.

![01. Create Module and Description](screenshots/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](screenshots/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](screenshots/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](screenshots/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](screenshots/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](screenshots/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](screenshots/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](screenshots/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](screenshots/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](screenshots/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](screenshots/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](screenshots/Modul%20Konfiguration/02.%20Choose%20fax2mail%20Modul.png)

---

### Schritt 3: Instanz benennen

Gib der Modul-Instanz einen eindeutigen Namen.

![03. Set module name](screenshots/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](screenshots/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](screenshots/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_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).