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
About-Dialog: Integrierte Hilfe im DEVONthink-Menü

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:

Kompiliert alle .applescript zu .scpt
Löscht danach die .applescript-Quelldateien
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

DEVONthink öffnen
Ein Objekt in der gewünschten Datenbank auswählen
Scripts → START aufrufen
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:

Listet alle zu versendenden Belege auf
Erstellt Vorschau-Datei mit Details
Zeigt Dialog mit Zusammenfassung
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:

ZIP-Archive mit Belegen werden erstellt
Apple Mail öffnet mit neuem Draft (nicht gesendet!)
User kann Template ändern, weitere Empfänger hinzufügen
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

Verzeichnisstruktur überprüfen:

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

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

Falls nur .applescript-Dateien vorhanden → ./compile.sh ausführen!
Script-Zugriff in Systemeinstellungen überprüfen:
- System Settings → Privacy & Security → Automation
- DEVONthink sollte dort mit entsprechenden Rechten gelistet sein
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.