Workflows

Dieses Kapitel brauchen Sie, wenn wiederkehrende Handgriffe – Tags setzen, Rechte vergeben, Belege nach Frist löschen, verschlüsselte PDFs öffnen – nicht mehr von Hand, sondern nach festen Regeln passieren sollen. In der Oberfläche heißen Workflows Arbeitsabläufe; Sie finden sie in der Seitenleiste unter Verwaltung → Attribute.

Arbeitsabläufe (Workflows) klinken sich in die Verarbeitungskette von Paperless-ngx ein – etwa, um zu steuern, welche Metadaten (Tags, Dokumenttypen) und Berechtigungen (Eigentümer, Rechte) einem Dokument zugewiesen werden. Ein Workflow besteht aus einem oder mehreren Auslösern und einer Reihe von Aktionen.

Workflows und ihre Aktionen werden der Reihe nach anhand der Sortierung angewendet. Bei „Zuweisungs"-Aktionen überschreiben spätere Aktionen frühere Zuweisungen – außer bei Feldern, die mehrere Werte aufnehmen (z. B. Tags, Zusatzfelder und Berechtigungen); diese werden zusammengeführt.

Einen Arbeitsablauf anlegen

1. Öffnen Sie Verwaltung → Attribute → Arbeitsabläufe und klicken Sie auf Arbeitsablauf hinzufügen.
2. Vergeben Sie einen Namen und eine Sortierreihenfolge; über Aktiviert schalten Sie den Workflow ein oder aus.
3. Legen Sie auf dem Reiter Auslöser mit Auslöser hinzufügen mindestens einen Auslöser an und wählen Sie den Auslösertyp (Standard: Verarbeitung gestartet). Darunter stehen die Filter, etwa Dateinamen filtern, Quellen filtern, Pfad filtern und E-Mail-Regel filtern.
4. Legen Sie auf dem Reiter Aktionen mit Aktion hinzufügen die Aktionen an und wählen Sie je Aktion den Aktionstyp. Bei einer Zuweisung erscheinen dann Felder wie Titel zuweisen, Tags zuweisen, Zusatzfelder zuweisen oder Anzeigeberechtigungen zuweisen.
5. Speichern Sie. Der Workflow greift ab jetzt bei jedem Dokument, auf das ein Auslöser passt.

Auslöser (Trigger)

Die vier Auslöser-Typen

1. Verarbeitung gestartet (Consumption Started): bevor ein Dokument aufgenommen wird. Filter können Quelle (Consume-Ordner, API und Weboberfläche oder Mail-Abruf), Dateipfad, Dateiname und E-Mail-Regel einbeziehen.
2. Dokument hinzugefügt (Document Added): nachdem ein Dokument hinzugefügt wurde. Pfad- und Quellinformationen sind dann nicht mehr verfügbar, aber der Inhalt ist ausgelesen und Metadaten wie Typ und Tags sind gesetzt – diese lassen sich nun zum Filtern nutzen.
3. Dokument aktualisiert (Document Updated): wenn ein Dokument geändert wird. Wie beim Hinzufügen kann nach Inhalt, Tags, Typ, Korrespondent oder Speicherpfad gefiltert werden.
4. Geplant (Scheduled): ein zeitgesteuerter Auslöser. Als Datum dienen das Hinzugefügt-, Erstellt- oder Aktualisiert-Datum oder ein benutzerdefiniertes (Datums-)Feld. Sie können einen Tages-Versatz angeben (positiv = nach dem Datum, negativ = davor).

Filter

Filtern können Sie nach:

• Quelle – Consume-Ordner, API (und Weboberfläche) oder Mail-Abruf.
• Dateiname, inklusive Platzhalter (z. B. *.pdf für alle PDFs).
• Dateipfad, inklusive Platzhalter.
• E-Mail-Regel – diese Auswahl erzwingt „Mail-Abruf" als Quelle.
• Inhaltsabgleich (nur bei Hinzugefügt, Aktualisiert und Geplant).

Für Hinzugefügt, Aktualisiert und Geplant gibt es zusätzlich erweiterte Filter:

• Beliebige Tags / Alle Tags / Keine Tags
• Dokumenttyp bzw. nicht diese Dokumenttypen
• Korrespondent bzw. nicht diese Korrespondenten
• Speicherpfad bzw. nicht diese Speicherpfade
• Abfrage auf Zusatzfelder (dieselbe Abfrage wie in den Filtern der Dokumentenliste)

Aktionen

Zuweisung

„Zuweisungs"-Aktionen können setzen:

• Titel (siehe Platzhalter weiter unten)
• Tags, Korrespondent, Dokumenttyp und Speicherpfad
• Dokument-Eigentümer
• Ansichts- und/oder Bearbeitungsrechte für Nutzer oder Gruppen
• Zusatzfelder, wahlweise mit Wert. Ohne Wert wird das Feld nur an das Dokument angehängt; ein bereits vorhandener Wert bleibt unberührt. Mit Wert überschreibt die Aktion einen vorhandenen Wert dieses Feldes am Dokument.

Entfernen

„Entfernen"-Aktionen können entweder alles oder gezielte Teile entfernen:

