Belegversand

Aus Tuxipedia

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 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)
Abgerufen von „https://wiki.tuxi.ddnss.de/index.php?title=Belegversand&oldid=316“