Paperless-ngx, Teil 14: Automatisierte Ablage auf Speicherpfaden

In Teil 4 der Serie bin ich bereits auf Speicherpfade eingegangen. Mit dieser Funktion erhält die Dokumentenablage eine Ordner-Struktur, die sich in jedem Filemanager aufrufen lässt. Der besondere Pluspunkt ist aus meiner Sicht, dass man mit der Verwendung von Speicherpfaden unabhängiger von dem Paperless-ngx-Tool wird. Sollte je einmal etwas gar nicht mehr funktionieren, so kann man ohne zusätzliche Konvertierung auf alle Dokumente zugreifen. Denn die Übersicht via Ordnerstruktur funktioniert immer und überall. Diese Art der Ablage lässt sich nun sehr einfach automatisieren, so dass neue Dokumente sofort im gewünschten Ordner landen.

Keep it simple!

Ich werde hier eine sehr einfache Struktur beschreiben, die trotzdem auch für langjährige Archive mit großen Datenmengen tauglich ist. Grundsätzlich hat man es dabei nur mit zwei Ordner-Varianten zu tun:

  1. „zeitlose“ Basisordner
    In diese Ordner wandern besonders wichtige Dokumente, die über Jahre hinweg ihre Gültigkeit behalten: Verträge, Haus-/Autokauf, Versicherungen, Zeugnisse usw. Im einfachsten Fall genügt dafür ein einziger Ordner, die Dokumente unterscheidet man dann nach Namen. Bewährt haben sich aber zwei bis vier Unterordner, z. B. alle Versicherungsunterlagen in den Ordner „Versicherungen“.
  2. chronologische Archiv-Ordner
    Steuerunterlagen, Handwerkerrechnungen, Reisebelege, Projektentwürfe – für den größten Teil der Dokumente genügt ein Archivbereich, der nach Jahren geordnet ist. Also jeweils Ordner für das Jahr „2022“, „2023“, „2024“ usw. Falls z. B. im Jahr 2024 eine Solaranlage installiert wird, so kann dieses Jahr einen Unterordner „2024/Solaranlage“ erhalten. Aber in allen Fällen sollte sich die Anzahl solcher Unterordner in Grenzen halten, da die Suchfunktion von Paperless-ngx super-schnell fast jedes Dokument einblendet, von dem man ein Stichwort in Erinnerung hat. Alternativ kann es auch sein, dass man Ordner für Korrespondenten – Arbeitgeber, Kunden – in einen Jahresordner aufnehmen möchte.

Die fertige Struktur könnte dann beispielsweise so aussehen:

Automatisierung für Archivordner

Kümmern wir uns zunächst um die Archivordner, da hier die Automatisierung besonders unkompliziert ist. Durch einen einfachen Kniff kann man Paperless-ngx veranlassen, jedes neue Dokument sofort im korrekten Jahresordner einzuordnen. Dafür genügen zwei Zeilen in der Konfigurationsdatei. Dazu wird im Filemanager auf dem Pfad „paperless-ngx“ die Datei „docker-compose.env“ aufgerufen. Diese enthält nur vier Zeilen. Für die erste der beiden Zeilen gibt es nun folgende Möglichkeiten:

puristische Anweisung

PAPERLESS_FILENAME_FORMAT={created_year}/{title}

Speichert man eine Datei mit dem Namen „kobold.pdf“, die als Datum „15.03.2024“ enthält in Paperless-ngx, so erhält findet man unter

paperless-ngx/documents/archive/2024/kobold.pdf

Wäre in der Datei ein Datum aus 2019 enthalten, so würde sie automatisch in dem Pfad „../2019“ gespeichert. Enthält ein Dokument kein Datum oder möchte man ein erkanntes Datum anpassen, so nimmt man den üblichen Eintrag im Feld „Ausgestellt am“ vor – sofort wandert das Dokument in den entsprechenden Ordner.

Auf diese Weise erhält man eine sehr flache Hierarchie – die Dokumente wandern einfach in den jeweiligen Jahresordner. In vielen Fällen genügt das auch. Aber man kann die Anweisung erweitern.

