Sub-Workflows: Module statt Monolith

Ein Workflow mit fünfzig Nodes und fünf Datenquellen ist schwer zu ändern. Jede Anpassung an der Rechnungsprüfung berührt den gesamten Ablauf, und neue Kollegen brauchen lange, um ihn zu verstehen.

Genau dafür gibt es in n8n Sub-Workflows. Ein Workflow ruft einen anderen auf, erhält dessen Ergebnis zurück und läuft weiter, ähnlich wie eine Funktion im Programmcode. Dieser Artikel zeigt die beiden beteiligten Nodes, die Konfiguration als JSON, die Zugriffsregeln und die häufigsten Fehlerbilder.

Was ist ein Sub-Workflow in n8n?

Ein Sub-Workflow ist ein normaler n8n-Workflow, der von einem anderen Workflow gestartet wird und ein Ergebnis zurückgibt. Laut der n8n-Dokumentation zum Aufteilen von Workflows bauen Sie damit modulare, microservice-ähnliche Abläufe statt eines einzigen großen Workflows.

Zwei Nodes bilden das Fundament. Im aufrufenden Workflow sitzt der Execute Sub-workflow Node. Im aufgerufenen Workflow steht der Execute Sub-workflow Trigger Node, in der Node-Suche als "When Executed by Another Workflow" geführt. Er muss der erste Node sein.

Wann lohnt sich die Aufteilung in Module?

Die Aufteilung lohnt sich, sobald eine Logik mehrfach gebraucht wird oder ein Workflow unübersichtlich wird. Bei kleinen, einmalig genutzten Abläufen bleibt der Monolith die einfachere Wahl.

Kriterium | Ein großer Workflow | Aufteilung in Sub-Workflows

Kriterium: Geschäftsregel ändern · Ein großer Workflow: An jeder Kopie einzeln · Aufteilung in Sub-Workflows: An einer Stelle im Modul

Kriterium: Wiederverwendung · Ein großer Workflow: Nur per Kopieren der Nodes · Aufteilung in Sub-Workflows: Aufruf aus beliebig vielen Workflows

Kriterium: Testen · Ein großer Workflow: Nur der komplette Ablauf · Aufteilung in Sub-Workflows: Jedes Modul einzeln ausführbar

Kriterium: Ausführungslimit des Plans · Ein großer Workflow: Jede Ausführung zählt · Aufteilung in Sub-Workflows: Sub-Ausführungen zählen nicht mit

Kriterium: Speicherbedarf · Ein großer Workflow: Steigt mit der Workflow-Größe · Aufteilung in Sub-Workflows: Verteilt sich auf mehrere Ausführungen

Kriterium: Arbeitsteilung im Team · Ein großer Workflow: Alle im selben Workflow · Aufteilung in Sub-Workflows: Getrennte Module je Zuständigkeit

Zum Limit steht in der Dokumentation wörtlich, dass Sub-Workflow-Ausführungen nicht gegen das monatliche Ausführungs- oder aktive Workflow-Limit Ihres Plans zählen. Das hilft zusätzlich bei Speicherproblemen großer Workflows.

Wie definieren Sie die Eingaben eines Sub-Workflows?

Die Eingaben legen Sie im Trigger-Node über den Parameter Input data mode fest. Drei Modi stehen zur Wahl.

Input data mode | Verhalten | Geeignet für

Input data mode: Define using fields below · Verhalten: Sie geben Feldnamen und Datentyp einzeln vor · Geeignet für: Produktive Module mit festem Vertrag

Input data mode: Define using JSON example · Verhalten: n8n leitet Struktur und Typen aus einem Beispiel ab · Geeignet für: Bestehende Datenstrukturen übernehmen

Input data mode: Accept all data · Verhalten: Der Trigger nimmt alles entgegen, ohne Vorgaben · Geeignet für: Prototypen und Debugging

Bei "Accept all data" zeigt der aufrufende Node keine Eingabefelder an. Der Sub-Workflow muss dann fehlende Werte selbst abfangen. Das folgende JSON definiert zwei typisierte Eingaben und lässt sich direkt in n8n importieren.

1{
2  "name": "Kundendaten validieren",
3  "nodes": [
4    {
5      "parameters": {
6        "inputSource": "workflowInputs",
7        "workflowInputs": {
8          "values": [
9            { "name": "kundennummer", "type": "string" },
10            { "name": "auftragssumme", "type": "number" }
11          ]
12        }
13      },
14      "name": "When Executed by Another Workflow",
15      "type": "n8n-nodes-base.executeWorkflowTrigger",
16      "typeVersion": 1.1,
17      "position": [0, 0]
18    }
19  ],
20  "connections": {},
21  "settings": { "executionOrder": "v1" }
22}
Copy

