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

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_1-4
cd Belegversand_1-4

Alternativ: ZIP von der Gitea-Website herunterladen und entpacken.

Schritt 3: Verzeichnisstruktur prüfen

Nach Installation sollte folgende Struktur vorhanden sein:

Belegversand_1-4/
├── START.scpt                    # Einstiegspunkt (sichtbar in DEVONthink-Menü)
├── README.md                     # Diese Datei
├── Änderungshistorie.txt         # 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]

Schritt 4: 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
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 basePath to (do shell script "echo ~") & "/Library/Application Scripts/com.devon-technologies.think/Menu/Belegversand_1-4"

Vorteil: Das Script funktioniert unabhängig davon, wo es sich befindet oder von welchem Verzeichnis aus es aufgerufen wird.

Fehlerbehandlung

Häufige Fehler

Fehler	Ursache	Lösung
"Script nicht gefunden"	Falsche Verzeichnisstruktur	Verzeichnisse überprüfen, Scripts neu platzieren
"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
• 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

Vollständiger Quellcode in AppleScript. 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_1-4/

2. Script-Zugriff in Systemeinstellungen überprüfen: 2. System Settings → Privacy & Security → Automation 3. DEVONthink sollte dort mit entsprechenden Rechten gelistet sein

3. Script Editor öffnen und manuell testen: 2. ~/Library/Application Scripts/... → START.scpt öffnen 3. Compile (⌘K) — sollte ohne Fehler durchlaufen 4. Run (⌘R) für manuellen Test

ZIP wird nicht erstellt

• ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
• Festplatte hat genug Platz
• Stagings-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.