erweiterte Anweisungen

Dokumententyp/Korrespondent

Nehmen wir an, man möchte für den Bereich „Energie“ gerne einen Unterordner im betreffenden Jahr haben. Dort können Stromrechnungen, Tarifänderungen, Heizungsangelegenheiten usw. aufgenommen werden. Dafür kann man wahlweise einen Korrespondenten oder einen Dokumenttyp anlegen. Die Zeile wird in diesem Fall um einen Platzhalter erweitert:

PAPERLESS_FILENAME_FORMAT={created_year}/{document_type}/{title} oder
PAPERLESS_FILENAME_FORMAT={created_year}/{correspondent}/{title}

Zunächst wird die Datei wie gewohnt in Paperless-ngx aufgenommen. Anschließend – oder zu einem späteren Zeitpunkt – weist man etwa den Korrespondent „Energie“ zu. In der gleichen Sekunde wandert die Datei in den Pfad „../2024/Energie“. (Das könnte man zwar auch über die Definition eines gesonderten Speicherpfads innerhalb der Web-Oberfläche erreichen, aber das beschriebene Vorgehen hat bei großen Datenmengen Vorteile.)

Wichtig ist: Für die meisten Dateien ist die Zuweisung eines Korrespondenten oder Dokumententyps unwichtig – diese sollen ja gerade in dem eigentlichen Jahres-Ordner gespeichert werden. Für all diese Dateien gilt, dass man keine zusätzlichen Einstellungen vornehmen muss – die Anweisung in der Konfigurationsdatei genügt bereits.

Platzhalter für Titel

Noch eine zweite Erweiterung der Konfigurationszeile kann sinnvoll sein. Ich persönlich ordne meine Archivdokumente seit Jahren mit Dateinamen nach dem Muster „Jahr-Monat-Tag_Titel“. Dieses Muster kann man beibehalten durch folgende Platzhalter:

{created_year}-{created_month}-{created_day}_{title}

Die ganze Zeile lautet dann:

PAPERLESS_FILENAME_FORMAT={created_year}/{document_type}/{created_year}-{created_month}-{created_day}_{title}

Das Ergebnis sieht dann so aus:

Klar, das ist eine gewisse Doppelung. Das Jahr ist ja bereits im Ordnernamen enthalten. Muss man auch nicht machen – aber auf diese Weise habe ich die gewohnten Dateinamen, wenn ich z. B. mal Dokumente aus Paperless-ngx exportiere und in einen Projektordner auf einem anderen Speichermedium schiebe.

Alle Platzhalter sind auf dieser Seite zu finden.

Die zweite Zeile

Bei diesem System ist noch eine zweite Anweisung wichtig, die ebenfalls in „docker-compose.env“ aufgenommen werden muss. Ohne diese Anweisung würden, bei Nicht-Zuweisung eine Korrespondenten, unsere Pfade ein „none“ erhalten. Das wird vermieden durch die Zeile

PAPERLESS_FILENAME_FORMAT_REMOVE_NONE=true

Basisordner zuweisen

Im einfachsten Fall werden für die Basisordner Speicherpfade mit Platzhaltern ohne Jahreszahl definiert:

Bei der Aufnahme eine Versicherungsdokuments landet die Datei zwar zunächst auf „../2024/Versicherung/xyz.pdf“. Dies wird aber durch die Zuweisung des Speicherpfads überschrieben, so dass sich Unterlagen danach in „../Versicherung/xyz.pdf“ befindet. Möchte man sich die Zuweisung des Dokumenttyps ersparen, so ersetzt man in der Pfadanweisung die Zeile mit „Versicherung/{title}“.

Eleganter ist es, wenn man sich erst gar keine Gedanken darüber machen muss, auf welchem Ordnerpfad ein Dokument landen soll. Dies kann man über einen Arbeitsablauf bewerkstelligen.

Wenn-dann-Anweisungen

