'''Belegversand''' ist eine automatisierte AppleScript-Lösung zur Verwaltung von Dokumenten-Versand in DEVONthink. Das System ermöglicht es, Belege aus einer DEVONthink-Datenbank auszuwählen, diese in ZIP-Archive zu packen (optional mit Passwort) und automatische Mail-Drafts mit konfigurierbaren Empfängern zu erstellen. Zusätzlich erfolgt strukturierte Protokollierung über Logging und Tagging-Mechanismen.

Aktuelle Softwareversion

-Version: 1.4
-Plattform: macOS 10.13+
-Abhängigkeiten: DEVONthink 4.x, Apple Mail
-Lizenz: Privatgebrauch
-Repository: https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation

Sicherheitstechnischer Hinweis!

Ich bitte zu beachten, dass die Software allenfalls minimale Sicherheitsanforderungen erfüllt.

Insbesondere liegt das Passwort für's ZIP-Archiv unverschlüsselt, im Klartext, in /_config/belegversand.conf. Wer das Passwort schützen möchte, kann das über die DB-Crypto von DEVONthink selbst tun. DEVONthink hat eine Datenbank-Verschlüsselung in den Bordmitteln.

Dann bleibt trotzdem der zweite Schwachpunkt: Die ZIP-Verschlüsselung wird in dieser Version 1.4 über das Shell-Tool zip -P auf der Konsolenzeile realisiert. Dahinter steckt das veraltete und kryptographisch schwache ZipCrypto-Verfahren.

Ganz deutlich:

Diese Belegversand-Automatisation hab' ich mir gebaut, um innerhalb weniger Sekunden Tankbelege, Einkaufszettel und Restaurant-Quittungen an die Steuerberatung zu verschicken - und den Überblick darüber zu behalten, was schon dort ist, und was noch nicht. Dafür sind die Skripte prima! Falls es eine Version 1.5 geben sollte, ersetze ich zip -P vermutlich durch eine starke AES-Verschlüsselung, und das Passwort kommt als Hash-Wert in die Config-Datei.

Bis dahin jedoch gilt ganz klar: Wer mit diesen Skripten, in dieser Version 1.4, sicherheitsrelevante Dokumente verschickt, tut das auf eigene Gefahr und handelt potentiell fahrlässig!

Installation

Voraussetzungen

macOS 10.13 oder neuer
DEVONthink 4.x
Apple Mail
AppleScript-Zugriff in Systemeinstellungen aktiviert
Git (zum Klonen des Repositories)

Schritt-für-Schritt Anleitung

1. Verzeichnisstruktur anlegen

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

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

2. Repository klonen

git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand cd Belegversand

3. Scripts kompilieren

Dies ist ein '''wichtiger Schritt''' und darf nicht übersprungen werden! chmod +x compile.sh ./compile.sh

Erwartete Ausgabe: Compiliere Belegversand AppleScripts... ✓ Fertig!

4. Erste Ausführung

DEVONthink öffnen
Eine Gruppe (Ordner) in der gewünschten Datenbank auswählen
Scripts → START aufrufen -Dialog folgen → Setup wird durchgeführt

Das Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink:

Nach der ersten Ausführung erstellt das System automatisch folgende Struktur in DEVONthink:

_config/
├── belegversand.conf              # Konfigurationsdatei
├── mail_vorlagen/                 # Mail-Templates
│   └── belegversand               # Standard-Template
├── README-Belegversand            # Interne Hilfe
└── [weitere Dateien nach Versand]

Wichtig: .applescript vs. .scpt Dateien

Im Repository liegen AppleScript-Dateien:

.applescript: Das sind die Quelldateien (Textfiles, Git kann versionieren und tracken)
.scpt: Kompilierte Skripte (binär, werden von DEVONthink ausgeführt)

'''Kritisch:''' Die .applescript-Quelldateien funktionieren '''nicht''' direkt in DEVONthink. Sie enthalten relative Pfade, die zur Laufzeit expandiert werden müssen.

