Zum Inhalt springen

Änderungen von Dokument N8n Workflow Engine

Zuletzt geändert von Daniel Herrmann am 2026/02/22 21:17
Von Version Icon 2.1 Icon
bearbeitet von Daniel Herrmann
am 2025/08/31 19:24
Änderungskommentar: Es gibt keinen Kommentar für diese Version
Auf Version Icon 19.1
bearbeitet von Daniel Herrmann
am 2026/02/22 21:17
Änderungskommentar: Es gibt keinen Kommentar für diese Version

Zusammenfassung

Details

Icon Seiteneigenschaften
Inhalt
... ... @@ -1,108 +1,165 @@
1 1  n8n ist ein **Open-Source-Tool zur Workflow-Automatisierung**, das man selbst hosten kann. Über eine **visuelle Oberfläche** baut man Workflows per Drag-and-drop aus sogenannten „Nodes“, die verschiedene Dienste und Aktionen miteinander verbinden. Es gibt Hunderte vorgefertigte Integrationen, z. B. für Slack, Mail oder MQTT. Ebenfalls gibt es eine große Auswahl an für uns relevante Community Nodes (Vikunja, Listmonk, und so weiter) sowie die Möglichkeit, eigene Nodes zu schreiben (beispielsweise Paperless oder NATS).
2 2  
3 -= {{id name="N8nWorkflowEngine-WorkflowÜbersicht"/}}Workflow Übersicht =
3 += Inhaltsverzeichnis =
4 4  
5 -asd
5 +{{toc/}}
6 6  
7 -= {{id name="N8nWorkflowEngine-CommunityNodes"/}}Community Nodes =
7 += Workflow Übersicht =
8 8  
9 -asd
9 +Workflows bestehen grundsätzlich aus einem oder mehreren **Triggern** und einer oder mehreren **Aktionen**. Im Folgenden werden nur die für die Mitgliederverwaltung relevanten Workflows beschrieben, N8n kann aber natürlich auch für andere Automatisierung verwendet werden.
10 10  
11 -= {{id name="N8nWorkflowEngine-TechnischesSetup"/}}Technisches Setup =
11 +== Workflows für Dokumente ==
12 12  
13 -== {{id name="N8nWorkflowEngine-Lizenz"/}}Lizenz ==
13 +=== Document Consumed Workflow ===
14 14  
15 -N8n hat eine so genannte "Sustainable Use License". Für den internen Gerbauch frei verwendbar, solange man keine Produkte damit verkauft. Auszug aus der FAQ:
15 +Dieser Workflow wird durch das [[Paperless Post-Consume Script>>doc:PROJ.Digitale Mitgliederverwaltung.Paperless NGX.WebHome]] ausgelöst, immer dann, wenn ein **QR Code mit dem korrekten Inhalt **erkannt wird. Die Idee hier ist, dass **ausgedruckte und handschriftliche Dokumente **automatisch verarbeitet werden können.
16 16  
17 ->Our license restricts use to "internal business purposes". In practice this means all use is allowed unless you are selling a product, service, or module in which the value derives entirely or substantially from n8n functionality.
17 +Im Prinzip ersetzt dieser Workflow den Docuseal Webhook, der automatisch dem Backend bescheid gibt, wenn alle Parteien unterschrieben haben. Bei ausgedruckten Dokumenten passiert dies stattdessen hierüber.
18 18  
19 -Wir verwenden im Makerspace die kostenlose [[Community License>>url:https://docs.n8n.io/hosting/community-edition-features/||shape="rect"]], den Lizenzkey erhält man online durch Ausfüllen eines Formulars.
19 +[[image:1771785973968-394.png||height="150"]]
20 20  
21 -== {{id name="N8nWorkflowEngine-HostingundKubernetes"/}}Hosting und Kubernetes ==
21 +Der Workflow:
22 22  
23 -N8n soll hauptsächlich mit unserer Paperless Instanz interagieren und läuft aus diesem Grund ebenfalls im Makerspace auf unserem Kubernetes Cluster. Für die Installation kommt das [[Helm Chart von 8gears>>url:https://artifacthub.io/packages/helm/open-8gears/n8n||shape="rect"]] zum Einsatz.
23 +* wird über ein Webhook vom Post Consume Script ausgelesen. Als Inhalt wird der Inhalt des dekodierten QR Codes übergeben
24 +* nur handschriftlich unterschriebene Dokumente werden verarbeitet
25 +* dem Backend wird signalisiert, dass das Dokument erfolgreich verarbeitet wurde
24 24  
25 -Der Code für die ArgoCD App ist in Gitlab gespeichert und wird automatisch über ArgoCD synchronisiert: [[https:~~/~~/git.makerspace-darmstadt.de/makerspace-it-infrastructure/gitops/main-apps/n8n/-/tree/main?ref_type=heads>>url:https://git.makerspace-darmstadt.de/makerspace-it-infrastructure/gitops/main-apps/n8n/-/tree/main?ref_type=heads||shape="rect"]]
27 +Als Konsequenz kann das Backend weitere automatische Aktionen ausführen, beispielsweise vorläufige oder dauerhafte Berechtigungen eintragen.
26 26  
27 -[[image:attach:image-2025-8-31_19-10-32.png||height="250"]]
29 +=== Paperless Papierkorb ===
28 28  
29 -Die Komponenten beschränken sich hierbei auf:
31 +**In Paperless kann nur der Owner Dokumente in den Papierkorb verschieben**. Dies lässt sich leider nicht anders konfigurieren, sodass wir uns hier mit einem Workaround behelfen: die Mitgliederverwaltung und/oder der Vorstand können dem Dokument **ein Tag zuweisen**. **Dieses Tag löst einen Workflow in Paperless aus:**
30 30  
31 -* Die N8n Applikation selbst, das sind die Ressourcen aus dem Helm Chart
32 -* Eine Datenbank-Instanz (PostgeSQL, auf dem zentralen DB Server)
33 -* Secrets, die aus Hashicorp Vault synchronisiert werden
33 +[[image:1771786279823-587.png||height="250"]]
34 34  
35 -== {{id name="N8nWorkflowEngine-HelmChartParameter"/}}Helm Chart Parameter ==
35 +Dieser Workflow löst zwei Dinge aus (leider ist Dokument löschen keine verfügbare Aktion):
36 36  
37 -Das Helm Chart akzepziert einige Parameter, mit denen das Deployment genauer konfiguriert werden kann. In unserem Fall kurz erklärt:
37 +* er entfernt das Tag wieder, um Rekursion zu vermeiden
38 +* und löst ein N8n Webhook aus
38 38  
39 -\\
40 +**Der N8n Workflow löscht dann das Dokument.**
40 40  
41 -{{code}}
42 -{
43 - values(ns, version, url, db_name, sc, size, db_hostname='pgsql-postgresql.mksp-services.svc.cluster.local')::
44 - {
45 - image: {
46 - tag: version,
47 - },
48 - main: {
49 - config: {
50 - db: {
51 - type: 'postgresdb',
52 - postgresdb: {
53 - database: ns + '-' + db_name,
54 - host: db_hostname,
55 - user: ns + '-' + db_name,
56 - },
57 - },
58 - },
59 - extraEnv: {
60 - DB_POSTGRESDB_PASSWORD: {
61 - valueFrom: {
62 - secretKeyRef: {
63 - name: 'db-' + db_name + '-creds',
64 - key: 'POSTGRES_PASSWORD',
65 - },
66 - },
67 - },
68 - },
69 - persistence:
70 - {
71 - enabled: true,
72 - type: 'dynamic',
73 - storageClass: sc,
74 - accessModes: ['ReadWriteOnce'],
75 - size: size,
76 - },
77 - },
78 - ingress:
79 - {
80 - enabled: true,
81 - annotations: {
82 - 'cert-manager.io/cluster-issuer': 'letsencrypt',
83 - },
84 - className: 'nginx',
85 - hosts: [
86 - {
87 - host: url,
88 - paths: ['/'],
89 - },
90 - ],
91 - tls: [
92 - { secretName: 'n8n-tls', hosts: [url] },
93 - ],
94 - },
95 - },
96 -}
42 +[[image:1771786234093-932.png||height="150"]]
97 97  
44 +== Cron Jobs - Sync von Daten ==
98 98  
46 +=== Sync Tags für Einweisungen ===
47 +
48 +In Paperless unterscheiden wir verschiedene Arten von Dokumente, diese sind [[hier im Wiki beschrieben>>doc:PROJ.Digitale Mitgliederverwaltung.WebHome]]. Es wäre aber nicht zweckmäßig, für jede Einweisung ebenfalls einen eigenen Typ zu erzeugen, daher verwenden wir Tags. **Dieser Workflow liest die verfügbaren Einweisungen vom Backend der Homepage aus und erzeugt die Tags.**
49 +
50 +[[image:1771790486089-157.png||height="150"]]
51 +
52 +Dieser Workflow **regelmäßig als Cronjob ausgeführt**.
53 +
54 +* liest verschiedene Informationen aus Paperless aus
55 +** Alle Gruppe, und findet die ID der Gruppen für Mitgliederverwaltung und IT-Admins
56 +** Alle User, und findet die ID des MV Owner Users
57 +** Alle bestehenden Tags
58 +* Dann werden die verfügbaren Einweisungen aus dem Backend ausgelesen
59 +* Im Merge Node werden Tags herausgefiltert, die noch nicht in Paperless existieren
60 +* Diese werden dann erzeugt.
61 +
62 +=== Sync Document Types ===
63 +
64 +Die verfügbaren Dokumenten-Typen werden [[in Directus verwaltet>>https://assets.makerspace-darmstadt.de/admin/content/paperless_document_types]], und können dort einfacher verändert werden. Dieser Workflow synchronisiert die Dokumenten-Typen ähnlich der Tags für Einweisungen.
65 +
66 +[[image:1771790995906-398.png||height="150"]]
67 +
68 +Dieser Workflow **regelmäßig als Cronjob ausgeführt**.
69 +
70 +* liest verschiedene Informationen aus Paperless aus
71 +** Alle Gruppe, und findet die ID der Gruppen für Mitgliederverwaltung und IT-Admins
72 +** Alle User, und findet die ID des MV Owner Users
73 +** Alle bestehenden Dokumenten-Typen
74 +* Dann werden die verfügbaren Typen aus Directus ausgelesen
75 +* Im Merge Node werden Typen herausgefiltert, die noch nicht in Paperless existieren
76 +* Diese werden dann erzeugt
77 +
78 +{{info}}
79 +Wir müssen überdenken, ob dies wirklich so sinnvoll ist. Die Dokumenten-Typen werden vom Backend in den QR Code rein kodiert und müssen übereinstimmen, damit das Dokument erfolgreich zugeordnet werden kann. Es macht eventuell mehr Sinn, dass IT-Admins diese direkt in Paperless verwalten. Dann würde die Directus Collection und dieser Workflow wegfallen.
80 +{{/info}}
81 +
82 +== Backend Event Workflows ==
83 +
84 +Bestimmte Events aus dem Backend werden über NATS als Event gepublished. Details dazu sind auf der [[Seite zu NATS>>doc:PROJ.Digitale Mitgliederverwaltung.Technische Dokumentation.NATS Setup.WebHome]] beschrieben. Hier werden die Events beschrieben, die Paperless betreffen:
85 +
86 +=== mksp.docuseal.signature.completed ===
87 +
88 +Dieses Event wird ausgelöst, wenn im Backend ein Signatur-Prozess abgeschlossen ist (d.h. alle Parteien haben unterschrieben und die Unterschrift wurde im Backend erfasst). Dies kann auf zwei Arten passieren:
89 +
90 +* Bei **rein digitalen Signaturen** durch einen über **Docuseal ausgelösten Webhook**
91 +* Bei **handschriftlich** unterschrieben Zetteln durch **Einscannen** und den oben beschrieben **"Document Consumed" N8n Workflow**
92 +
93 +[[image:1771785764191-239.png||height="150"]]
94 +
95 +**Der Workflow löst nur bei digitalen Dokumenten eine Aktion aus**. Bei handschriftlich unterschriebenen Dokumenten ist das Dokument bereits eingescannt. Für digital unterschriebene Signaturen:
96 +
97 +* wird der Status der Submission aus Docuseal ausgelesen
98 +* wird das PDF mit den Unterschriften aller Parteien runtergeladen...
99 +* und anschließend in Docuseal hochgeladen und dort verarbeitet.
100 +
101 +=== mksp.backend.user.created ===
102 +
103 +Dieser Workflow wird immer dann getriggert, wenn im Backend ein **neuer User** angelegt wird. Die Informationen aus der NATS Nachricht werden dann verwendet, um den **Korrespondenten in Paperless anzulegen**.
104 +
105 +[[image:1771784637258-114.png||height="200"]]
106 +
107 +Die folgenden Aktionen werden ausgeführt:
108 +
109 +1. Parallel werden **alle Gruppen und Benutzer **aus Paperless ausgelesen
110 +1. Es wird auf die relevanten Gruppen und Benutzer gefiltert. Ziel ist es, **die ID der entsprechenden Gruppen und Benutzer auszulesen**. Wir sind **interessiert an den Gruppen für die Mitgliederverwaltung und die IT Admins** sowie dem statischen **MV Owner**.
111 +1. Zuletzt wird der Subflow "Create Paperless Correspondent" angelegt. Dieser bekommt als Info:
112 +11. **firstname** - aus NATS Trigger
113 +11. **lastname** - aus NATS Trigger
114 +11. **isGuest** - true wenn membership_number in NATS Trigger = null, false otherwise
115 +11. **membership_number** - aus NATS Trigger
116 +11. **user_id** - aus NATS Trigger
117 +11. **owner_id** - ID des MV Data Owner Benutzers
118 +11. **permissions** - siehe unten
119 +11. **backend_url** - URL des Makerspace Backends
120 +
121 +Der Subflow erzeugt dann den Display-Namen des Korrespondenten und **speichert die Paperless-ID über die Backend-API zurück ins Backend.** Der **Display-Name **setzt sich wie folgt zusammen:
122 +
123 +|=Nutzer-Typ|=Format|=Beispiel
124 +|Mitglied|Vorname Nachname (#Mitgliedsnummer)|Daniel Herrmann (#250)
125 +|Gast|Vorname Nachname (Gast #Nutzer-ID)|Daniel Herrmann (Gast #1)
126 +
127 +Die **Berechtigungen** werden dabei wie folgt gesetzt:
128 +
129 +{{code language="none"}}
130 +{"view":{"users":[],"groups":[{{ $('Static Data').item.json.mv_group_id }}]},"change":{"users":[],"groups":[{{ $('Static Data').item.json.it_admin_group_id }}]}}
99 99  {{/code}}
100 100  
101 -Hervorzuheben sind hier insbesondere:
133 +D.h. Owner (und damit alle Rechte) hat der statische MV Owner Nutzer. Alle Mitglieder der Gruppe "Mitgliederverwaltung" können den Korrespondenten sehen (notwendig für Zuweisung und Filterung), IT-Admins können diese verändern.
102 102  
103 -* Das **Image **- Hier wird die Version von N8n konfiguriert. Eine Versions-Änderung des Helm Charts hat nicht zwangsweise auch eine Versions-Änderung der Applikation selbst (N8n) zur Folge, sodass dieses separat übergeben wird
104 -* **DB Config + Extra Env** - Hier werden die Zugangsdaten für die Datenbank übergeben. Host, Benutzername und Datenbankname werden an Hand des App-Namens erzeugt, das Passwort wird beim Anlegen der Datenbank dynamisch erzeugt und von einem Kubernetes Secret gemounted
105 -* **Persistence **- Hier wird angegeben, wie die Daten persistent gespeichert werden - im Prinzip eine Art Festplatte für ein Kubernetes Pod. Im Makerspace gibt es dafür zwei Storage Classes, die werden im Artikel über unseren [[confluencePage:page:IN.Kubernetes Cluster]] genauer beschrieben
106 -* **Ingress **- Hier wird angegeben, unter welcher Domain N8n erreichbar sein soll und wie das Zertifkat erzeugt wird.
135 +=== mksp.backend.user.converted_to_guest ===
107 107  
108 -\\
137 +Dieser Workflow wird dann ausgelöst, wenn ein Mitglied den Verein verlässt und daher zum Gast wird.
138 +
139 +[[image:1771785245954-780.png||height="150"]]
140 +
141 +Alle notwendigen Daten (inklusive der Paperless Korrespondent-ID) sind im NATS Event vorhanden. Es wird also lediglich ein neuer Display-Name erzeugt (Format: siehe Tabelle oben) und der Korrespondent wird aktualisiert.
142 +
143 +=== mksp.backend.user.converted_to_member ===
144 +
145 +Dieser Workflow wird dann ausgelöst, wenn ein neues Mitglied dem Verein beitritt.
146 +
147 +[[image:1771785309574-242.png||height="150"]]
148 +
149 +Alle notwendigen Daten (inklusive der Paperless Korrespondent-ID) sind im NATS Event vorhanden. Es wird also lediglich ein neuer Display-Name erzeugt (Format: siehe Tabelle oben) und der Korrespondent wird aktualisiert.
150 +
151 += N8n Nodes =
152 +
153 +N8n nodes sind im Prinzip die Schnittstelle zwischen N8n und externen Tools. Einige Funktionalitäten sind Teil des N8n Cores (beispielsweise HTTP Anfragen, MQTT, ...), andere müssen über externe Nodes hinzugefügt werden. Für einige Tools nutzen wir bestehende Community Nodes, für andere haben wir selbst welche entwickelt.
154 +
155 +== Paperless Node ==
156 +
157 +Es gibt stand heute keinen Community Node für die Anbindung von Paperless. Wir haben daher im Rahmen des Projekts diesen Community Node erstellt und unter eine Open Source Lizenz gestellt.
158 +
159 +Der Paperless Node inklusive Beschreibung ist auf [[GitHub verfügbar>>https://github.com/makerspace-darmstadt/n8n-nodes-paperless]].
160 +
161 +== NATS Node ==
162 +
163 +NATS ist die Event-Queue, die Events zwischen dem Backend und der Infrastruktur im Makerspace transportiert. Das Setup [[ist hier im Wiki beschrieben>>doc:PROJ.Digitale Mitgliederverwaltung.Technische Dokumentation.NATS Setup.WebHome]]. Die bestehenden NATS Nodes hatten entweder kein Support für Trigger Nodes, oder haben TLS fehlerhaft implementiert und daher keine Verbindung zu unserer NATS Umgebung ermöglicht, die korrekte Zertifikate benötigt. Wir haben daher im Rahmen des Projekts diesen Community Node erstellt und unter eine Open Source Lizenz gestellt.
164 +
165 +Der NATS Node inklusive Beschreibung ist auf [[GitHub verfügbar>>https://github.com/makerspace-darmstadt/n8n-nodes-nats]].
Icon 1771784637258-114.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.dherrman
Größe
... ... @@ -1,0 +1,1 @@
1 +201.1 KB
Inhalt Icon
Icon 1771785245954-780.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.dherrman
Größe
... ... @@ -1,0 +1,1 @@
1 +63.2 KB
Inhalt Icon
Icon 1771785309574-242.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.dherrman
Größe
... ... @@ -1,0 +1,1 @@
1 +63.0 KB
Inhalt Icon
Icon 1771785764191-239.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.dherrman
Größe
... ... @@ -1,0 +1,1 @@
1 +92.9 KB
Inhalt Icon
Icon 1771785973968-394.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.dherrman
Größe
... ... @@ -1,0 +1,1 @@
1 +83.1 KB
Inhalt Icon
Icon 1771786234093-932.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.dherrman
Größe
... ... @@ -1,0 +1,1 @@
1 +56.7 KB
Inhalt Icon
Icon 1771786279823-587.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.dherrman
Größe
... ... @@ -1,0 +1,1 @@
1 +173.8 KB
Inhalt Icon
Icon 1771790486089-157.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.dherrman
Größe
... ... @@ -1,0 +1,1 @@
1 +227.4 KB
Inhalt Icon
Icon 1771790995906-398.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.dherrman
Größe
... ... @@ -1,0 +1,1 @@
1 +280.3 KB
Inhalt Icon