• Tags, Korrespondenten, Dokumenttypen oder Speicherpfade
• Dokument-Eigentümer
• Ansichts- und/oder Bearbeitungsrechte
• Zusatzfelder

E-Mail

„E-Mail"-Aktionen versenden Dokumente per Mail (erfordert einen eingerichteten Mailserver). Angeben lassen sich:

• die Empfängeradresse(n), durch Kommas getrennt
• Betreff und Text (können Platzhalter enthalten)
• ob das Dokument als Anhang beigefügt wird

Webhook

„Webhook"-Aktionen senden eine POST-Anfrage an eine angegebene URL. Angeben lassen sich Ziel-URL, Anfrage-Text (als Text oder Schlüssel-Wert-Paare, mit Platzhaltern), Kodierung (JSON oder Formulardaten) und Kopfzeilen (Header). Aus Sicherheitsgründen lassen sich Webhooks auf bestimmte Ports beschränken und für lokale URLs sperren.

In den Papierkorb

„In den Papierkorb"-Aktionen verschieben das Dokument in den Papierkorb. Von dort lässt es sich wiederherstellen, bis der Papierkorb geleert wird – nach der eingestellten Frist oder von Hand (siehe Historie, PDF-Aktionen & Papierkorb).

Drei Regeln gelten für diese Aktion:

• Sie wird immer zuletzt ausgeführt, unabhängig von ihrer Position in der Aktionsliste.
• Nach ihr wird kein weiterer Workflow auf das Dokument angewendet.
• Läuft sie beim Auslöser Verarbeitung gestartet, wird die Aufnahme abgebrochen und die Datei gelöscht – das Dokument entsteht dann gar nicht erst.

Passwort entfernen

„Passwort entfernen"-Aktionen versuchen, den Passwortschutz verschlüsselter PDFs aufzuheben. Sie geben ein oder mehrere Passwörter an, durch Kommas oder Zeilenumbrüche getrennt; Paperless probiert sie der Reihe nach, bis eines das Dokument öffnet.

Die Datei wird dabei nie an Ort und Stelle verändert. Passt ein Passwort, nimmt Paperless den entschlüsselten Inhalt als neue Version des Dokuments auf; die verschlüsselte Originaldatei bleibt in der Versionshistorie (siehe Dokumentversionen).

Das Verhalten hängt vom Auslöser ab:

• Verarbeitung gestartet: Das Dokument existiert zu diesem Zeitpunkt noch nicht, deshalb wird die Entschlüsselung aufgeschoben, bis die verschlüsselte Datei aufgenommen ist. Weil die Texterkennung verschlüsselte PDFs nicht lesen kann, hat diese erste Version in der Regel keinen ausgelesenen Text. Unmittelbar danach entfernt Paperless das Passwort und nimmt die entschlüsselte Datei als zweite Version auf – diesmal mit normaler Texterkennung. Kurz existiert das Dokument also als Version ohne Text.
• Dokument hinzugefügt, Dokument aktualisiert, Geplant: Das Dokument existiert bereits, die Entschlüsselung läuft sofort, und der entschlüsselte Inhalt wird als neue Version eingereiht. War schon die ursprüngliche Aufnahme verschlüsselt, fehlt dieser ersten Version ebenfalls der Text.

Einschränkung: Passwörter werden als einfache Liste ohne Beschreibung gespeichert. Für verschiedene PDF-Typen mit verschiedenen Passwörtern legen Sie getrennte Workflows an.

Remote OCR

„Remote OCR"-Aktionen schicken das Dokument statt zur lokalen Texterkennung an eine von der Administration eingerichtete externe OCR-Engine. Die Aktion hat keine Optionen – ihr Vorhandensein genügt, damit ein passendes Dokument extern verarbeitet wird. Sie funktioniert nur mit dem Auslöser Verarbeitung gestartet.

Damit die Aktion greift, muss die Administration den Remote-OCR-Modus so einstellen, dass er nur über Workflows wirkt; erst dann lassen sich einzelne Dokumente gezielt extern verarbeiten. Ist keine externe Engine eingerichtet oder unterstützt sie den Dateityp nicht, verarbeitet Paperless das Dokument lokal und schreibt eine Warnung ins Protokoll.

KI-Vorschläge anwenden

„KI-Vorschläge anwenden"-Aktionen fragen den eingerichteten KI-Dienst nach Vorschlägen für Titel und Metadaten – dieselben Vorschläge, die die Detailansicht anzeigt, nur automatisch und im Stapel übernommen. Voraussetzung ist, dass die Administration die KI-Funktionen eingeschaltet hat (siehe Automatische Zuordnung). Einstellen lassen sich:

• Welche Vorschläge übernommen werden: Titel, Tags, Korrespondent, Dokumenttyp, Speicherpfad und/oder Erstellungsdatum. Vorschläge für nicht gewählte Felder werden verworfen.
• Ob fehlende Einträge angelegt werden. Standardmäßig werden nur Tags, Korrespondenten und Dokumenttypen zugewiesen, die es bereits gibt; andere Vorschläge fallen weg. Mit dieser Option legt Paperless vorgeschlagene, noch nicht vorhandene Einträge an. Speicherpfade werden nie angelegt.
• Ob vorhandene Werte überschrieben werden. Standardmäßig wird ein Feld nur gefüllt, wenn es leer ist. Da Dokumente fast immer schon Titel und Erstellungsdatum haben, brauchen Sie diese Option meist, wenn Sie beides übernehmen wollen. Tags sind die Ausnahme: Vorgeschlagene Tags werden immer hinzugefügt und ersetzen nie die vorhandenen.