Bei diesem Vorgehen hat man es im Feld „Dokumenttyp“ (oder „Korrespondent“) mit einer einheitlichen Liste zu tun. Der Auswahlliste sieht man die Unterscheidung in diesem Fall nicht an:

Für die wenigen Basisordner legen wir einfach „Arbeitsabläufe“ an. Das ist in einer Minute geschehen und zahlt sich später aus.

Der Menüpunkt „Arbeitsabläufe“ ist in der linken Sidebar zu finden. Als „Auslöser“ wird in diesem Beispiel die Zuweisung des Dokumenttyps „Versicherung“ gewählt:

Auslöser für den Ablauf ist die Zuweisung des Dokumenttyps „Versicherung“. Das muss nicht gleich bei der ersten Aufnahme passieren. Entscheidet man sich zu einem späteren Zeitpunkt, dass die Unterlage in diesen Basisordner soll, so weist man erst dann den Dokumenttyp zu.

Bei „Aktionen“ wählt man unter „Speicherpfad zuweisen“ den dazugehörigen Speicherpfad aus. Fertig. Das wiederholt man dann noch für den Basisordner „Vertrag“ oder „Zeugnisse“ – nach ein paar Minuten ist alles erledigt.

Vorhandene Dokumente einsortieren lassen

Sofern schon eine Reihe von Dokumenten aufgenommen wurden, so kann man mit einem einfachen Befehl den vorhandenen Bestand von Paperless-ngx neu arrangieren lassen.

Also, auf dem Paperless-ngx-Pfad einfach folgende Zeile eingeben:

sudo docker-compose exec webserver document_renamer

Je nach Anzahl der Dokumente kann das etwas dauern, es müssen ja auch die Datenbankeinträge neu vorgenommen werden. Aber anschließend finden sich die Dateien in der neuen Ordnerstruktur.

Das gesamte System sieht also so aus:

Wie immer gilt: zuvor den Export-Befehl durchführen bzw. ein Backup. Es kann ja sein, dass man eine sehr komplexe Struktur ursprünglich eingeführt hatte – dann sollte man zunächst testen, ob man mit dem Ergebnis zufrieden ist. Falls nicht: Wie bereits beschrieben ein Restore durchführen – und alles ist wie gehabt. Allgemein ist zu empfehlen, ein zweites Paperless-ngx (mit einem anderen Port) aufzusetzen und mit einer geringen Anzahl zu testen. (Bei mir liegt mein Hauptsystem auf einem Raspberry Pi 5, für die Tests mit Paperless-ngx nehme ich meinen 4-er.)

Bisherige Teile der Paperless-ngx-Serie:
Teil 1: Ausführlicher Überblick
Teil 2: Suche & Tags
Teil 3: consume-Ordner – Einsatz von Scannern
Teil 4: Speicherpfade konfigurieren
Teil 5: Installation auf dem Raspberry Pi
Teil 6: Neue Funktionen in Version 2
Teil 7: Dokumente unterwegs über das eigene Modem abrufen
Teil 8: Exportfunktion nutzen
Teil 9: Update durchführen
Teil 10: Das Rundum-sorglos-Backup
Teil 11: Mail-Abruf mit vielen Extras
Teil 12: Mein Alltag mit Paperless-ngx
Teil 13: Ein Quanten-Code für das Papier-Archiv
FORUM für Fragen eröffnet
Teil 14: Automatisierte Ablage auf Speicherpfaden
Teil 15: Neue Funktion für das Verbinden und Trennen von Dokumenten

