Introduction

Avant de connecter votre tout premier workflow réel dans n8n, vous devez comprendre une chose qui cause des difficultés à presque tous les débutants : n8n ne transmet pas de fichiers bruts ou de flux entre les nœuds. Il transmet des items. Tout — une charge 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îtriser ce modèle mental dès le départ rend le débogage beaucoup plus facile.

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

Un élément est l’unité fondamentale de données 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 données réelles sous forme d’un objet JSON. Optionnellement, un élément peut aussi porter des données binaires (pour des fichiers, images, etc.), mais cela est couvert séparément.

Un seul élément ressemble à ceci à son noyau :

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

Lorsqu’un nœud comme HTTP Request récupère une liste d’utilisateurs à partir d’une API, n8n ne remet pas au nœud suivant un seul grand tableau. Il divise ce tableau et donne 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. Ce comportement est fondamental pour la façon dont n8n pense.

Comment les JSON circulent 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 ci-dessous pour accéder à la sortie du nœud précédent:

{{ $json.fieldName }}

Si vous voulez récupérer des données à partir d’un nœud nommé spécifique plutôt que du nœud immédiatement précédent, 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’e-mail de l’utilisateur comme ceci :

{{ $json.email }}

L’un des points clés à intégrer est : vous ne travaillez jamais avec le corps brut de la réponse HTTP en tant que chaîne. Au moment où les données arrivent dans votre expression, n8n les a déjà analysées en un 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. On appelle cela 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 :

Premièrement, 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 horodaté s’exécutera 50 fois pour 50 éléments, produisant 50 éléments en sortie.

Deuxièmement, certains nœuds combinent ou divisent délibérément 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 manière dont le nombre d’éléments change au cours du workflow est essentiel pour éviter un comportement inattendu.

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'éléments lorsqu'il entre dans un nœud Code. Vous pouvez inspecter cela vous-même en utilisant le débogueur 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 ceci et que vous voulez ajouter un indicateur traité à chaque élément, vous écrivez :

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

Remarquez que vous parcourez vous-même les éléments à l'intérieur du nœud Code — c'est la seule exception à la règle « les boucles n8n s'occupent de vous » . Le nœud Code vous donne le tableau complet et s'attend à ce que le tableau complet revienne.

Résumé

Chaque morceau de donnée dans n8n est encapsulé 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 de boucles en dehors du nœud Code. Des expressions comme $json.fieldName permettent d’accéder aux données de l’item. Comprendre ce modèle d’exécution est la base de tout le reste : transformations, branches, fusion et gestion des erreurs s’appuient directement dessus.