n8n-Workflows bauen — Cheat Sheet

Der erste von zwei Spickzetteln zum Seminar n8n in der Praxis: alles, was man beim Bauen eines Workflows nachschlägt. Was danach kommt — KI-Bausteine, Rollen, Umgebungen, Betrieb — steht auf n8n: KI und Betrieb.

Maßgeblich ist docs.n8n.io. Dieses Blatt hält die Unterscheidungen fest, deren Verwechslung einen Workflow grün durchlaufen und trotzdem falsch arbeiten lässt.

Einordnung: Anlass und Muster

Die zweite Tabelle ordnet ein, sie wertet nicht — die Wahl entscheidet der konkrete Prozess. n8n verbindet Systeme und steuert Abläufe; es ersetzt keine Fachanwendung.

Modul: n8n und moderne Workflow-Automatisierung

Ausführungsarten und Veröffentlichen

Produktive Läufe ignorieren angeheftete Daten und zählen bei bezahlten Plänen gegen das Kontingent. Erst das Veröffentlichen schaltet die Produktions-URLs von Webhook- und Formular-Triggern scharf, lässt Zeitpläne laufen und App-Ereignisse durch. Wer nur die Workflow-Einstellungen ändert, dessen Version veröffentlicht n8n selbst neu.

Angeheftete Daten veralten nach Änderungen — und zwar gezielt, nicht pauschal:

Innerhalb einer Schleife gilt zusätzlich der erste Node der Schleife als veraltet. Unveröffentlichen ist nicht Löschen: der Workflow bleibt bestehen.

Modul: Workflows, Nodes und Executions verstehen

Workflow-Einstellungen mit Folgen

Die ungesetzte Zeitzone ist der häufigste stille Fehler: Der nächtliche Lauf startet am Nachmittag, und nichts meldet es.

Modul: Workflows, Nodes und Executions verstehen

Das Item-Modell: json und binary

[{
  "json": { "anlage": "KW-3312", "vorlauf": 62 },
  "binary": {
    "protokoll": {
      "data": "....",
      "mimeType": "application/pdf",
      "fileName": "wartung.pdf"
    }
  }
}]

data ist Pflicht und Base64-kodiert; mimeType, fileExtension und fileName sind empfohlen. Aus dieser Struktur folgt das meiste Verhalten: Zwei Items im Eingang heißen zwei Aufrufe im Node, nicht einer mit zwei Werten. Ein Node, der nichts zurückgibt, lässt den Zweig dahinter leer laufen. Binärdaten stehen nie unter json — Transformations-Nodes für json lassen sie unberührt oder verlieren sie. Nur Code- und Function-Node ergänzen einen fehlenden json-Schlüssel selbst.

Modul: Das n8n-Datenmodell sicher beherrschen

Expressions und Item Linking

{{ $json.anlage }}
{{ $json.body.plz }}
{{ $('Kundenkreis').item.json.vertragsart }}
{{ $('Kundenkreis').first().json.kundennummer }}
{{ $('Kundenkreis').all()[2].json.ort }}
{{ $workflow.name }}   {{ $execution.id }}
{{ $jmespath($json.anlagen, "[*].seriennummer") }}

.item wirft einen Item-Linking-Fehler, wenn der Faden zu den Vorgängern unterbrochen ist — meist an einer Zusammenführung — oder wenn er auf mehrere Items zeigt. n8n rät dann nicht, sondern meldet. Der Ausweg über first() oder all()[n] ist nur dann richtig, wenn die Position fachlich feststeht; sonst verschiebt er das Problem auf den Tag, an dem die Reihenfolge wechselt. Die JMESPath-Syntax steht in der JMESPath-Dokumentation, nicht bei n8n.

Modul: Das n8n-Datenmodell sicher beherrschen

Transformations-Nodes

Ein einzelner Parameterwert aus vorhandenen Daten ist eine Expression. Eine der obigen Standardoperationen ist ein Node. Eigener Umbau von Arrays und Objekten oder viele Items auf einmal sind der Code-Node.

Modul: Das n8n-Datenmodell sicher beherrschen

Trigger und Webhook-Antwortmodi

Abrufen oder benachrichtigt werden ist die Grundentscheidung: Die Verzögerung beim Abrufen ist so groß wie der Abfrageabstand, nie kleiner. Ereignisse gehen dafür verloren, wenn niemand zuhört — Abrufen holt sie später nach.

Streaming braucht mindestens einen Node, der es unterstützt. Die maximale Nutzlast liegt bei 16 MB — größere Aufrufe scheitern, bevor der Workflow überhaupt anläuft. Für Wartezustände liefert {{ $execution.resumeUrl }} die Fortsetzungs-URL; sie entsteht erst zur Laufzeit und ist je Ausführung eindeutig.

Modul: Trigger, Webhooks und ereignisgesteuerte Prozesse

HTTP-Aufrufe: Methode, Paginierung, Last

Die rechte Spalte entscheidet, ob ein Wiederholungsversuch nach einem Fehler gefahrlos ist. Für den Rumpf gilt: JSON im Regelfall, Form URLencoded und Form-Data für Formulare und Anhänge, n8n Binary File für Dateien aus dem Workflow, Raw für eigene Formate samt Content-Type.

