Introduction

Avant de raccorder votre premier workflow réel dans n8n, vous devez comprendre une chose qui gêne presque tous les débutants : n8n ne transmet pas de fichiers bruts ni de flux entre les nœuds. Il transmet des éléments. Tout — une charge utile de webhook, une ligne de base de données, une réponse API — est enveloppé dans un élément structuré avant de passer au nœud suivant. Maîtrisez ce modèle mental dès le début, et le débogage devient énormément plus facile.

Qu’est-ce qu’un Élément ?

Un élément est l’unité de données fondamentale dans n8n. Chaque nœud reçoit un tableau d’éléments et en sort un autre. Chaque élément est un objet JavaScript avec une clé obligatoire appelée json, qui contient vos réelles données de charge utile sous forme d’un objet JSON. Optionnellement, un élément peut aussi porter des données binaires (pour des fichiers, des images, etc.), mais cela est couvert séparément.

Un seul élément ressemble à ceci à son cœur :

{
  "json": {
    "id": 42,
    "name": "Alice",
    "email": "alice@example.com"
  }
}

Lorsqu’un nœud comme HTTP Request obtient une liste d’utilisateurs depuis une API, n8n ne transmet pas au nœud suivant un seul grand tableau. Il divise ce tableau et passe au nœud suivant un élément par utilisateur. Cela signifie que si votre API renvoie 10 utilisateurs, le nœud en aval s’exécute 10 fois — une fois par élément. Cette comportement est fondamental pour la façon dont n8n pense.

Comment le JSON circule entre les nœuds

Lorsque vous référencez des données d’un nœud précédent, vous accédez toujours à la clé json d’un élément. Dans les expressions, n8n utilise la syntaxe suivante pour accéder à la sortie du nœud précédent:

{{ $json.fieldName }}

Si vous souhaitez extraire des données d'un nœud nommé spécifique plutôt que celui qui précède immédiatement, vous utilisez :

{{ $node["NodeName"].json.fieldName }}

En pratique, si vous avez un nœud Set qui produit un élément avec la structure montrée précédemment, le nœud suivant peut référencer l’email de l’utilisateur comme ceci :

{{ $json.email }}

L’élément clé à internaliser : vous ne travaillez jamais avec le corps HTTP brut en tant que chaîne. Au moment où les données atteignent votre expression, n8n les a déjà analysées en objet json. Vous n’avez pas besoin d’appeler JSON.parse() vous-même.

Le modèle d’exécution

n8n traite les éléments un par un à travers chaque nœud, dans l’ordre. Lorsqu’un nœud reçoit plusieurs éléments, il les parcourt automatiquement — vous n’écrivez pas de boucle. C’est ce qu’on appelle le modèle d’exécution basé sur les éléments.

Considérez un workflow qui lit 50 lignes d’une base de données, transforme chaque ligne et envoie un e-mail par ligne. Vous n’écrivez pas « pour chaque ligne, envoyer un e-mail ». Vous connectez simplement les nœuds. n8n gère l’itération.

Cela a des implications importantes :

Tout d’abord, chaque nœud de la chaîne s’exécute une fois par élément par défaut. Un nœud qui ajoute un champ horodatage s’exécutera 50 fois pour 50 éléments, produisant 50 éléments de sortie.

Deuxièmement, certains nœuds fusionnent délibérément ou divisent le nombre d’éléments. Le nœud Merge peut combiner des flux. Le nœud SplitInBatches peut regrouper les éléments. Le nœud Code peut remodeler l’ensemble du tableau si nécessaire. Être conscient de la façon dont votre nombre d’éléments change au cours du workflow est la clé pour éviter des comportements inattendus.

Troisièmement, si un nœud échoue sur un élément, par défaut l’exécution entière s’arrête. Vous pouvez configurer la gestion des erreurs par nœud pour changer cela, mais la valeur par défaut est l’échec rapide.

Exemple pratique

Voici à quoi ressemble réellement un tableau d’items lorsqu’il entre dans un nœud Code. Vous pouvez inspecter cela vous-même en utilisant le debugger intégré en cliquant sur le panneau de sortie de n’importe quel nœud.

[
  {
    "json": {
      "orderId": "ORD-001",
      "amount": 120.5,
      "status": "pending"
    }
  },
  {
    "json": {
      "orderId": "ORD-002",
      "amount": 89.0,
      "status": "shipped"
    }
  }
]

Si vous placez un nœud Code après celui-ci et que vous souhaitez ajouter un indicateur processed à chaque élément, vous écrivez :

for (const item of items) {
  item.json.processed = true;
}
return items;

Notez que vous parcourez vous-même les éléments à l’intérieur du nœud Code — c’est la seule exception à la règle « n8n gère les boucles pour vous ». Le nœud Code vous remet le tableau complet et attend le tableau complet en retour.

Résumé

Chaque morceau de données dans n8n est enveloppé dans un item avec une clé json. Les nœuds reçoivent et émettent des tableaux d’items, et par défaut chaque nœud s’exécute une fois par item — vous ne gérez pas les boucles en dehors du nœud Code. Des expressions comme $json.fieldName permettent d’atteindre les données de l’item. Comprendre ce modèle d’exécution est la base de tout le reste : les transformations, le branching, la fusion et la gestion des erreurs se construisent directement dessus.