Gestion d'état avec données statiques de workflow

1. Le Concept de Données Statiques (getWorkflowStaticData)

Pour permettre à un workflow de conserver un état, n8n propose une fonction intégrée spéciale, accessible via le nœud Code ou dans les expressions : $getWorkflowStaticData().

Cette fonction vous donne accès à un petit espace de stockage de type clé-valeur (un objet JSON) qui est attaché de manière persistante à votre workflow. Chaque fois que le workflow s'exécute avec succès, n8n sauvegarde automatiquement toute modification apportée à cet objet.

Pour bien comprendre les bases, la documentation officielle de n8n est la meilleure source.

Comme vous l'avez lu, il y a quelques points cruciaux à retenir :

• Petites données uniquement : Ne l'utilisez pas pour stocker de grands volumes de données. C'est fait pour des compteurs, des timestamps, des identifiants ou des petits objets de configuration.
• Exécution active requise : Les données ne sont sauvegardées que lors d'une exécution réelle (déclenchée par un trigger ou un webhook), pas lors d'un test manuel via l'interface de n8n.
• Sauvegarde automatique : Vous n'avez qu'à modifier l'objet en JavaScript. Si le workflow se termine avec succès, n8n s'occupe de persister les changements.

2. Types de Données Statiques : global vs. node

La fonction $getWorkflowStaticData() accepte un argument qui définit la portée (scope) des données :

1. $getWorkflowStaticData('global') : C'est le mode que vous utiliserez 99% du temps. Il donne accès à un objet de données partagé par tous les nœuds Code au sein du même workflow. C'est idéal pour gérer un état global pour l'ensemble du processus.

2. $getWorkflowStaticData('node') : Ce mode donne accès à un objet de données qui est unique et privé au nœud Code qui l'appelle. C'est un cas d'usage plus rare, utile si vous voulez vous assurer qu'il n'y a aucune collision de noms de variables entre différents nœuds qui gèrent leur propre état interne.

Les exemples de code dans la documentation (LINK) que vous venez de consulter illustrent clairement la syntaxe pour les deux types. Pour la suite de cette leçon, nous nous concentrerons sur le type global, qui est le plus courant.

3. Cas d'Usage 1 : Mémoriser le Timestamp de la Dernière Exécution

Le cas d'usage le plus classique est de permettre à un workflow de ne traiter que les données créées ou modifiées depuis sa dernière exécution.

Imaginez un workflow qui s'exécute toutes les heures pour vérifier de nouveaux utilisateurs dans une base de données. Au lieu de récupérer tous les utilisateurs à chaque fois, il peut demander uniquement ceux créés après le timestamp de sa dernière exécution.

Voici comment vous pourriez implémenter cela avec un nœud Code :

// 1. Récupérer l'objet de données statiques
const staticData = $getWorkflowStaticData('global');

// 2. Lire la valeur de la dernière exécution (si elle existe)
// S'il n'y a pas de valeur, on peut utiliser une date lointaine dans le passé
const lastRunTimestamp = staticData.lastSuccessfulRun || '2000-01-01T00:00:00.000Z';

// 3. Passer ce timestamp au nœud suivant pour qu'il puisse l'utiliser
// Par exemple, dans une requête API : '.../items?since=' + lastRunTimestamp
items[0].json.fetchSince = lastRunTimestamp;

// 4. Mettre à jour le timestamp pour la PROCHAINE exécution
// Nous utilisons la date et l'heure actuelles
staticData.lastSuccessfulRun = new Date().toISOString();

// 5. Retourner les données pour que le workflow continue
return items;

Avec ce simple nœud Code au début de votre workflow, chaque exécution "sait" quand la dernière s'est terminée avec succès.

4. Cas d'Usage 2 : Reprendre un Web Scraping Interrompu

