enchiriadis/DEVONthink-Belegversand-Automatisation
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a3c500f2aa0a6516f9e8f038fb21f4ef659f9ae1
DEVONthink-Belegversand-Aut…/README.md
T
enchiriadis a3c500f2aa README.md aktualisiert 
Aktualisiert:
- ./compile.sh
- *.applescript versus *.scpt
2026-08-17 13:39:39 +00:00

341 lines
15 KiB
Markdown
Raw Blame History

# Belegversand-Automatisation für DEVONthink v1.4
Automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Ermöglicht die Auswahl von Belegen, deren Verpackung in ZIP-Archive (optional mit Passwort), automatische Mail-Drafts mit konfigurierbaren Empfängern und strukturierte Logging/Tagging-Mechanismen.
## Features v1.4
- **Booking-Jahr Enforcement**: Verhindert versehentliche Vermischung von Belegen aus verschiedenen Buchungsjahren in einem Versand
- **Intelligente Versand-Logs**: Separate NDJSON- und Markdown-Logs mit Jahres-Kontext
- **Automatische Pfadverwaltung**: Absolute Pfade via Home-Verzeichnis — funktioniert unabhängig vom Script-Speicherort
- **Template-basierte Mail-Vorlagen**: Dynamische Mailbody-Auswahl aus DEVONthink-Verzeichnis
- **CSV-Email-Parser**: Unterstützung mehrerer TO und CC Empfänger
- **ZIP-Verschlüsselung**: Optional mit benutzerdefinierten Passwörtern
- **Dokumenten-Tagging**: Automatisches Markieren versendeter Belege
- **Dry-Run Modus**: Vorschau vor echtem Versand
- **Fehlerprotokollierung**: Detaillierte Logs für Auditing und Troubleshooting
## Systemanforderungen
- macOS 10.13+
- DEVONthink 3.x
- Apple Mail
- AppleScript-Zugriff aktiviert
---
## ⚠️ WICHTIG: Quelldateien vs. Kompilierte Skripte
**LIES DAS!**
Im Repository findest du zwei Arten von AppleScript-Dateien:
| Dateiendung | Bedeutung | Nutzung |
|---|---|---|
| `.applescript` | **Quelldateien (Lesbar)** | Nur für Entwicklung/Versionskontrolle |
| `.scpt` | **Kompilierte Skripte (Binär)** | Werden von DEVONthink ausgeführt |
**Kritisch:** Die `.applescript`-Quelldateien funktionieren **NICHT** direkt in DEVONthink, weil:
- Interne Pfade sind relativ (z.B. `"Library/Application Scripts/..."`)
- Zur Laufzeit werden diese Pfade mit `echo ~` zu absoluten Pfaden expandiert
- Unkompilierte `.applescript`-Dateien führen zu Fehler wie **"Scriptdatei nicht gefunden"**
**Lösung:** Nach dem Clone **MUSS** das `compile.sh`-Skript ausgeführt werden. Dieses:
1. Kompiliert alle `.applescript` zu `.scpt`
2. Löscht danach die `.applescript`-Quelldateien
3. Hinterlässt nur funktionsfähige `.scpt`-Dateien
**Falls du die `.applescript`-Dateien siehst:**
→ `./compile.sh` wurde nicht ausgeführt oder ist fehlgeschlagen!
→ Siehe Schritt 3 der Installation unten.
---
## Installation
### Schritt 1: Verzeichnisstruktur anlegen
```bash
mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
```
### Schritt 2: Repository clonen
```bash
git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand
cd Belegversand
```
Alternativ: ZIP von der Gitea-Website herunterladen und entpacken.
### Schritt 3: Scripts kompilieren (NOTWENDIG!)
```bash
chmod +x compile.sh
./compile.sh
```
**Erwartete Ausgabe:**
```
Compiliere Belegversand AppleScripts...
✓ Fertig!
```
**Wenn Fehler auftritt:**
```bash
# Sicherstellen, dass bash vorhanden ist (sollte bei macOS Standard sein)
which bash
# Oder manuell mit osacompile testen:
osacompile -o START.scpt START.applescript
```
Nach erfolgreicher Kompilierung:
- ✓ Alle `.applescript`-Quelldateien sind gelöscht
- ✓ Alle `.scpt`-Skripte sind vorhanden und einsatzbereit
- ✓ DEVONthink kann die Skripte ausführen
### Schritt 4: Verzeichnisstruktur prüfen
Nach Installation sollte folgende Struktur vorhanden sein:
```
Belegversand/
├── START.scpt # Einstiegspunkt (sichtbar in DEVONthink-Menü)
├── README.md # Diese Datei
├── compile.sh # Kompilierungs-Skript (nach Nutzung nicht mehr nötig)
├── Change.log # Changelog
├── Helpers/
│ ├── show_mail_templates.scpt # Dialog für Template-Auswahl
│ ├── create-year-cycle.scpt # Erstellt Jahres-Ordnerstruktur
│ ├── uuid_anzeigen.scpt # Utility zum Anzeigen von Record-UUIDs
│ └── scripts/
│ ├── _belegversand_setup.scpt # Initialisierung & Konfiguration
│ └── _belegversand.scpt # Hauptlogik (Versand, Logging)
└── [weitere Dateien nach erster Ausführung]
```
**Hinweis:** `.applescript`-Dateien sollten NICHT vorhanden sein. Falls doch → `./compile.sh` erneut ausführen.
### Schritt 5: Erste Ausführung
1. DEVONthink öffnen
2. Ein Objekt in der gewünschten Datenbank auswählen
3. Scripts → `START` aufrufen
4. Dialog folgen → Setup wird durchgeführt
Das Setupscript erstellt automatisch notwendige Ordnerstrukturen und Konfigurationsdateien.
## Konfiguration
### Automatische Initialisierung
Nach erster Ausführung wird folgende Struktur in DEVONthink angelegt:
```
_config/
├── belegversand.conf # Konfigurationsdatei
├── mail_vorlagen/ # Mail-Templates
│ └── belegversand # Default-Template
├── README-Belegversand # Interne Dokumentation
└── [Logging-Verzeichnisse nach Bedarf]
```
### Konfigurationsdatei (belegversand.conf)
Zugänglich über DEVONthink → `_config` → `belegversand.conf`
Wichtigste Einträge:
| Key | Beispiel | Bedeutung |
| ---------------------- | ----------------------- | ----------------------------------- |
| `SHOW_README` | `true` | Zeigt Willkommens-Dialog beim Start |
| `MAIL_TO_DEFAULT` | `recipient@example.com` | Standard TO-Empfänger |
| `MAIL_CC_TO_DEFAULT` | `cc@example.com` | Standard CC-Empfänger |
| `SUBJECT_PREFIX` | `Belegversand` | Mail-Betreff Präfix |
| `ZIP_PASSWORD_DEFAULT` | `12345` | Default ZIP-Passwort |
| `SENT_TAG_FOR_DOCS` | `gesendet` | Tag für versendete Belege |
| `LOG_SENT_GROUP_NAME` | `Versendet` | Ordner für Versand-Logs |
| `WRITE_DEBUG_LOG` | `false` | Debug-Ausgaben aktivieren |
**CSV-Format für multiple Empfänger:**
```
MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
```
Die E-Mail-Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt.
## Verwendung
### Grundablauf
```
1. Belege in DEVONthink auswählen (Mehrfach-Selektion möglich)
↓
2. Scripts → START aufrufen
↓
3. Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
↓
4. Dry-Run Vorschau (optional)
↓
5. Echtlauf → ZIP + Mail-Draft + Logging + Tagging
```
### Spezielle Verhaltensweisen
#### Booking-Jahr Enforcement (v1.4)
Das Script ordnet alle ausgewählten Belege automatisch ihrem Buchungsjahr zu:
- **Mixed-Year Selection**: Wenn Sie Belege aus verschiedenen Jahren auswählen, wird das Script einen Fehler zurückweisen
- **Outsider Documents**: Belege außerhalb definierter Jahresordonner (z.B. unter `Provisionsabrechnungen`) werden separat gehandhabt
- **Separate Logging**: Jedes Buchungsjahr hat sein eigenes `Versendet`-Verzeichnis mit separaten Logs
Beispiel-Struktur:
```
Belege/
├── 2026/
│ ├── 01_Januar/ [Belege hier]
│ ├── Versendet/ [← Logs landen HIER für 2026er-Versand]
├── 2027/
│ ├── 01_Januar/ [Belege hier]
│ ├── Versendet/ [← Logs landen HIER für 2027er-Versand]
└── Provisionsabrechnungen/ [Outsider-Dokumenty]
└── [← Logs landen in entsprechend eigenen Outsider-Log]
```
#### Dry-Run Modus
Vor jedem echten Versand wird ein simulierter Durchlauf durchgeführt:
1. Listet alle zu versendenden Belege auf
2. Erstellt Vorschau-Datei mit Details
3. Zeigt Dialog mit Zusammenfassung
4. User bestätigt oder bricht ab
Die Vorschaudatei wird im DEVONthink-Verzeichnis gespeichert (konfigurierbar).
#### Mail-Draft Vorbereitung
Das Script erstellt keinen echten Versand, sondern einen **Mail-Draft**:
1. ZIP-Archive mit Belegen werden erstellt
2. Apple Mail öffnet mit neuem Draft (nicht gesendet!)
3. User kann Template ändern, weitere Empfänger hinzufügen
4. Benutzerdefinierter Versand per Knopfdruck
### Template-System
Mail-Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`):
```
Hello,
Here are your documents.
Best regards
```
Das Script zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind.
## Logging & Dokumentation
### NDJSON-Logs
Maschinell lesbare Logs im JSON-Lines Format:
```json
{"timestamp":"2026-01-15T10:30:45Z","type":"record","record_uuid":"...","record_name":"Invoice-001","status":"sent"}
{"timestamp":"2026-01-15T10:30:46Z","type":"email","to":"recipient@example.com","zip_file":"...","status":"created"}
{"timestamp":"2026-01-15T10:30:47Z","type":"tag","record_uuid":"...","tag":"gesendet","status":"applied"}
```
### Markdown-Logs
Mensch-lesbare Dokumentation mit Übersichten:
```markdown
# Belegversand Logs — 2026
## Versandlauf 2026-01-15 10:30
**Versendete Belege:** 5 Stück
**Empfänger:** recipient@example.com
**ZIP-Datei:** belegversand_2026-01-15_103045.zip
**Passwort:** [konfiguriert]
### Versandte Dokumente
- Invoice-001 (UUID: abc123...)
- Invoice-002 (UUID: def456...)
...
```
Logs werden automatisch in `_config → Versendet` gespeichert.
## Verzeichnisse und ihre Rollen
| Pfad | Funktion |
| ------------------------------------------ | -------------------------------------------------------- |
| `START.scpt` | Einstiegspunkt, delegiert zu Setup/Hauptscript |
| `compile.sh` | Kompiliert `.applescript` zu `.scpt` (nach Installation) |
| `Helpers/show_mail_templates.scpt` | Dialog-Utility für Template-Auswahl |
| `Helpers/create-year-cycle.scpt` | Erstellt 12-Monats-Struktur + Versendet-Ordner |
| `Helpers/uuid_anzeigen.scpt` | Debug-Utility: zeigt UUIDs von Records |
| `Helpers/scripts/_belegversand_setup.scpt` | Konfiguration, Initialisierung, Verzeichnis-Vorbereitung |
| `Helpers/scripts/_belegversand.scpt` | Hauptlogik: Auswahl, ZIP, Mail, Logging, Tagging |
## Pfadverwaltung
Das System verwendet **absolute Pfade basierend auf dem Home-Verzeichnis**:
```applescript
set expandedPath to (do shell script "echo ~") & "/" & basePath
```
wobei `basePath` relativ definiert ist:
```applescript
property basePath : "Library/Application Scripts/com.devon-technologies.think/Menu/Belegversand"
```
**Vorteil:** Das Script funktioniert unabhängig davon, wo es sich befindet oder von welchem Verzeichnis aus es aufgerufen wird.
**Wichtig für Entwickler:** Nach Änderungen an `basePath` **MUSS** `compile.sh` erneut ausgeführt werden, damit die Pfade korrekt in die kompilierten `.scpt`-Dateien übernommen werden.
## Fehlerbehandlung
### Häufige Fehler
| Fehler | Ursache | Lösung |
| --------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------- |
| "Script nicht gefunden" | `compile.sh` nicht ausgeführt oder `.applescript` noch vorhanden | Siehe Schritt 3 der Installation — `./compile.sh` ausführen |
| "Keine Konfiguration gefunden" | Kein `_config` in DB | Erneut `START` aufrufen → Setup durchlaufen |
| "Mixed-Year selection" | Belege aus verschiedenen Jahren | Nur Belege aus einem Jahr auswählen |
| "Mail kann nicht erstellt werden" | Apple Mail läuft nicht oder Script-Zugriff verweigert | Mail öffnen, Systemeinstellungen → Sicherheit → Script-Zugriff prüfen |
### Debug-Informationen aktivieren
In `belegversand.conf`:
```
WRITE_DEBUG_LOG=true
```
Debug-Logs erscheinen dann in `/tmp/DT-Belegversand-debug.log` mit detaillierten Informationen.
## Versionshistorie
### v1.4 (aktuell)
- **Booking-Jahr Enforcement**: Verhindert Mixed-Year-Versende
- **Separate Year-Logs**: Jedes Jahr bekommt eigene `Versendet`-Gruppe
- **Outsider Handling**: Belege außerhalb Jahresstruktur unterstützen
- **Code-Refactoring**: Robustere Pfadverwaltung
- **Kompilierungs-Automation**: `compile.sh` für automatisierte Vorbereitung
- **Kommentar-Cleanup**: Alle bekannten AppleScript-Fallstricke dokumentiert
### v1.3
- Dry Run mit Vorschau-Datei
- Markdown-Logs mit besserer Strukturierung
- Enhanced README in DEVONthink
### v1.2
- Mailbody in DEVONthink Storage verlagert
- Config-Management erweitert
### v1.1
- Konfigurationssystem eingeführt
- Setup-Script hinzugefügt
### v1.0
- Initiale Version
- ZIP-Erzeugung
- Mail-Draft-Erstellung
- Tagging und Logging
## Entwicklung und Beiträge
Quellcode liegt als `.applescript`-Dateien vor (lesbar, git-freundlich).
Zur lokalen Entwicklung:
1. Quelldateien editieren (`.applescript`)
2. `./compile.sh` ausführen
3. In DEVONthink testen
4. Bei Änderungen: `./compile.sh` erneut ausführen
Alle Scripts sind kommentiert und dokumentieren:
- Funktionale Schritte
- Parameter und Rückgabewerte
- Bekannte AppleScript-Fallstricke (reserved words, Pfadverwaltung, etc.)
Für Beiträge oder Probleme: Issues im Gitea-Repository erstellen.
## Troubleshooting
### Script funktioniert in DEVONthink-Menü nicht
1. Verzeichnisstruktur überprüfen:
```bash
ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/
```
2. Sicherstellen, dass `.scpt`-Dateien vorhanden sind (NICHT `.applescript`):
```bash
ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/
# Sollte zeigen: _belegversand.scpt, _belegversand_setup.scpt
# Sollte NICHT zeigen: _belegversand.applescript, _belegversand_setup.applescript
```
3. Falls nur `.applescript`-Dateien vorhanden → `./compile.sh` ausführen!
4. Script-Zugriff in Systemeinstellungen überprüfen:
- System Settings → Privacy & Security → Automation
- DEVONthink sollte dort mit entsprechenden Rechten gelistet sein
5. Script Editor öffnen und manuell testen:
- ~/Library/Application Scripts/... → START.scpt öffnen
- Compile (⌘K) — sollte ohne Fehler durchlaufen
- Run (⌘R) für manuellen Test
### ZIP wird nicht erstellt
- ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
- Festplatte hat genug Platz
- Staging-Ordner im DEVONthink existiert und ist beschreibbar
### Mail-Draft öffnet sich nicht
- Apple Mail ist geöffnet?
- Script-Zugriff für Mail in Systemeinstellungen aktiviert?
- Mail-Templates-Ordner vorhanden und Konfiguration korrekt?
### "Mixed-Year-Selection"-Fehler
Das ist kein Fehler, sondern Schutz vor Versandvermischung:
- Nur Belege aus **einem** Buchungsjahr auswählen
- Oder Belege in separaten Versänden verteilen
## Lizenz
Intern entwickelt für Privatgebrauch.
## Support
Für technische Fragen: Siehe `_config/README-Belegversand` in DEVONthink (interne Dokumentation) oder erstelle ein Issue im Gitea-Repository.
---
**Hinweis**: Dieses System ist eine AppleScript-Automatisierung und stark abhängig von macOS und DEVONthink-APIs. Änderungen am System können Anpassungen erfordern.
Reference in New Issue View Git Blame Copy Permalink