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

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

mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/

Schritt 2: Repository clonen

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!)

chmod +x compile.sh
./compile.sh

Erwartete Ausgabe:

Compiliere Belegversand AppleScripts...
✓ Fertig!

Wenn Fehler auftritt:

# 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. Ein Objekt in der gewünschten Datenbank auswählen
3. Im DEVONthink Scripte-Menü → Belegversand->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
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:

{"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:

# 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

---

Troubleshooting

Script funktioniert in DEVONthink-Menü nicht

1. Verzeichnisstruktur überprüfen:

ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/

2. Sicherstellen, dass .scpt-Dateien vorhanden sind (NICHT .applescript):

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

---

Support

Für technische Fragen:

• Siehe Wiki-Dokumentation
• 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.