Zum Inhalt springen

Änderungen von Dokument Paperless NGX

Zuletzt geändert von Daniel Herrmann am 2026/02/22 11:41
Von Version Icon 2.1 Icon
bearbeitet von Daniel Herrmann
am 2025/10/24 19:57
Änderungskommentar: Es gibt keinen Kommentar für diese Version
Auf Version Icon 11.1 Icon
bearbeitet von Daniel Herrmann
am 2025/10/24 20:20
Änderungskommentar: Neuen Anhang pencil.png hochladen

Zusammenfassung

Details

Icon Seiteneigenschaften
Inhalt
... ... @@ -1,6 +1,6 @@
1 1  Das Herzstück der digitalen Mitgliederakte bildet Paperless NGX. Es wird im Makerspace lokal betrieben und ist daher nur aus dem Netzwerk des Makerspaces oder [[per VPN>>path:/bin/view/IN/IT%20Infrastruktur/IT%20im%20Makerspace/%5BHOWTO%5D%20Makerspace%20VPN/]] erreichbar. Der Zugang zu Paperless ist über OpenID Connect an [[Keycloak>>path:/bin/view/IN/IT%20Infrastruktur/Services/Keycloak/]] gekoppelt, Zugang besteht nur für Mitglieder der Gruppen **Vorstand** und **Mitgliederverwaltung**.
2 2  
3 -== Paperless Übersicht ==
3 += Paperless Übersicht =
4 4  
5 5  **Dokumente** sind die primären Ressourcen in Paperless. Ein Dokument kann über mehrere Wege in Paperless aufgenommen werden (der Prozess wird **Ingestion** genannt):
6 6  
... ... @@ -12,6 +12,280 @@
12 12  
13 13  Die folgenden Grafik gibt eine Übersicht:
14 14  
15 -{{diagram/}}
15 +{{diagram reference="PROJ.Digitale Mitgliederverwaltung.Paperless NGX.Diagram" cached="false"/}}
16 16  
17 -
17 +Der Scanner ist so eingerichtet, dass nur zwei Buttons auf dem Display sichtbar sind:
18 +
19 +* **SCAN Vorstand** - Platziert das Dokument in dem Consumption Ordner für den Vorstand, Rechte und Tags werden dann automatisch gesetzt
20 +* **SCAN MV** - Platziert das Dokument in dem Consumption Ordner für die Mitgliederverwaltung, Rechte und Tags werden dann automatisch gesetzt
21 +
22 += Metadaten =
23 +
24 +Jedem Dokument werden dann Meta-Daten zugeordnet, die eine spätere Suche und Zuordnung erleichtern. Diese Meta-Daten sind:
25 +
26 +* **Korrespondent**: Im Prinzip der "Gesprächspartner", beispielsweise der Absender eines Briefs. Im Falle der Mitgliederverwaltung wird für jedes Mitglied und jeden registrierten Gast automatisch im Hintergrund ein Korrespondent angelegt. Die Korrespondenten heißen:
27 +** Für **Mitglieder**: //Vorname Nachname (#Mitgliedsnummer)//, also beispielsweise "//Daniel Herrmann (#250)//"
28 +** Für **Gäste**: //Vorname Nachname (GEindeutigeNummer)//, also beispielsweise "//Max Mustermann (G1244)//"
29 +** Bei **Vereinseintritt** und **Vereinsaustritt** werden die Korrespondenten automatisch umbenannt, auch Namensänderungen werden automatisch verarbeitet.
30 +* **Tags**: Einem Dokument können beliebig viele Tags zugewiesen werden. **Tags** dienen der einfacheren **Zuordnung** und dem **Wiederfinden** von Dokumenten. Es gibt allerdings auch spezielle Tags für Dokumente die eingelesen aber noch nicht bearbeitet wurden, so genannte "Inbox Tags":
31 +** **Inbox Mitgliederverwaltung** - Alle **Dokumente** die **per Mail oder per Ordner** für die **Gruppe Mitgliederverwaltung** aufgenommen wurden und **nicht automatisch zugeordnet** werden konnten.
32 +** **Inbox Vorstand** - Alle **Dokumente** die **per Mail oder per Ordner** für die **Gruppe Vorstand** aufgenommen wurden und **nicht automatisch zugeordnet** werden konnten.
33 +* **Dokumenten-Typen**: Einem Dokument wird exakt ein Typ zugewiesen. Dokumenten Typen sind im Prinzip einfache Gruppen. Für die Mitgliederverwaltung sind die Gruppen gemäß der folgenden Liste festgelegt, können aber natürlich bei Bedarf erweitert werden.
34 +** Mitgliedsantrag
35 +** SEPA Lastschriftmandat
36 +** Studienbescheinigung
37 +** Bestätigung Schlüsselausgabe
38 +** Verpflichtungserklärung Datenschutz
39 +** Übungsleitervertrag
40 +** Nutzungsvereinbarung Schulungsinhalte
41 +** Bestellung als Einweiser:in
42 +** Haftungsausschluss
43 +** Einweisungszettel
44 +** Lagervertrag Kistenlager
45 +** Lagervertrag Projektlager
46 +* (((
47 +**Storage Path**: Speicherpfade sind ein fortgeschrittenes Feature, welches kontrolliert, wie die Dateien im unterliegenden Dateisystem gespeichert werden. In der Regel arbeitet man nicht direkt mit den Dateien, aber wenn man aus lange Sicht mal aus Paperless NGX weg ziehen möchte kann es sinnvoll sein, die Dokumente in einer Struktur zu speichern, die man theoretisch auch manuell durchsuchen könnte. Details finden sich in der [[Dokumentation von Paperless zu File Name Handling>>url:https://docs.paperless-ngx.com/advanced_usage/#file-name-handling]].
48 +)))
49 +
50 +>Paperless checks the filename of a document whenever it is saved. Changing (or deleting) a [[storage path>>url:https://docs.paperless-ngx.com/advanced_usage/#storage-paths]] will automatically be reflected in the file system. However, when changing PAPERLESS_FILENAME_FORMAT you will need to manually run the [[document renamer>>url:https://docs.paperless-ngx.com/administration/#renamer]] to move any existing documents.
51 +
52 +In unserem Fall kommen die folgenden Speicherpfade zum Einsatz:
53 +
54 +|=Name|=Definition|=Sichtbar für|=Anwendung
55 +|Mitglieder Einweisungszettel|~{~{ correspondent }}/Einweisungen/~{~{ document_type }}-~{~{ tag_list }}-~{~{ created }}-~{~{ doc_pk }}|Mitgliederverwaltung|Einweisungszettel
56 +|Mitglieder Unterlagen|~{~{ correspondent }}/~{~{ document_type }}-~{~{ created }}-~{~{ doc_pk }}|Mitgliederverwaltung|Alle anderen Mitgliederdokumente
57 +|Vorstand Dokumente|~{~{ created_year }}/~{~{ correspondent }}/~{~{ title }}|Vorstand|Alle Vorstandsdokumente
58 +
59 +== Automatische Zuordnung von Metadaten ==
60 +
61 +Paperless unterstützt die automatische Zuordnung von Metadaten basierend auf festen Strings. So kann man beispielsweise angeben, dass ein Dokumententyp "Haftungsausschluss" zugewiesen werden soll, wenn der String "Haftungsausschluss" irgendwo im Dokument vorkommt. Dies ist allerdings auf eine korrekte Funktion der Texterkennung angewiesen und funktioniert erfahrungsgemäß nur in manchen Fällen, sodass mindestens eine manuelle Überprüfung trotzdem notwendig kommt. Wenn beispielsweise ein Brief mit dem Satz "ich dachte, ich hätte den Haftungsausschluss bereits abgegeben, könntet ihr dies bitte prüfen" erfasst wird, würde der basierend auf der Regel ebenfalls kategorisiert werden.
62 +
63 +**Aus diesem Grund wird auf jedes Dokument einen spezieller QR Code aufgedruckt**. Der QR code wird vom Post-Consume Script verwendet um die Metadaten in Paperless zuzuordnen. Weiterhin können Daten übermittelt werden, die dann mittels Webhook an N8n übermittelt werden und dort im Workflow verwendet werden können. Der Aufbau orientiert sich an dem Aufbau eines **JSON Web Tokens (JWT).**
64 +
65 +
66 +=== Barcode erzeugen ===
67 +
68 +Der Prozess zur Erzeugung eines QR Codes ist wie folgt:
69 +
70 +* **Payload (Daten) festlegen**. Einige Werte sind verpflichtend, andere können nach Bedarf optional hinzugefügt werden.
71 +* JWT erzeugen und signieren. der JWT besteht aus drei Teilen:
72 +** **Header**: **alg** (Algorithmus) und **typ** (JWT) sind verpflichtend. Zusätzlich fügen wir einen Timestamp, eine eindeutige ID und eine Gültigkeitsdauer hinzu.
73 +** **Body**: beinhaltet die eigentlichen Daten.
74 +** **Signature**: Mit Hilfe eines Secrets und wird die Signatur erzeugt und automatisch angehängt.
75 +* PDF417 code erzeugen: ein JWT ist per Definition URL safe und kann daher einfach in ein QR code umgewandelt werden.
76 +
77 +=== Header ===
78 +
79 +Der Header enthält wichtige Meta-Daten, diese werden von der JWT Library automatisch erzeugt und beschreiben in der Regel den verwendeten Key-Typ.
80 +
81 +=== Body ===
82 +
83 +Die folgenden Claims sind im Body verfügbar.
84 +
85 +|=(((
86 +Claim
87 +)))|=(((
88 +Type
89 +)))|=(((
90 +Pflicht
91 +)))|=(((
92 +Beschreibung
93 +)))
94 +|(((
95 +id
96 +)))|(((
97 +UUID4
98 +)))|(((
99 +✅️
100 +)))|(((
101 +Eindeutige ID dieses Dokuments
102 +)))
103 +|(((
104 +time
105 +)))|(((
106 +Zahl
107 +)))|(((
108 +✅️
109 +)))|(((
110 +UTC Linux-Timestamp an dem das Dokument und der QR Code erzeugt wurden
111 +)))
112 +|(((
113 +exp
114 +)))|(((
115 +Zahl
116 +)))|(((
117 +✅️
118 +)))|(((
119 +UTC Linux-Timestamp der angibt, bis wann das Dokument gültig ist.
120 +)))
121 +|(((
122 +typ
123 +)))|(((
124 +String
125 +)))|(((
126 +✅️
127 +)))|(((
128 +Typ des Dokuments basierend auf der unten definierten Liste.
129 +)))
130 +|mode|String|✅️ |Kann entweder "digital" oder "manual" sein und bestimmt, ob N8n den unterschriebenen Vertrag ans Backend meldet.
131 +|(((
132 +cor
133 +)))|(((
134 +String
135 +)))|(((
136 +❌️
137 +)))|(((
138 +Optional: Name des Korrespondenten, dem das Dokument zugeordnet werden soll
139 +)))
140 +|(((
141 +tags
142 +)))|(((
143 +List[String]
144 +)))|(((
145 +❌️
146 +)))|(((
147 +Liste an Tags, die dem Dokument zugeordnet werden soll
148 +)))
149 +|(((
150 +spth
151 +)))|(((
152 +String
153 +)))|(((
154 +❌️
155 +)))|(((
156 +Storage Path, das dem Dokument zugeordnet werden soll
157 +)))
158 +|(((
159 +opt
160 +)))|(((
161 +dict
162 +)))|(((
163 +❌️
164 +)))|(((
165 +Optionale Attribute, die mit eincodiert werden und dem N8n Workflow übergeben werden.
166 +)))
167 +
168 +=== Footer ===
169 +
170 +Der Footer wird automatisch erzeugt und erhält eine Signatur über den Header und den Body, basierend auf einem Algorithmus und einer Signatur.
171 +
172 +{{success}}
173 +**Algorithmus**
174 +
175 +
176 +Von den meisten Libraries werden symmetrische und asymmetrische Signaturen unterstützt. Die Verwendung eines symmetrischen Algorithmus ist für uns einfacher.
177 +
178 +Für diesen Anwendungsfall nutzen wir **HS256** (HMAC mit SHA-256 Algorithmus).
179 +{{/success}}
180 +
181 +=== Auswahl der Library ===
182 +
183 +Die Implementierung für die Erzeugung und das Validieren erfolgt in Python. Dies hat den Hintergrund, dass sowohl unser Backend als auch Paperless NGX (und damit das Post-Consumption Script) in Python implementiert ist. Es gibt verschiedene Libraries, die betrachtet wurden:
184 +
185 +|=(((
186 +Name
187 +)))|=(((
188 +CVE
189 +)))|=(((
190 +Github
191 +)))|=(((
192 +GH⭐
193 +)))|=(((
194 +Letztes Release
195 +)))|=(((
196 +Offene Issues
197 +)))|=(((
198 +Dokumentation
199 +)))|=(((
200 +Qualität Dokumentation
201 +)))|=(((
202 +In Backend vorhanden?
203 +)))|=(((
204 +In Paperless vorhanden?
205 +)))
206 +|(((
207 +python-jose
208 +)))|(((
209 +3/0
210 +)))|(((
211 +[[https:~~/~~/github.com/mpdavis/python-jose>>url:https://github.com/mpdavis/python-jose]]
212 +)))|(((
213 +1.7k
214 +)))|(((
215 +28.05.2025
216 +)))|(((
217 +83
218 +)))|(((
219 +[[https:~~/~~/python-jose.readthedocs.io/en/latest/>>url:https://python-jose.readthedocs.io/en/latest/]]
220 +)))|(((
221 +⛔ Wenige Bespiele, API Dokumentation fehlt komplett
222 +)))|(((
223 +❌️
224 +)))|(((
225 +❌️
226 +)))
227 +|(((
228 +pyJWT
229 +)))|(((
230 +4/0
231 +)))|(((
232 +[[https:~~/~~/github.com/jpadilla/pyjwt>>url:https://github.com/jpadilla/pyjwt]]
233 +)))|(((
234 +5.4k
235 +)))|(((
236 +28.11.2024
237 +)))|(((
238 +30
239 +)))|(((
240 +[[https:~~/~~/pyjwt.readthedocs.io>>url:https://pyjwt.readthedocs.io]]
241 +)))|(((
242 +➕️ Gute Dokumentation, API, Beispiele, Changelog
243 +)))|(((
244 +✅️ 2.10.1
245 +Dep von firebase
246 +)))|(((
247 +✅️ 2.10.1
248 +)))
249 +|(((
250 +JWCrypto
251 +)))|(((
252 +5/0
253 +)))|(((
254 +[[https:~~/~~/github.com/latchset/jwcrypto>>url:https://github.com/latchset/jwcrypto]]
255 +)))|(((
256 +465
257 +)))|(((
258 +06.03.2024
259 +)))|(((
260 +8
261 +)))|(((
262 +[[https:~~/~~/jwcrypto.readthedocs.io>>url:https://jwcrypto.readthedocs.io]]
263 +)))|(((
264 +➕️ API Doc, einige Beispiele
265 +)))|(((
266 +✅️ 1.5.6
267 +Dep von python-keycloak
268 +)))|(((
269 +❌️
270 +)))
271 +
272 +Unsere bevorzugte Library ist **pyjwt**. Diese ist auch in **paperless nativ vorhanden**, sodass wir uns für die Implementierung mittels **pyjwt** entschieden haben.
273 +
274 +=== PDF417 Code ===
275 +
276 +Als Format für den Code wurde PDF417 ausgewählt, da dieser mehr Platz und Fehlerkorrektur bietet. Weiterhin gibt es eine einfach zu nutzende Library für Python (Erzeugung) und PDF417 wird von ZXING unterstützt, welches in Paperless eingebettet ist. Ein solcher Barcode sieht beispielsweise so aus:
277 +
278 +
279 +[[image:/bin/download/PROJ/Digitale%20Mitgliederverwaltung/WebHome/barcode.jpg?height=250&rev=1.1||alt="barcode.jpg" height="250"]]
280 +
281 +Daraus kann dann eine Base64 basierte Repräsentation berechnet werden, die einfach in Docuseal hochgeladen werden kann.
282 +
283 +=== Referenz-Implementierung ===
284 +
285 +Eine Referenz-Implementierung befindet sich im Makerspace Gitlab: [[https:~~/~~/git.makerspace-darmstadt.de/makerspace-it-infrastructure/mitgliederverwaltung/paperless-pdf417-reference>>url:https://git.makerspace-darmstadt.de/makerspace-it-infrastructure/mitgliederverwaltung/paperless-pdf417-reference]]
286 +
287 +=== Post Consumption Script ===
288 +
289 +Die eigentliche Zuordnung der Meta-Daten erfolgt über ein so genanntes Post Consumption Script. Dieses befindet sich ebenfalls im Makerspace Gitlab: [[https:~~/~~/git.makerspace-darmstadt.de/makerspace-it-infrastructure/mitgliederverwaltung/paperless-post-consumption-script#>>url:https://git.makerspace-darmstadt.de/makerspace-it-infrastructure/mitgliederverwaltung/paperless-post-consumption-script]]
290 +
291 +
Icon accept.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.dherrman
Größe
... ... @@ -1,0 +1,1 @@
1 +724 bytes
Inhalt Icon
Icon barcode.jpg
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.dherrman
Größe
... ... @@ -1,0 +1,1 @@
1 +46.6 KB
Inhalt Icon
Icon pencil.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.dherrman
Größe
... ... @@ -1,0 +1,1 @@
1 +388 bytes
Inhalt Icon