Voici un scénario très pratique qui démontre la puissance de la gestion d'état. Imaginez que vous devez scraper un site de e-commerce avec 500 pages de produits. Il est probable que votre scraping soit bloqué par le site après un certain nombre de requêtes. Sans gestion d'état, vous devriez tout recommencer. Avec les données statiques, vous pouvez reprendre là où vous vous êtes arrêté.

L'approche est la suivante :

1. Au début du workflow : Un nœud Code vérifie si une page a été sauvegardée dans les données statiques. Si oui, il commence à partir de cette page. Sinon, il commence à la page 1.
2. À la fin d'un lot de traitement : Après avoir scrapé avec succès un certain nombre de pages (par ex. 10), un autre nœud Code met à jour les données statiques avec le numéro de la dernière page traitée.

De cette manière, même si le workflow s'arrête, la prochaine exécution reprendra au bon endroit.

L'article ci-dessous utilise les données statiques pour agréger des résultats lors d'une pagination, ce qui est une technique très similaire.

Voici à quoi ressemblerait le code pour implémenter cette logique de reprise :

Nœud Code au début du workflow : "Lire l'état"

const staticData = $getWorkflowStaticData('global');

// Si `lastScrapedPage` existe, on commence à la page suivante. Sinon, page 1.
const startPage = staticData.lastScrapedPage ? staticData.lastScrapedPage + 1 : 1;

// On renvoie la page de départ pour le nœud HTTP Request
return [{ json: { pageToScrape: startPage } }];

Nœud Code à la fin de la boucle de scraping : "Sauvegarder l'état"
Cet exemple suppose que le workflow a traité une page et que son numéro est disponible dans $json.processedPageNumber.

const staticData = $getWorkflowStaticData('global');

// On met à jour la donnée statique avec le numéro de la dernière page traitée
staticData.lastScrapedPage = $json.processedPageNumber;

// Ce nœud sert juste à mettre à jour l'état, on peut retourner un item vide.
return [];

Cette architecture rend vos processus de collecte de données beaucoup plus résilients.

5. Alternatives : Données Statiques vs. Data Tables

En tant que consultant, il est crucial de savoir quand utiliser le bon outil. Les données statiques sont excellentes, mais elles ne sont pas la seule option pour stocker des données dans n8n. Une alternative plus récente et plus structurée est la fonctionnalité Data Tables.

Regardez cette courte introduction pour comprendre ce que sont les Data Tables et en quoi elles diffèrent des données statiques.

Voici un tableau comparatif pour vous aider à choisir :

En résumé, utilisez les données statiques pour la gestion d'état interne et simple d'un workflow. Dès que les données doivent être partagées, structurées ou plus volumineuses, les Data Tables ou une base de données externe sont de meilleures options.

Conclusion

Vous avez maintenant ajouté une compétence fondamentale à votre arsenal n8n : la capacité de créer des workflows avec état. En utilisant getWorkflowStaticData, vous pouvez surmonter la nature "sans mémoire" des exécutions et construire des automatisations plus intelligentes et résilientes.

Points clés à retenir :

• Les données statiques permettent de persister un petit objet JSON entre les exécutions d'un même workflow.
• La fonction $getWorkflowStaticData('global') est l'outil principal pour y accéder depuis un nœud Code.
• C'est une fonctionnalité "expérimentale" qui fonctionne mieux pour des données de petite taille et des exécutions pas trop fréquentes.
• Les cas d'usage typiques sont la mémorisation d'un timestamp de dernière exécution ou la gestion d'un état de reprise pour des tâches longues comme le scraping.
• Pour des besoins de stockage plus importants ou partagés, les Data Tables de n8n ou une base de données externe sont des alternatives à considérer.

Dans la prochaine leçon, nous mettrons en pratique la modularité en refactorisant un workflow complexe à l'aide de sous-workflows. Peu après, un exercice dédié vous permettra d'appliquer concrètement ce que vous avez appris aujourd'hui sur les données statiques pour construire un workflow de scraping résilient.