Wie rufen Sie den Sub-Workflow auf?

Den Aufruf übernimmt der Execute Sub-workflow Node im übergeordneten Workflow. Sie wählen die Quelle, füllen die Eingabefelder und legen den Ausführungsmodus fest.

Quelle | Bedeutung | Hinweis

Quelle: Database · Bedeutung: Workflow aus der Liste oder per Workflow-ID · Hinweis: Standard und empfohlene Variante

Quelle: Define Below (Parameter) · Bedeutung: Workflow-JSON direkt im Node · Hinweis: Für kurze, fest verdrahtete Abläufe

Quelle: Local File · Bedeutung: JSON-Datei auf dem n8n-Host · Hinweis: Als veraltet markiert, entfällt künftig

Quelle: URL · Bedeutung: Workflow von einer Web-Adresse · Hinweis: Als veraltet markiert, entfällt künftig

Die Workflow-ID steht am Ende der Workflow-URL hinter /workflow/. Beim Modus gilt: Run once with all items übergibt alle Items in einer Ausführung. Run once for each item ist laut Node-Hinweis veraltet. Nutzen Sie stattdessen einen Loop Over Items Node vor dem Aufruf.

1{
2  "parameters": {
3    "workflowId": {
4      "__rl": true,
5      "value": "abCDE1f6gHiJKL7",
6      "mode": "id"
7    },
8    "workflowInputs": {
9      "mappingMode": "defineBelow",
10      "value": {
11        "kundennummer": "={{ $json.kundennummer }}",
12        "auftragssumme": "={{ $json.summe }}"
13      },
14      "matchingColumns": [],
15      "schema": [
16        {
17          "id": "kundennummer",
18          "displayName": "kundennummer",
19          "required": false,
20          "defaultMatch": false,
21          "display": true,
22          "canBeUsedToMatch": true,
23          "type": "string"
24        },
25        {
26          "id": "auftragssumme",
27          "displayName": "auftragssumme",
28          "required": false,
29          "defaultMatch": false,
30          "display": true,
31          "canBeUsedToMatch": true,
32          "type": "number"
33        }
34      ],
35      "attemptToConvertTypes": false,
36      "convertFieldsToString": true
37    },
38    "mode": "once",
39    "options": { "waitForSubWorkflow": true }
40  },
41  "name": "Kundendaten validieren aufrufen",
42  "type": "n8n-nodes-base.executeWorkflow",
43  "typeVersion": 1.2,
44  "position": [420, 0]
45}
Copy

Die Option Wait For Sub-Workflow Completion steht standardmäßig auf true. Der Hauptworkflow wartet dann auf das Ergebnis. Schalten Sie sie ab, läuft er sofort weiter und erhält keine Rückgabewerte.

Wer darf einen Sub-Workflow aufrufen?

Den Zugriff regelt die Workflow-Einstellung This workflow can be called by. Den Standard für die gesamte Instanz setzen Sie über eine Umgebungsvariable.

Wert von `N8N_WORKFLOW_CALLER_POLICY_DEFAULT_OPTION` | Bedeutung

Wert von N8N_WORKFLOW_CALLER_POLICY_DEFAULT_OPTION: workflowsFromSameOwner · Bedeutung: Standardwert, nur Workflows desselben Eigentümers

Wert von N8N_WORKFLOW_CALLER_POLICY_DEFAULT_OPTION: workflowsFromAList · Bedeutung: Nur ausdrücklich freigegebene Workflows

Wert von N8N_WORKFLOW_CALLER_POLICY_DEFAULT_OPTION: any · Bedeutung: Jeder Workflow der Instanz

Wert von N8N_WORKFLOW_CALLER_POLICY_DEFAULT_OPTION: none · Bedeutung: Kein anderer Workflow

Die Einstellung setzt geteilte Workflows voraus. Details stehen in der Dokumentation zu den Umgebungsvariablen für Workflows.

Wie fließen die Daten zwischen Haupt- und Sub-Workflow?

Die Daten wandern in zwei Schritten. Der Execute Sub-workflow Node übergibt seine Items an den Trigger-Node des Sub-Workflows. Der letzte Node des Sub-Workflows schickt sein Ergebnis zurück an den aufrufenden Node.

Über den Link View sub-execution springen Sie aus der Ausführung des Hauptworkflows in die des Sub-Workflows. Der Rückweg funktioniert genauso. Beim Debuggen verschachtelter Module ist das der schnellste Einstieg.

Wie wandeln Sie einen bestehenden Workflow in Module um?

Markieren Sie die gewünschten Nodes, klicken Sie mit der rechten Maustaste auf den Hintergrund und wählen Sie "Convert to sub-workflow". Die Funktion ist laut n8n-Dokumentation zur Umwandlung ab Version 1.97.0 verfügbar.

