Public Access
383 lines
14 KiB
Markdown
383 lines
14 KiB
Markdown
# 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.
|
|
|
|
Ausführliche Dokumentation hier im Wiki, sowie auf:
|
|
https://wiki.tuxi.ddnss.de/wiki/Belegversand
|
|
|
|
DEVONthink (c) Datenbank-Software:
|
|
https://www.devontechnologies.com/de/apps/devonthink
|
|
|
|
**Hinweis:**
|
|
Dieses Projekt ist als privates Projekt mit Hilfe verschiedener KI-Modelle entstanden. Es wurde mit AI-Support getestet, ge-debuggt und dokumentiert.
|
|
Der Projektersteller nutzt die Skripte als Hilfe bei Buchhaltung und nicht-sicherheitsrelevanter Belegübermittlung an's Steuerberatungsbüro. Sie unterstützen aber jeden Kontext, bei dem aus DEVONthink heraus Dokumente per Mail geteilt werden sollen.
|
|
|
|
## 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
|
|
- **About-Dialog**: Integrierte Hilfe im DEVONthink-Menü
|
|
|
|
## Systemanforderungen
|
|
|
|
- macOS 10.13+
|
|
- DEVONthink 4.x
|
|
- Apple Mail
|
|
- AppleScript-Zugriff aktiviert
|
|
|
|
## ☢️ Sicherheitsrelevante Einschränkungen
|
|
Ich bitte zu beachten, dass die Software lediglich minimale Sicherheitsanforderungen erfüllt.
|
|
- Insbesondere liegt das Passwort für's ZIP-Archiv unverschlüsselt, im Klartext, in /_config/belegversand.conf.
|
|
- Die Crypto selbst wird in dieser Version 1.4 über das Shell-Tool zip -P auf der Konsolenzeile realisiert. Dahinter steckt das veraltete und kryptographisch schwache ZipCrypto-Verfahren.
|
|
|
|
**Ganz deutlich:** Diese Belegversand-Automatisation hab' ich mir gebaut, um Tankbelege und Restaurant-Quittungen an die Steuerberatung zu verschicken!
|
|
Dafür sind sie prima!
|
|
Wer hingegen mit diesen Skripten sicherheitsrelevante Dokumente verschickt, tut das auf eigene Gefahr und handelt fahrlässig!
|
|
|
|
---
|
|
|
|
## ⚠️ WICHTIG: Quelldateien vs. Kompilierte Skripte
|
|
|
|
**LIES DAS!**
|
|
|
|
In diesem Repository findest du AppleScript-Dateien.
|
|
|
|
| Dateiendung | Bedeutung | Nutzung |
|
|
|---|---|---|
|
|
| `.applescript` | **Quelldateien (Lesbar)** | Nur für Entwicklung/Versionskontrolle |
|
|
|
|
*.appelscript-Files sind reine Textdateien. Sie können von Git versioniert und getrackt werden.
|
|
Innerhalb von DEVONthink werden allerdings die kompilierten Versionen dieser Dateien verwendet!
|
|
|
|
| Dateiendung | Bedeutung | Nutzung |
|
|
|---|---|---|
|
|
| `.scpt` | **Kompilierte Skripte (Binär)** | Werden von DEVONthink ausgeführt |
|
|
|
|
Um die *.scpt-Files zu erzeugen, verwendest du bitte die Datei:
|
|
compile.sh
|
|
|
|
DETAILS hierzu:
|
|
|
|
**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ü)
|
|
├── About.scpt # About-Dialog (sichtbar in DEVONthink-Menü)
|
|
├── README.md # Diese Datei
|
|
├── compile.sh # Kompilierungs-Skript (nach Nutzung nicht mehr nötig)
|
|
├── Change.log # Changelog
|
|
├── Helpers/
|
|
│ ├── about.scpt # About-Dialog (Menü)
|
|
│ ├── 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/
|
|
│ ├── _text_about.scpt # Zentrale About-Text-Generierung
|
|
│ ├── _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. Eine Gruppe (Ordner) in der gewünschten Datenbank auswählen
|
|
3. Im DEVONthink Scripte-Menü <img src=".gitea/dt-scripts.webp" width="16" height="22" alt="DEVONthink-Script-Symbol"> → `Belegversand->START` aufrufen
|
|
4. Dialog folgen → Setup wird durchgeführt
|
|
|
|
Das Setupscript erstellt die notwendigen Ordnerstrukturen und Konfigurationsdateien innerhalb der DEVONthink-Datenbank.
|
|
|
|
---
|
|
|
|
## 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 |
|
|
| `MAIL_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
|
|
```
|
|
|
|
### Menü-Befehle
|
|
|
|
| Befehl | Funktion |
|
|
|--------|----------|
|
|
| `START` | Haupteinstiegspunkt — startet Setup oder Versand |
|
|
| `About...` | About-Dialog mit Versionsinformation und Links |
|
|
|
|
### 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-Dokumente]
|
|
└── [← 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.
|
|
|
|
---
|
|
|
|
## Dokumentation
|
|
|
|
Ausführliche Dokumentation im Wiki:
|
|
**[Belegversand-Wiki](https://wiki.tuxi.ddnss.de/wiki/Belegversand)**
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
---
|
|
|
|
## Versionshistorie
|
|
|
|
Siehe [CHANGELOG](./CHANGELOG.txt)
|
|
|
|
---
|
|
|
|
## Support
|
|
|
|
Für technische Fragen:
|
|
- Siehe [Wiki-Dokumentation](https://wiki.tuxi.ddnss.de/wiki/Belegversand)
|
|
- Oder erstelle ein Issue im Gitea-Repository (falls Zugriff vorhanden)
|
|
|
|
---
|
|
|
|
**Hinweis**: Dieses System ist eine AppleScript-Automatisierung und stark abhängig von macOS und DEVONthink-APIs. Änderungen am System können Anpassungen erfordern.
|