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 liegen AppleScript-Dateien.

Dateiendung	Bedeutung	Nutzung
.applescript	Quelldateien (Lesbar)	Nur für Entwicklung/Versionskontrolle

DEVONthink arbeitet mit den kompilierten Versionen dieser Dateien!

Dateiendung	Bedeutung	Nutzung
.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 einmalig 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ü)
├── 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:

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

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:

set expandedPath to (do shell script "echo ~") & "/" & basePath

wobei basePath relativ definiert ist:

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:

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

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.