10 Kommentare

  • vs

    Hallo und danke schon mal für diese interessante Reihe, die ich mal angefangen habe umzusetzen.
    Ich habe derzeit pareless-ngx 2.6.3 in einer lxc im proxmox am laufen. Kann es sein, dass die obigen Anweisungen für di docker-compose.env nicht stimmen? Das „=“ Zeichen scheint nicht richtig zu sein….
    VG vs

    • Herbert

      Danke für die Rückmeldung und den Hinweis! Habe gleich mal nachgeschaut – bei mir funktioniert es mit dem „=“-Zeichen (env-Datei). So wird es auch in der Dokumentation angegeben: https://docs.paperless-ngx.com/configuration/ – Evtl. ist es bei Deiner Installation anders – ich teste hier ja nur die docker-compose-Variante auf dem Raspberry Pi.

  • Tom

    Man kann die Variable auch direkt in der docker-compose.yaml Datei setzen.
    Die .env Datei muss man nicht nutzen.

    Anstelle des = kann man auch den : benutzen

    environment:
    USERMAP_UID: 1000
    USERMAP_GID: 1000
    PAPERLESS_FILENAME_FORMAT: „{created_year}/{document_type}/{created_year}-{created_month}-{created_day}_{title}“

    Dann muss aber der Sring von PAPERLESS_FILENAME_FORMAT in “ “ gesetzt werden.
    (Ohne “ “ -> yaml: line xx: did not find expected key)

    Diese Variante ist ebenfalls möglich.

    environment:
    – PUID=1000
    – PGID=1000
    – TZ=Europe/Berlin

  • Tom

    Kein Problem. 🙂 Wenn möglich helfe ich doch gerne.

    Leider lässt sich hier in den Kommentaren nicht yaml-konform (richtige Formatierung/
    Leerzeichen) posten.

    Somit tauchen vermutlich beim Testen Fehler auf, weil die yaml-Formatierung nicht stimmt.

  • Heinz

    Hallo zusammen,
    wollte das mit dem Basisordner und Archiv einrichten, aber leider werden meine Dokumente immer nur in den Hauptpfad Archiv gelegt und auch der Basisunterordner wird unter Archiv mit den dazugehörigen Unterordnern angelegt. Egal wie ich die Speicherpade benennne z.B. (..Basisordner/Versicherung/xyz.pdf oder Basisordner/Versicherung/xyz.pdf) muß ich in der docker-compose.env noch andere Einstellungen konfigurieren?

    • Herbert

      Hast Du Paperless-ngx so installiert, wie es in Teil 5 beschrieben wurde? Also via docker-compose und in der yaml-Datei den Mediapfad gesetzt? Dann musst Du nichts anderes eintragen, als bereits im Artikel erwähnt wurde. Der Aufbau ist dann so, dass von „/home/paperless-ngx/documents“ die beiden Unterordner „archive“ und „originale“ abgehen. Und alle Speicherpfade werden innerhalb dieser beiden Ordner angelegt. Es klappt dann also nicht, z. B. „/home/unterlagen/versicherung“ oder so zu bestimmen.

      • Heinz

        Hallo Herbert danke für die schnelle Antwort, zur Erklärung ich habe es auf einer Nas laufen aber da sind die Speicherpfade ja identisch also unter Media/Dokumente/Archiv und Originale aber auf dieser Seite wird ja der Basisordner neben dem Archivordner aufgeführt und hier habe ich das Problem oder verstehe ich die Speicherpfade falsch und beide angesprochenen Ordner liegen unter dem Standard angelegten Archiv.

        • Herbert

          Ach so – jetzt verstehe ich. Der Begriff „Archiv“ führt wohl zu der Verwirrung 🙂 Also: „archive“ nennt sich einfach der Standardordner von Paperless-ngx, der alles einschließlich Unterordnern aufnimmt. In meinem Blog-Artikel habe ich dann von „Archiv-Ordnern“ gesprochen aber mit einer anderen Bedeutung. In meinem Artikel waren damit „persönliche Zeit-Archiv-Ordner“ gemeint, die – ebenso wie die Basisordner – im Hauptordner „archive“ untergebracht sind.
          Also:
          archive
          – Versicherungen
          – Verträge
          — mein_archiv
          — mein_archiv\2023
          — mein_archiv\2024

          • Heinz

            Ah, jetzt verstehe ich meinen Fehler, danke nochmal für die ausführliche Aufzählung der Ordner, das hat jetzt Licht ins Dunkel gebracht 😉

Eine Antwort schreiben

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert