# 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 Steuerberatungskommunikation. 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 --- ## ⚠️ 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ü 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.