{{ $pageCount }}
{{ $response.body.next }}
{{ $response.headers.link }}
{{ $response.statusCode }}

Diese Variablen stehen im Paginierungs-Ausdruck und werden je Aufruf neu belegt. Last steuert man über Batching mit Batch Interval in Millisekunden, Timeout für den Antwortbeginn und die Zahl erlaubter Redirects.

Modul: APIs und Unternehmensanwendungen integrieren

Ablauflogik und Sub-Workflow-Verträge

Die ersten beiden Modi zieht der aufrufende Node automatisch als Eingabefelder heran — Accept all data ist der Modus ohne Vertrag. Für die Zerlegung spricht außerdem, dass Sub-Workflow-Ausführungen nicht gegen das monatliche Kontingent zählen und This workflow can be called by begrenzt, wer aufrufen darf.

Modul: Ablaufsteuerung und robuste Workflow-Architektur

Zustand, Dateien und Grenzen

Alle Data Tables einer Instanz teilen sich standardmäßig 200 MiB, per Umgebungsvariable änderbar. Ab 80 Prozent warnt n8n, ab der Grenze schlagen Schreibzugriffe fehl. Aus dem Code-Node gibt es keinen programmatischen Zugriff auf Data Tables, und innerhalb eines Projekts sehen alle Mitglieder sie.

Für lokale Dateien gibt es zusätzlich den Local File Trigger. Die Größe von Binärdaten wirkt unmittelbar auf Speicherbedarf und Laufzeit — früh ablegen und nur die Kennung weiterreichen.

Modul: Ablaufsteuerung und robuste Workflow-Architektur · Datenbanken, Dateien und interne Datenhaltung

Expression, Node oder Code

Der Code-Node hat keinen Zugriff auf das Dateisystem und kann keine HTTP-Aufrufe absetzen. Wiederverwendbar wird Logik als Sub-Workflow, nicht als kopierter Code-Block.

// Run Once for All Items
const offen = $input.all()
  .filter(i => i.json.status === 'offen');
return offen;
// Run Once for Each Item
$input.item.json.dringend =
  $input.item.json.vorlauf < 40;
return $input.item;

Fehlt der json-Schlüssel oder die Array-Klammer, ergänzt der Code-Node beides selbst. Stimmt die Zahl der Ein- und Ausgabe-Items nicht überein, muss der Code die Verkettung selbst setzen — sonst schlägt ein späterer Zugriff über .item fehl.

In der Cloud stehen JavaScript-seitig nur crypto und moment zur Verfügung.

Modul: Expressions, JavaScript und Python

Fehlerverhalten je Node

Dazu Retry On Fail für Wiederholungen und Always Output Data, das auch ohne Ergebnis ein Item liefert — auf einem If-Node erzeugt das eine Endlosschleife. Scheitert schon der Trigger, sieht der Error Workflow ganz andere Daten.

Modul: Fehlerbehandlung, Resilienz und Debugging

Testfälle und Versionshistorie

Benannte Versionen werden nie automatisch aufgeräumt — sie sind der Weg, einen Meilenstein zu behalten. Reviews sind Enterprise, ab n8n 2.37.0, müssen von einem Admin freigeschaltet werden und befinden sich im Preview-Status; n8n benachrichtigt niemanden, der Reviewer muss selbst nachsehen.

Modul: Tests, Qualitätssicherung und kontrollierte Veröffentlichung

Typische Fallen

• Die Test-URL landet in der fremden Anwendung. Produktiv passiert dann nichts, und der Editor meldet trotzdem nichts.
• Angeheftete Daten täuschen einen funktionierenden Abruf vor. Der gelbe Hinweis wird übersehen, das Ergebnis stammt aus einem alten Lauf.
• .item nach einem Merge. Dort ist der Faden nicht mehr eindeutig; first() macht den Fehler weg, nicht das Problem.
• Ein Node wird umbenannt — und jede Expression mit seinem Namen bricht.
• Continue wird gesetzt, damit der Lauf durchgeht. Der Fehler verschwindet damit aus der Sicht, nicht aus der Welt.
• Never Error an, damit es grün bleibt. Dieselbe Falle eine Ebene tiefer.
• Zugangsdaten bleiben nach dem cURL-Import im Node stehen — im Klartext, statt im Credential.
• Die Paginierung läuft endlos, weil die Abbruchbedingung nie zutrifft, oder bricht nach der ersten Seite ab, ohne dass es auffällt.
• Bei 429 wird sofort erneut versucht, statt den Abstand zu vergrößern.
• Werte werden per Expression in SQL-Text eingesetzt. Das ist eine Einladung zur Injektion — und genau das, was der Sicherheitsbericht Database später meldet.
• Die Datei wird durch zehn Nodes gereicht und liegt zehnmal im Speicher.
• Der Code fängt jeden Fehler und gibt ein leeres Array zurück. Eine geworfene Meldung landet im Fehlerzweig und in den Ausführungsdaten, eine still verworfene nirgends.
• Der Fehlerzweig wird gebaut, aber nie ausgelöst — und damit nie getestet.
• Getestet wird mit einem echten Kundendatensatz, weil er zur Hand war.