Die Aktion funktioniert mit jedem Auslöser außer Verarbeitung gestartet, weil die Vorschläge aus dem Dokumenttext entstehen und der erst nach der Verarbeitung vorliegt. Dokumente ohne erkannten Text oder mit ausschließlich Leerzeichen werden übersprungen. Weil die Anfrage an den KI-Dienst langsam ist, wird die Aktion in eine Warteschlange gestellt und im Hintergrund ausgeführt; das Dokument wird aktualisiert, sobald die Vorschläge zurückkommen.

Hinweis des Herstellers: Jedes passende Dokument löst eine Anfrage an den KI-Dienst aus. Das kann Kosten verursachen und hat Auswirkungen auf den Datenschutz. Weil die Anfragen langsam sind, kann ein Workflow, der viele Dokumente trifft, die Aufgaben-Warteschlange belegen und die Aufnahme neuer Dokumente verzögern. Der Hersteller rät, die Auslöser-Filter eng zu fassen, in kleinen Stapeln zu arbeiten und/oder mehr Worker vorzusehen.

Platzhalter (Jinja-Templates)

Titel und Webhook-Inhalte lassen sich mit Jinja-Templates↗ (öffnet in einem neuen Tab) erzeugen. Das erlaubt auch logische Strukturen und Filter. Welche Platzhalter verfügbar sind, hängt vom Auslöser-Typ ab (bei der Aufnahme sind automatische Tags o. Ä. noch nicht gesetzt).

Mit jedem Auslöser-Typ verfügbar:

• {{correspondent}} – zugewiesener Korrespondentenname
• {{document_type}} – zugewiesener Dokumenttyp
• {{owner_username}} – Benutzername des Eigentümers
• {{added}} – Hinzugefügt-Zeitpunkt, dazu {{added_year}}, {{added_year_short}}, {{added_month}}, {{added_month_name}}, {{added_month_name_short}}, {{added_day}} und {{added_time}} (Format HH:MM)
• {{original_filename}} – ursprünglicher Dateiname ohne Endung
• {{filename}} – aktueller Dateiname ohne Endung (bei Hinzugefügt unter Umständen noch nicht endgültig – dann {{original_filename}} verwenden)
• {{doc_title}} – aktueller Dokumenttitel (nicht bei der Titel-Zuweisung nutzbar)

Nur bei Hinzugefügt oder Aktualisiert zusätzlich:

• {{created}} – Erstellt-Zeitpunkt, dazu {{created_year}}, {{created_year_short}}, {{created_month}}, {{created_month_name}}, {{created_month_name_short}}, {{created_day}} und {{created_time}} (Format HH:MM)
• {{doc_url}} – URL zum Dokument in der Weboberfläche (setzt voraus, dass die Administration die Adresse der Instanz hinterlegt hat)
• {{doc_id}} – die Dokument-ID, wie sie in der Kopfzeile der Detailansicht steht

Beispiele

{{ created | localize_date('MMMM', 'en_US') }}
<!-- Ausgabe: "January" -->

{{ added | localize_date('MMMM', 'de_DE') }}
<!-- Ausgabe: "Juni" -->

Berechtigungen für Workflows

Alle Nutzer mit dem Recht, Workflows zu bearbeiten, sehen denselben Satz an Workflows. Workflows haben bewusst keinen eigenen Eigentümer und keine eigenen Berechtigungen. Da sie weitreichend wirken können – bis hin zum Ändern von Dokument-Berechtigungen –, sollten Sie den Zugriff auf Workflows bewusst einschränken.

Typische Fehler

• Remote OCR am falschen Auslöser. Die Aktion wirkt nur bei Verarbeitung gestartet. An Hinzugefügt oder Geplant gehängt, passiert nichts.
• KI-Vorschläge an „Verarbeitung gestartet". Umgekehrt: Diese Aktion braucht den Dokumenttext und funktioniert deshalb mit jedem Auslöser außer diesem.
• Nach „In den Papierkorb" noch etwas erwartet. Die Aktion läuft immer als Letztes, und danach greift kein weiterer Workflow. Ein zweiter Workflow, der das Dokument vorher noch bearbeiten soll, muss in der Sortierung davor stehen.
• Feld ohne Wert zugewiesen. Eine Zuweisung ohne Wert hängt das Feld nur an; wer einen Wert erwartet, muss ihn in der Aktion eintragen.

Weiter mit

• Benutzerdefinierte Felder – welche Feldtypen es gibt und wie Werte gesetzt werden.
• Dokumentversionen – was mit der Version entsteht, die „Passwort entfernen" anlegt.
• Berechtigungen & Teilen – Rechte, die Workflows setzen oder entfernen.