Ressources · Intégration n8n

Intégration KoBoToolbox n8nAutomatiser KoBoToolbox avec n8n.

Une réponse collectée sur le terrain ne devrait pas attendre un export du lundi matin. L'intégration KoBoToolbox n8n pose un nœud de 17 opérations sur 4 ressources, plus un trigger qui démarre le workflow dès qu'un formulaire reçoit une soumission. Pour les équipes qui collectent hors ligne et traitent au siège.

Tester l'intégration KoBoToolbox sur n8nVoir les 17 opérations

Avis vérifiés sur Trustpilot · Agence IA, automatisation & growth

Pourquoi automatiser

À quoi sert l'intégration KoBoToolbox n8n ?

L'intégration KoBoToolbox n8n relie un compte de collecte de données au reste de tes outils, avec deux nœuds. Le nœud KoBoToolbox rassemble 17 opérations réparties sur 4 ressources : File, Form, Hook et Submission. Le KoBoToolbox Trigger écoute 1 événement et lance un workflow quand un formulaire reçoit une nouvelle soumission. Les deux partagent le même credential, c'est-à-dire l'identifiant enregistré une fois dans n8n, ici un jeton d'API.

Premier scénario, l'export qui se fait tout seul. Chaque nuit, submission.getAll récupère les soumissions d'un formulaire, Return All activé pour ne rien tronquer, et les lignes atterrissent dans Google Sheets. Plus personne ne clique sur « exporter » le lundi matin.

Deuxième scénario, la validation qui reste dans la donnée. Une soumission arrive, le workflow la publie dans un salon Discord, un superviseur tranche, et submission.setValidation écrit Approved, Not Approved ou On Hold directement sur la soumission. La décision reste lisible dans les données par la suite, pas noyée dans un fil de discussion.

Troisième scénario, les hooks qui lâchent sans prévenir. hook.getLogs filtre les logs sur Failed, hook.retryAll relance les tentatives en échec, et une notification Pushover part sur le téléphone de l'astreinte. Une panne côté destinataire cesse d'être une découverte trois semaines plus tard.

Les fichiers suivent le même chemin : file.create pousse une liste de référence reconstruite par le workflow, file.get la ressort en binaire quand un autre système la réclame.

Deux points à garder en tête. Quand un endpoint de l'API KoBoToolbox sort des 17 opérations du nœud, le nœud HTTP Request l'appelle directement et réutilise le même credential via l'authentification prédéfinie : rien ne bloque. Et sur les listes, Return All décide du volume. Désactivé, le nœud s'arrête à Limit, et un export partiel ressemble trait pour trait à un export complet. Si tu veux prendre le nœud en main plus vite, la Formation n8n couvre ce genre d'enchaînement.

Connexion

Comment connecter KoBoToolbox à n8n ?

  1. 01

    Récupérer le jeton d'API

    Connecte-toi au compte KoBoToolbox et ouvre Account Settings : le jeton d'API y est affiché. C'est la seule valeur secrète dont n8n a besoin. Profites-en pour noter sur quel serveur ce compte a été créé, l'étape suivante te le demandera et les deux serveurs ne sont pas interchangeables.

  2. 02

    Créer le credential dans n8n

    Dans n8n, menu Credentials, ajoute un credential KoBoToolbox. API Root URL attend l'adresse du serveur où le compte a été créé : https://kf.kobotoolbox.org pour le serveur global, https://eu.kobotoolbox.org pour le serveur Union européenne. API Token reçoit la chaîne copiée depuis Account Settings. Une fois enregistré, tous tes workflows le réutilisent.

  3. 03

    Choisir le formulaire dans le nœud

    Pose le nœud KoBoToolbox ou le KoBoToolbox Trigger sur le canvas et sélectionne le credential dans la liste déroulante. Form Name or ID charge alors les formulaires du compte : tu choisis par nom, sans aller chercher un identifiant du type aSAvYreNzVEkrWg5Gdcvg. L'identifiant reste possible via une expression, ce petit bout de code que n8n évalue à l'exécution.

Déclencheurs

Qu'est-ce qui démarre un workflow KoBoToolbox ?