Für die Auswahl gelten vier Regeln:

• Trigger-Nodes dürfen nicht enthalten sein.
• Nur ein Node der Auswahl darf eingehende Verbindungen von außen haben, über einen einzigen Eingabezweig.
• Nur ein Node der Auswahl darf ausgehende Verbindungen nach außen haben, über einen einzigen Ausgabezweig.
• Alle Nodes zwischen Ein- und Ausstiegspunkt gehören in die Auswahl.

Nach der Umwandlung prüfen Sie drei Punkte. Neue Sub-Workflows nutzen die Ausführungsreihenfolge v1, unabhängig vom Ursprungsworkflow. Bei KI-Nodes müssen verbundene Sub-Nodes komplett mit ausgewählt sein. Ausdrücke mit first(), last() und all() schreibt n8n unter Umständen um.

Wer viele wiederkehrende Abläufe automatisiert, etwa Angebots- oder Rechnungsprozesse, profitiert besonders von dieser Struktur. NordFlux baut solche modularen Automatisierungen im Rahmen der n8n-Einrichtung auf.

Typische Fehler und Ursachen

Fünf Fehlerbilder treten bei Sub-Workflows besonders häufig auf. Alle lassen sich über die Node- oder Workflow-Einstellungen lösen.

Der übergeordnete Workflow kann den Sub-Workflow nicht starten.

Ursache: Der Sub-Workflow enthält selbst Fehler. Lösung: Sub-Workflow einzeln ausführen und alle Node-Fehler beheben, bevor Sie ihn einbinden. Quelle: Execute Sub-workflow Trigger.

Der Aufruf wird abgewiesen, obwohl die Workflow-ID stimmt.

Ursache: Die Einstellung "This workflow can be called by" verbietet den Aufruf, meist wegen des Standardwerts workflowsFromSameOwner. Lösung: Aufrufer freigeben oder den Standard über die Umgebungsvariable ändern. Quelle: Workflow-Einstellungen.

Der Sub-Workflow erhält `null` statt eines Werts.

Ursache: Das Eingabefeld wurde im Execute Sub-workflow Node entfernt. Lösung: Feld wieder mappen oder im Sub-Workflow einen Standardwert setzen. Quelle: Execute Sub-workflow.

Der Aufruf bricht mit einem Typfehler ab.

Ursache: Der übergebene Wert passt nicht zum deklarierten Typ, etwa Text statt Zahl. Lösung: Option "Attempt to convert types" aktivieren oder den Wert vorher umwandeln. Quelle: Execute Sub-workflow.

Der Hauptworkflow arbeitet ohne das Ergebnis weiter.

Ursache: Die Option "Wait For Sub-Workflow Completion" ist ausgeschaltet. Lösung: Option einschalten, wenn die Folgeschritte auf die Rückgabe angewiesen sind. Quelle: Execute Sub-workflow.

Für Fehler, die trotzdem durchrutschen, hinterlegen Sie in den Workflow-Einstellungen einen Error workflow. Er beginnt mit dem Error Trigger Node und erhält Fehlermeldung, Ausführungs-ID und Workflow-Namen. Quelle: Fehler sauber behandeln.

Häufige Fragen

Wann lohnt sich ein Sub-Workflow und wann nicht?

Ein Sub-Workflow lohnt sich, sobald eine Logik mehrfach gebraucht wird oder ein Workflow unübersichtlich wächst. Bei kleinen, einmalig genutzten Abläufen mit wenigen Nodes überwiegt der Aufwand für den zusätzlichen Aufruf.

Kann ein Sub-Workflow selbst wieder einen Sub-Workflow aufrufen?

Ja, Sub-Workflows lassen sich verschachteln. Behalten Sie die Verschachtelungstiefe im Blick, damit sich Fehler beim Debuggen noch eindeutig zuordnen lassen.

Was passiert, wenn der Sub-Workflow fehlschlägt?

Enthält der Sub-Workflow Fehler, kann der übergeordnete Workflow ihn laut Dokumentation nicht auslösen. Testen Sie deshalb jedes Modul einzeln und hinterlegen Sie einen Error workflow.

Zählen Sub-Workflow-Ausführungen zu meinem n8n-Limit?

Nein. Laut n8n-Dokumentation zählen Sub-Workflow-Ausführungen nicht gegen das monatliche Ausführungs- oder aktive Workflow-Limit Ihres Plans.

Kann ich einen bestehenden Workflow nachträglich in Module aufteilen?

Ja, über "Convert to sub-workflow" im Kontextmenü. Die Auswahl braucht genau einen Ein- und einen Ausstiegspunkt. Prüfen Sie danach Ausführungsreihenfolge und Ausdrücke.