Public Access
Automatisierter Belegversand für DEVONthink hinzugefügt
@@ -0,0 +1,311 @@
|
|||||||
|
= 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.
|
||||||
|
|
||||||
|
; 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 ====
|
||||||
|
|
||||||
|
<source lang="bash">
|
||||||
|
mkdir -p ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
|
||||||
|
cd ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/
|
||||||
|
</source>
|
||||||
|
|
||||||
|
==== 2. Repository klonen ====
|
||||||
|
|
||||||
|
<source lang="bash">
|
||||||
|
git clone https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation.git Belegversand
|
||||||
|
cd Belegversand
|
||||||
|
</source>
|
||||||
|
|
||||||
|
==== 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 ====
|
||||||
|
|
||||||
|
# DEVONthink öffnen
|
||||||
|
# Ein Objekt 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.
|
||||||
|
|
||||||
|
== 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:
|
||||||
|
# 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 automatisch folgende Struktur in DEVONthink:
|
||||||
|
|
||||||
|
<source>
|
||||||
|
_config/
|
||||||
|
├── belegversand.conf # Konfigurationsdatei
|
||||||
|
├── mail_vorlagen/ # Mail-Templates
|
||||||
|
│ └── belegversand # Standard-Template
|
||||||
|
├── README-Belegversand # Interne Hilfe
|
||||||
|
└── [weitere Dateien nach Versand]
|
||||||
|
</source>
|
||||||
|
|
||||||
|
=== 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:
|
||||||
|
|
||||||
|
<source>
|
||||||
|
MAIL_TO_DEFAULT=recipient1@example.com, recipient2@example.com
|
||||||
|
MAIL_CC_TO_DEFAULT=cc1@example.com, cc2@example.com
|
||||||
|
</source>
|
||||||
|
|
||||||
|
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 ===
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
<source>
|
||||||
|
Belege/
|
||||||
|
├── 2026/
|
||||||
|
│ ├── 01_Januar/
|
||||||
|
│ ├── [weitere Monate]
|
||||||
|
│ └── Versendet/ [← Logs für 2026-Versand]
|
||||||
|
├── 2027/
|
||||||
|
│ ├── 01_Januar/
|
||||||
|
│ ├── [weitere Monate]
|
||||||
|
│ └── Versendet/ [← Logs für 2027-Versand]
|
||||||
|
└── Provisionsabrechnungen/
|
||||||
|
└── [← Separate Outsider-Logs]
|
||||||
|
</source>
|
||||||
|
|
||||||
|
=== 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 ===
|
||||||
|
|
||||||
|
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 ==
|
||||||
|
|
||||||
|
=== NDJSON-Logs ===
|
||||||
|
|
||||||
|
Maschinell lesbar im JSON-Lines Format für technische Weiterverarbeitung:
|
||||||
|
|
||||||
|
<source lang="json">
|
||||||
|
{"timestamp":"2026-01-15T10:30:45Z","type":"record","record_uuid":"abc123","record_name":"Invoice-001","status":"sent"}
|
||||||
|
{"timestamp":"2026-01-15T10:30:46Z","type":"email","to":"recipient@example.com","zip_file":"archive.zip","status":"created"}
|
||||||
|
{"timestamp":"2026-01-15T10:30:47Z","type":"tag","record_uuid":"abc123","tag":"gesendet","status":"applied"}
|
||||||
|
</source>
|
||||||
|
|
||||||
|
=== Markdown-Logs ===
|
||||||
|
|
||||||
|
Menschlich lesbar mit Übersichten nach Versandlauf:
|
||||||
|
|
||||||
|
<source>
|
||||||
|
# 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]
|
||||||
|
**Status:** Erfolgreich
|
||||||
|
|
||||||
|
### Versandte Dokumente
|
||||||
|
- Invoice-001 (UUID: abc123...)
|
||||||
|
- Invoice-002 (UUID: def456...)
|
||||||
|
...
|
||||||
|
</source>
|
||||||
|
|
||||||
|
== 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: <code>ls ~/Library/Application\ Scripts/com.devon-technologies.think/Menu/Belegversand/Helpers/scripts/</code>
|
||||||
|
# Falls nur `.applescript`-Dateien vorhanden → <code>./compile.sh</code> 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!)
|
||||||
|
* 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:
|
||||||
|
# Quelldateien (`.applescript`) editieren
|
||||||
|
# `./compile.sh` ausführen
|
||||||
|
# In DEVONthink testen
|
||||||
|
# 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 ==
|
||||||
|
|
||||||
|
* [https://gitea.tuxi.ddnss.de/enchiriadis/DEVONthink-Belegversand-Automatisation Repository] (privat, erfordert Zugriff)
|
||||||
|
* [https://www.devontechnologies.com DEVONthink Homepage]
|
||||||
|
* [https://support.apple.com/mail Apple Mail Documentation]
|
||||||
Reference in New Issue
Block a user