Daher liegt das compile.sh-Script im Repo. Es muss, nach git clone, nur ein Mal ausgeführt werden. Es...

Kompiliert alle .applescript zu .scpt
Löscht anschließend die .applescript-Dateien
Hinterlässt nur funktionsfähige .scpt-Dateien

Falls nach dem Clone noch .applescript-Dateien vorhanden sind, war compile.sh nicht erfolgreich. In diesem Fall erneut ausführen und auf Fehlermeldungen achten.

Konfiguration

Automatische Initialisierung

Nach der ersten Ausführung erstellt das System in der aktuellen DEVONthink-Datenbank unter _config die Steuerverzeichnisse. Die Konfigurationsdatei belegversand.conf befindet sich in DEVONthink unter _config → belegversand.conf.

Wichtigste Parameter

MAIL_TO_DEFAULT: Standard-Empfänger (z.B. steuer@example.com)
MAIL_CC_TO_DEFAULT: Standard-CC-Empfänger (optional)
MAIL_SUBJECT_PREFIX: Präfix für den Mail-Betreff (z.B. "Belegversand")
ZIP_PASSWORD_DEFAULT: Standard-Passwort für ZIP-Archive (optional, keine Sonderzeichen)
LOG_SENT_GROUP_NAME: Name der Ordnergruppe für Versandprotokolle (Standard: "Versendet")
SENT_TAG_FOR_DOCS: Tag für versendete Belege (Standard: "gesendet")
WRITE_DEBUG_LOG: Debug-Logging aktivieren (true/false)
SHOW_README: Willkommensdialog beim Start anzeigen (true/false)
MAILBODY_FOLDER_NAME: Ordner für Mail-Templates (Standard: "mail_vorlagen")
MAILBODY_RECORD_NAME: Name des Standard-Templates (Standard: "belegversand")
PATH_TO_DRYRUN_PREVIEW: Speicherort der Dry-Run Vorschau-Datei

Multiple Empfänger (CSV-Format)

Mehrere E-Mail-Adressen können durch Kommas getrennt werden:

Die Adressen werden automatisch geparst und in Apple Mail einzeln eingefügt.

Verwendung

Grundablauf

Belege in DEVONthink auswählen (Mehrfachauswahl möglich)
Scripts → START aufrufen
Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
Dry-Run Vorschau anschauen (optional) -Echtlauf → ZIP-Archive erstellt, Mail-Draft geöffnet, Logging durchgeführt

Menü-Befehle

START: Haupteinstiegspunkt — startet Setup oder Versand
About...: About-Dialog mit Versionsinformation und Links

Booking-Jahr Enforcement

Die Gruppen-Struktur innerhalb von DEVONthink für ein Buchungsjahr sieht so aus:

Belege/
├── 2026/
│   ├── 01_Januar/
    ├── 02_Februar/
    ├── .../
    ├── Provisionsabrechnungen/
│   └── Versendet/ [← Logs für Dokument-Versand-Vorgänge aus dem aktuellen Buchungsjahr]
├── 2027/
│   ├── 01_Januar/
    ├── .../
│   └── Versendet/ [← Logs]
└── Provisionsabrechnungen/
Versendet_Outsider/ [← Separate Outsider-Logs für Doks, die außerhalb von Buchungsjahres-Gruppen versendet wurden.]

Das System verhindert Versandvermischung über mehrere Jahre:

Mixed-Year Selection: Werden Belege aus verschiedenen Jahren auswählt, wird ein Fehler zurückgewiesen
Separate Protokolle: Jedes Buchungsjahr hat eigene Versendet-Ordner mit separaten Logs
Outsider-Belege: Dokumente außerhalb der Jahresstruktur werden separat gehandhabt

Dry-Run Modus

Vor jedem echten Versand kann ein Dry-Run durchgeführt werden:

Simuliert den kompletten Versandprozess
Erstellt Vorschau-Datei mit allen Details
Zeigt Dialog mit Zusammenfassung
User kann bestätigen oder abbrechen

Die Vorschau-Datei wird auf der lokalen Festplatte gespeichert (Pfad konfigurierbar).

Mail-Drafts

Das System erstellt keinen automatischen Versand, sondern Mail-Drafts:

ZIP-Archive werden erzeugt
Apple Mail öffnet mit neuem Draft (nicht gesendet!)
User kann Template prüfen, weitere Empfänger hinzufügen
Benutzerdefinierter Versand per Knopfdruck in Mail

Dies ermöglicht volle Kontrolle über den Versand.

Mail-Templates

Seit Version 1.4 unterstützt der Belegversand beliebig viele Mail-Templates. Templates werden aus DEVONthink geladen (_config/mail_vorlagen/).

Das System zeigt einen Dialog zur Template-Auswahl, wenn mehrere Vorlagen vorhanden sind.

Protokollierung

Die Versende-Vorgänge werden zweifach protokolliert.

Maschinell lesbar im *.JSON-Lines Format für technische Weiterverarbeitung:
Menschlich lesbar, im *.MD-Format, mit Übersichten nach Versandlauf:

Troubleshooting

Scripts funktionieren nicht

Problem: "Script nicht gefunden"

Häufigste Ursache: compile.sh wurde nicht ausgeführt.

Lösung:

Prüfen ob .scpt-Dateien vorhanden sind: ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/
Falls nur .applescript-Dateien vorhanden → ./compile.sh erneut ausführen
Auf Fehlermeldungen achten

Problem: Script-Zugriff verweigert

Lösung:

System Settings → Privacy & Security → Automation
DEVONthink sollte mit entsprechenden Rechten gelistet sein
Script Editor öffnen und START.scpt öffnen
Compile (⌘K) — sollte ohne Fehler durchlaufen

ZIP wird nicht erstellt

-ZIP-Passwort in Config überprüfen (###Keine### Sonderzeichen, keine Leerzeichen!)

Ausreichend Festplatte vorhanden?
Staging-Ordner in DEVONthink beschreibbar?

Mail-Draft öffnet sich nicht

Apple Mail ist geöffnet?
Script-Zugriff für Mail aktiviert?
Mail-Templates-Ordner vorhanden?

"Mixed-Year-Selection"-Fehler

Dies ist kein Fehler, sondern Schutz vor Versandvermischung:

Lösung 1: Nur Belege aus einem Buchungsjahr auswählen
Lösung 2: Belege in mehreren Versänden verteilen

Debug-Informationen aktivieren

In belegversand.conf: WRITE_DEBUG_LOG=true Debug-Logs erscheinen dann in /tmp/DT-Belegversand-debug.log.

== Versionshistorie ==

1.4: Booking-Jahr Enforcement, Kompilierungs-Automation, About-Dialog, Wiki-Integration
1.3: Dry-Run Verbesserungen, Markdown-Logs
1.2: Mail-Templates in DEVONthink, interne README
1.1: Konfigurationssystem
1.0: Erste funktionale Version

Entwicklung

Quellcode liegt als .applescript-Dateien vor (lesbar, git-freundlich).

Zur lokalen Entwicklung:

Quelldateien (.applescript) editieren
./compile.sh ausführen
In DEVONthink testen
Bei Änderungen: ./compile.sh erneut ausführen

Lizenz:

OpenSource, MIT-License

Support

Für technische Fragen oder Probleme:

Wiki-Dokumentation durchlesen (diese Seite)
Debug-Log aktivieren und analysieren
Im Gitea-Repository ein Issue erstellen (falls Zugriff vorhanden)

Externe Links

[Dieses Repo] (https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation)
[DEVONthink-Homepage] (https://www.devontechnologies.com)
[Wiki-Artikel auf Tuxi] (https://wiki.tuxi.ddnss.de/wiki/Belegversand)
[Apple Mail Documentation] (https://support.apple.com/mail)