KoBoToolbox Trigger est le nœud qui démarre un workflow quand quelque chose se passe dans KoBoToolbox. Il écoute 1 événements, listés ci-dessous par famille. Tu en choisis un ou plusieurs, tu actives le workflow : n8n enregistre le webhook (l'URL que KoBoToolbox appelle) sur ton compte.

Ce que tu vois dans n8n

Tous les événements, par famille

Une ligne par objet, une puce par action. L'événement à cocher dans le nœud s'écrit objet.action ; survole une puce pour lire quand il se déclenche.

form.*1

    Notes de configuration

    01Configure the KoBoToolbox TriggerLe nœud trigger démarre un workflow sur les nouvelles soumissions d'un formulaire donné. Il crée et supprime lui-même le hook côté KoBoToolbox : tu n'as rien à paramétrer dans l'interface de l'outil. Il lit la soumission exactement comme l'opération Get a submission, avec les mêmes options de reformatage.

    Le nœud trigger démarre un workflow sur les nouvelles soumissions d'un formulaire donné. Il crée et supprime lui-même le hook côté KoBoToolbox : tu n'as rien à paramétrer dans l'interface de l'outil. Il lit la soumission exactement comme l'opération Get a submission, avec les mêmes options de reformatage.

    Paramètres clés

    • Form Name or ID : requis, c'est le formulaire écouté. Tu le prends dans la liste que n8n charge depuis le compte, ou tu passes un identifiant comme aSAvYreNzVEkrWg5Gdcvg via une expression.
    • Reformat : dans la collection Options, applique un reformatage aux données de la soumission, comme l'interprétation des coordonnées GeoJSON, au lieu de te livrer la charge brute.
    Quand l'utiliser
    dès que le traitement doit partir au moment de la collecte et non au moment de l'export, d'une alerte superviseur à l'alimentation d'un tableau de suivi.
    02On Form SubmissionformSubmission est le seul événement du catalogue, une famille unique, et il se règle sur le paramètre Trigger On. Le mécanisme est un webhook, autrement dit une URL que KoBoToolbox appelle au moment où la soumission arrive : le workflow part en quelques secondes, sans boucle d'interrogation intermédiaire. Version 1 du trigger.

    formSubmission est le seul événement du catalogue, une famille unique, et il se règle sur le paramètre Trigger On. Le mécanisme est un webhook, autrement dit une URL que KoBoToolbox appelle au moment où la soumission arrive : le workflow part en quelques secondes, sans boucle d'interrogation intermédiaire. Version 1 du trigger.

    Paramètres clés

    • Download Attachments : récupère dans le workflow les photos ou vidéos envoyées avec les réponses, au lieu de les laisser derrière.
    • Attachments Naming Scheme et Attachments Prefix : nomment les propriétés binaires, en séquence ou d'après l'identifiant de la question d'origine, avec un index qui démarre à 0 ajouté au préfixe.
    • File Size : la version de la pièce jointe à récupérer quand plusieurs tailles existent.
    • Multiselect Mask et Number Mask : des sélecteurs séparés par des virgules, pour les champs à traiter comme des tableaux ou comme des nombres.
    Quand l'utiliser
    dès qu'une photo ou une coordonnée compte autant que les réponses, parce que ce sont ces options qui décident de ce qui arrive vraiment dans le workflow.
    Actions

    Que sait faire le nœud KoBoToolbox ?

    Le nœud KoBoToolbox expose 17 opérations sur 4 ressources. Pour chacune : le nœud tel que tu le configures dans n8n, les champs obligatoires, et nos notes de terrain.

    Matrice ressources × opérations
    RessourceCreateGetGet ManyDeleteLogsGet Validation StatusRedeployRetry AllRetry OneUpdate Validation Status
    File✓✓✓✓
    Form✓✓✓
    Hook✓✓✓✓✓
    Submission✓✓✓✓✓

    File

    4 opérations
    01

    Create a file

    file.create

    Ce que tu vois dans n8n

    Notes & cas d'usage

    Envoie un fichier sur un formulaire, soit depuis des données binaires déjà présentes dans le workflow, soit depuis un lien public.

    Paramètres clés

    • Form Name or ID : le formulaire destinataire, choisi dans la liste ou passé sous forme d'identifiant via une expression.
    • File Upload Mode : deux choix, Binary File quand le fichier voyage dans l'item, URL quand KoBoToolbox doit aller le chercher lui-même.
    • Property Name : la propriété binaire qui contient le fichier. Types supportés : image, audio, video, csv, xml et zip.
    • File URL : le lien HTTP(s) vers le fichier, utilisé en mode URL.
    Cas d'usage
    une liste de référence régénérée chaque mois par un workflow et déposée sur le formulaire sans passer par l'interface.
    02

    Delete a file

    file.delete

    Ce que tu vois dans n8n

    Notes & cas d'usage

    Supprime un fichier d'un formulaire, à partir de son identifiant.

    Paramètres clés

    • File ID : l'uid du fichier, qui commence par af, par exemple afQoJxA4kmKEXVpkH6SYbhb. C'est bien l'identifiant, pas le nom du fichier.
    • Form Name or ID : le formulaire auquel ce fichier appartient, utile quand un même workflow en traite plusieurs.
    Cas d'usage
    la seconde moitié d'une routine de mise à jour. On supprime la version périmée, puis Create a file dépose la nouvelle, et le formulaire ne se retrouve jamais avec deux versions du même document.
    03

    Get a file content

    file.get

    Ce que tu vois dans n8n

    Notes & cas d'usage

    Lit un fichier déjà rattaché à un formulaire et peut en ramener le contenu dans le workflow sous forme binaire.

    Paramètres clés

    • File ID : l'uid commençant par af, souvent repris d'un nœud précédent avec {{ $json.field }}.
    • Download File Content : détermine si le contenu est téléchargé dans une propriété binaire.
    • Property Name : le nom de la propriété binaire dans laquelle le fichier est écrit.
    Cas d'usage
    ressortir un document du formulaire pour l'envoyer en pièce jointe, sans ouvrir l'accès au compte KoBoToolbox à toute l'équipe.
    04

    Get many files

    file.getAll

    Ce que tu vois dans n8n

    Notes & cas d'usage

    Liste les fichiers rattachés à un formulaire, avec un seul champ à remplir.

    Paramètres clés

    • Form Name or ID : l'unique champ requis ici. Tu désignes le formulaire, le nœud renvoie ses fichiers.
    Cas d'usage
    l'inventaire avant le ménage. Le workflow parcourt les fichiers, garde ceux qu'il attend, et confie le reste à Delete a file. Pratique aussi sur un formulaire qui a changé de mains plusieurs fois et dont plus personne ne sait ce qu'il contient.

    Form

    3 opérations
    05

    Get a form

    form.get

    Ce que tu vois dans n8n

    Notes & cas d'usage

    Renvoie un formulaire du compte, un seul.

    Paramètres clés

    • Form Name or ID : le formulaire à lire. La liste déroulante va au plus vite ; l'expression sert quand l'identifiant vient d'une étape précédente.
    Cas d'usage
    une étape de consultation au milieu d'un workflow plus long, quand une branche a besoin de la fiche du formulaire avant de décider de la suite, juste avant un redéploiement ou avant d'envoyer un récapitulatif dans un canal.
    06

    Get many forms

    form.getAll

    Ce que tu vois dans n8n

    Notes & cas d'usage

    Parcourt les formulaires du compte et les renvoie sous forme d'items.

    Paramètres clés

    • Return All : coché, le nœud enchaîne les pages de l'API jusqu'au dernier formulaire ; décoché, il s'arrête à Limit.
    • Limit : le nombre maximal de formulaires renvoyés quand Return All reste décoché.
    • Filter : dans Options, une recherche textuelle sur les données du formulaire, par exemple owner__username:meg AND name__icontains:quixotic.
    • Sort : dans Options, les critères de tri appliqués au résultat.
    Cas d'usage
    un inventaire hebdomadaire de tous les formulaires du compte, déposé dans une feuille que les chefs de projet consultent.
    07

    Redeploy Current Form Version

    form.redeploy

    Ce que tu vois dans n8n

    Notes & cas d'usage

    Redéploie la version courante d'un formulaire depuis le workflow.

    Paramètres clés

    • Form Name or ID : le formulaire concerné, désigné une fois dans le nœud et réutilisé à chaque exécution.
    Cas d'usage
    la dernière étape d'une chaîne qui commence ailleurs. Un coordinateur valide une modification dans un canal, le workflow récupère l'accord et lance le redéploiement : l'action laisse une trace d'exécution au lieu de reposer sur la mémoire de quelqu'un.

    Hook

    5 opérations
    08

    Get a hook

    hook.get

    Ce que tu vois dans n8n

    Notes & cas d'usage

    Renvoie la définition d'un hook déclaré sur un formulaire.

    Paramètres clés

    • Hook ID : l'identifiant du hook, qui commence par h, par exemple hVehywQ2oXPYGHJHKtqth4.
    • Form Name or ID : le formulaire qui porte ce hook.
    Cas d'usage
    le contrôle avant relance. Le workflow lit la définition, confirme qu'il s'apprête à agir sur le bon hook, puis continue vers les logs ou vers les opérations de retry en aval.
    09

    Get Many hooks

    hook.getAll

    Ce que tu vois dans n8n

    Notes & cas d'usage

    Liste les hooks déclarés sur un formulaire, histoire de voir à quoi ce formulaire est branché.

    Paramètres clés

    • Return All : coché, tous les hooks du formulaire reviennent ; décoché, le nœud s'arrête à Limit.
    • Limit : le plafond appliqué quand Return All reste décoché.
    Cas d'usage
    un audit sur des formulaires qui tournent depuis longtemps. On collecte les hooks, on garde les identifiants, et on les envoie aux opérations de logs et de relance dans le même workflow.
    10

    Get Logs for a hook

    hook.getLogs

    Ce que tu vois dans n8n

    Notes & cas d'usage

    Récupère les logs d'un hook, avec de quoi resserrer la sélection.

    Paramètres clés

    • Hook ID : le hook dont on veut les logs, identifiant commençant par h.
    • Log Status : All, Failed, Pending ou Success, pour ne garder que ce qui compte.
    • Start Date et End Date : les dates minimale et maximale des logs récupérés.
    Cas d'usage
    un contrôle du matin filtré sur Failed sur la journée écoulée, dont le résultat est compté puis publié dans un canal pour qu'une panne silencieuse se voie.
    11

    Retry All hooks

    hook.retryAll

    Ce que tu vois dans n8n

    Notes & cas d'usage

    Relance toutes les tentatives en échec d'un hook, en un seul appel, sans avoir à parcourir les logs un par un au préalable.

    Paramètres clés

    • Hook ID : le hook dont les tentatives échouées sont rejouées.
    • Form Name or ID : le formulaire auquel ce hook est rattaché.
    Cas d'usage
    la reprise après une coupure du système destinataire. Plutôt que de rejouer log par log, le workflow appelle cette opération une fois par hook et passe à la branche de notification.
    12

    Retry One hook

    hook.retryOne

    Ce que tu vois dans n8n

    Notes & cas d'usage

    Rejoue une tentative précise plutôt que le lot entier.

    Paramètres clés

    • Hook Log ID : le log à rejouer, identifiant commençant par hl, par exemple hlSbGKaUKzTVNoWEVMYbLHe.
    • Hook ID : le hook auquel ce log appartient.
    Cas d'usage
    le complément naturel de Get Logs for a hook. On filtre sur Failed, on boucle sur les résultats, et chaque log est relancé séparément quand on veut connaître le sort de chacun.

    Submission

    5 opérations
    13

    Delete a submission

    submission.delete

    Ce que tu vois dans n8n

    Notes & cas d'usage

    Efface une soumission d'un formulaire.

    Paramètres clés

    • Submission ID : un nombre, par exemple 245128, et non le nom de la personne enquêtée.
    • Form Name or ID : le formulaire qui contient cette soumission.
    Cas d'usage
    nettoyer les entrées de test laissées après une répétition de formulaire, pour que le décompte réel reparte à zéro. Mets une étape de confirmation devant : il n'y a pas de branche d'annulation derrière.
    14

    Get a submission

    submission.get

    Ce que tu vois dans n8n

    Notes & cas d'usage

    Récupère une soumission et ses données, avec une série d'options pour façonner la réponse.

    Paramètres clés

    • Submission ID : l'identifiant numérique de la soumission, souvent passé en {{ $json.field }} depuis un nœud précédent.
    • Fields to Retrieve : une liste séparée par des virgules, du type _submission_time,_submitted_by. Laissé vide, tous les champs reviennent.
    • Reformat : applique la logique de reformatage, dont l'interprétation des coordonnées GeoJSON.
    Cas d'usage
    enrichir une alerte. La notification porte un identifiant, cette opération la transforme en jeu de réponses complet.
    15

    Get many submissions

    submission.getAll

    Ce que tu vois dans n8n

    Notes & cas d'usage

    Rassemble les soumissions d'un formulaire en volume : c'est l'opération sur laquelle reposent la plupart des exports.

    Paramètres clés

    • Return All : coché, le nœud pagine jusqu'à la dernière soumission ; décoché, il s'arrête à Limit.
    • Filter : None ou JSON, et avec JSON, c'est Filters (JSON) qui porte la requête.
    • Sort : dans Options, des prédicats de tri au format JSON MongoDB, par exemple {"_submission_time":1}.
    Cas d'usage
    l'export de nuit vers une feuille de calcul, trié par date de soumission pour que les lignes récentes se retrouvent en bas.
    16

    Get the validation status for a submission

    submission.getValidation

    Ce que tu vois dans n8n

    Notes & cas d'usage

    Indique où en est une soumission dans le circuit de relecture, sans rien y modifier.

    Paramètres clés

    • Submission ID : l'identifiant numérique de la soumission contrôlée.
    • Form Name or ID : le formulaire sur lequel elle a été déposée.
    Cas d'usage
    la condition d'entrée d'un workflow de relecture. On lit le statut d'abord, puis on branche pour ignorer les soumissions déjà traitées par un superviseur, au lieu de relancer le canal une deuxième fois.
    17

    Update the validation status for a submission

    submission.setValidation

    Ce que tu vois dans n8n

    Notes & cas d'usage

    Inscrit la décision de relecture sur la soumission elle-même, pour que le statut vive dans la donnée et pas dans une conversation.

    Paramètres clés

    • Validation Status : Approved, Not Approved ou On Hold, les trois valeurs acceptées par le nœud.
    • Submission ID : l'identifiant numérique de la soumission mise à jour.
    Cas d'usage
    un superviseur répond dans un canal, le workflow traduit sa réponse en l'une des trois valeurs et l'applique, et l'export suivant porte déjà la décision.
    Besoin d'aide

    Besoin d'aide pour automatiser KoBoToolbox avec n8n ?

    L'équipe te répond directement.

    Chaque message est lu par une personne.

    FAQ

    KoBoToolbox et n8n, les questions qui suivent

    01L'intégration KoBoToolbox n8n est-elle gratuite ?
    Oui, côté n8n. Le nœud KoBoToolbox et le KoBoToolbox Trigger sont livrés avec n8n : rien à installer, rien à acheter, pas de passage par une place de marché. C'est vrai sur n8n Cloud, l'offre hébergée par n8n, comme sur une instance auto-hébergée installée en Docker ou en npm sous la Community Edition et sa licence Sustainable Use. Un workflow se comporte de la même façon dans les deux cas, donc un flux monté sur un poste local se déplace vers un serveur sans réécriture. Ce que coûte un compte KoBoToolbox est une autre question, qui n'est pas traitée ici.
    02Quels credentials faut-il pour connecter KoBoToolbox à n8n ?
    Un seul credential, par jeton d'API, avec deux valeurs à renseigner. API Root URL attend l'adresse du serveur KoBoToolbox sur lequel le compte a été créé : https://kf.kobotoolbox.org pour le serveur global, https://eu.kobotoolbox.org pour celui de l'Union européenne. API Token reçoit la chaîne affichée dans les Account Settings de ce même compte. Tu crées le credential une fois depuis le menu Credentials de n8n, et le nœud comme le trigger le retrouvent ensuite dans leur liste déroulante. Pas d'écran OAuth, pas d'application à déclarer, pas de liste de scopes à cocher.
    03Quelles sont les limites du nœud KoBoToolbox ?
    Deux choses à anticiper. La pagination d'abord : sur les opérations de liste, Return All enchaîne les pages de l'API jusqu'au bout, et le laisser décoché signifie que le nœud s'arrête à Limit. Un export tronqué ressemble exactement à un export complet, et c'est comme ça qu'un trou dans les données passe inaperçu. La couverture ensuite : le nœud expose 17 opérations sur 4 ressources, et quand l'endpoint dont tu as besoin sort de ce catalogue, le nœud HTTP Request appelle l'API KoBoToolbox directement en réutilisant ce même credential via l'authentification prédéfinie. Le workflow continue, avec un nœud générique de plus dans la chaîne.
    04Le KoBoToolbox Trigger réagit-il en temps réel ?
    Oui. Le mécanisme est un webhook, c'est-à-dire une URL que KoBoToolbox appelle au moment où une soumission arrive : le workflow démarre en quelques secondes et non selon un calendrier. Aucun intervalle d'interrogation à régler, aucun délai à accepter. Le nœud trigger gère lui-même la création et la suppression du hook quand tu actives ou désactives le workflow, donc rien à paramétrer à la main dans KoBoToolbox. Il lit la soumission comme le fait l'opération Get a submission, avec les mêmes options de reformatage et de pièces jointes.
    05n8n ou Make pour KoBoToolbox ?
    Ça dépend de trois critères, et les deux outils se défendent. L'hébergement : Make est une plateforme hébergée, sans option d'auto-hébergement, quand n8n tourne sur ton propre serveur ou sur n8n Cloud, ce qui compte quand des données de terrain ne doivent pas quitter un territoire donné. Le modèle de coût : Make facture à l'opération, donc un workflow qui boucle sur des milliers de soumissions n'a pas la même forme là-bas. La logique visuelle : les deux dessinent le flux sur un canvas, avec des habitudes différentes sur les branches et le code. Pour KoBoToolbox, le point de départ reste les mêmes 17 opérations et le même webhook de soumission.
    Même plateforme

    Autres docs utiles sur ce stack.

    Voir toutes les intégrations