Belegversand

Belegversand

Übersicht

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.

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 Tankbelege, Einkaufszettel und Restaurant-Quittungen an die Steuerberatung zu verschicken! Dafür sind sie 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!

Version

1.4

Plattform

macOS 10.13+

Abhängigkeiten

DEVONthink 3.x, Apple Mail

Lizenz

Privatgebrauch

Repository

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

Installation

Voraussetzungen

• macOS 10.13 oder neuer
• DEVONthink 3.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!

<source lang="bash"> chmod +x compile.sh ./compile.sh </source>

Erwartete Ausgabe: <source> Compiliere Belegversand AppleScripts... ✓ Fertig! </source>

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 Setup-Script erstellt automatisch alle notwendigen Ordnerstrukturen und Konfigurationsdateien in DEVONthink.

Wichtig: .applescript vs. .scpt Dateien

Im Repository gibt es zwei Arten von AppleScript-Dateien:

.applescript

Quelldateien (lesbar, nur für Entwicklung)

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

Das `compile.sh`-Script:

1. Kompiliert alle `.applescript` zu `.scpt`
2. Löscht anschließend die `.applescript`-Dateien
3. 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 automatisch folgende Struktur in DEVONthink:

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

Konfigurationsdatei

Die Datei `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:

MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com

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

Verwendung

Grundablauf

1. Belege in DEVONthink auswählen (Mehrfachauswahl möglich)
2. Scripts → START aufrufen
3. Dialog beantwortet (Empfänger, ZIP-Passwort, Dry-Run?)
4. Dry-Run Vorschau anschauen (optional)
5. 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

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

Beispiel-Struktur:

Belege/
├── 2026/
│   ├── 01_Januar/
    ├── 02_Februar/
    ├── .../
│   └── Versendet/ [← Logs]
├── 2027/
│   └── Versendet/ [← Logs]
└── Provisionsabrechnungen/
    └── [← Separate Outsider-Logs]

Dry-Run Modus

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

1. Simuliert den kompletten Versandprozess
2. Erstellt Vorschau-Datei mit allen Details
3. Zeigt Dialog mit Zusammenfassung
4. 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:

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

Dies ermöglicht volle Kontrolle über den Versand.

Mail-Templates

Templates werden aus DEVONthink geladen (`_config/mail_vorlagen/`).

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

Beispiel-Template:

<source> Sehr geehrte/r Frau/Herr,

beiliegend erhalten Sie die angeforderten Unterlagen.

Mit freundlichen Grüßen </source>

Protokollierung

Die Versandvorgänge werden jeweils doppelt protokolliert:

1. Zum einen im maschinenlesbaren json-Format, für technische Weiterverarbeitung.

2. Zum anderen im menschlich lesbaren Mark-Down-Textformat, mit Übersichten nach Versandlauf.

Die Protokolle liegen entweder in der DEVONthink-Gruppe /Versendet des aktuellen Buchungsjahres. Das gilt, wenn Dokumente innerhalb eines Jahresordners liegen und einem Monat zugeordnet sind (siehe oben, Abschnitt Booking-Jahr Enforcement).

Dokumente, die nicht Teil eines Buchungsjahres sind, werden in der Gruppe /Versendet_Outsider abgelegt. Diese Gruppe liegt neben /_config unmittel an der Datenbankwurzel.

Troubleshooting

Scripts funktionieren nicht

Problem: "Script nicht gefunden"

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

Lösung:

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

Problem: Script-Zugriff verweigert

Lösung:

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

ZIP wird nicht erstellt

• ZIP-Passwort in Config überprüfen (keine Sonderzeichen!)
• 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`:

<source> WRITE_DEBUG_LOG=true </source>

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:

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

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

• Repository
• DEVONthink Homepage
• Apple Mail Documentation