5.7.1 Gérer des données externes

TABLE DES MATIÈRES

• Qu’est-ce qu’une donnée externe ?
• Importation de données externes
  • Focus outils: Etapes pour importer des données externes dans votre projet KoBoToolbox project
• 3 façons différentes d’intégrer des données externes
  • Configurer la fontion “pulldata” dans votre XLSForm
  • Filtrer une liste par la fonction de recherche
  • Sans utiliser un csv : travailler avec un fichier XML

---

Qu’est-ce qu’une donnée externe ?

Les données externes sont des données qui ne sont pas directement incluses dans la conception de l’enquête mais qui sont injectées dans l’ensemble de données. L’importation et la gestion de données externes peuvent être utiles pour intégrer dans la base de données des informations déjà existantes sans avoir besoin de les demander à nouveau, et utiliser également des bases de données existantes pour des enquêtes de suivi ou en cas de longues listes à intégrer dans le formulaire de collecte des données mobiles (Mobile Data Collection - MDC). En outre, comme les listes de données externes sont souvent caractérisées par leur longeur ce tutoriel traite egalement de la fonction de recherche dans une liste.

Importation de données externes

L’importation de données externes en .csv (valeurs séparées par des virgules) peut être utile pour:

• Mettre à jour facilement une liste sans avoir à créer une nouvelle version du XLSForm à chaque fois (c.-à-d. faciliter la gestion des versions des formulaires)
• Faciliter l’intégration de certaines informations de base de données déjà connues, sans le demander à nouveau

L’importation de données externes est par exemple utile lorsqu’il s’agit d’utiliser une longue liste de lieux (par exemple, la liste complète des villages avec leurs informations sur les districts et les provinces), ou des données provenant d’une enquête précédente (par exemple, les données d’enregistrement avec l’identification dans un formulaire de suivi, etc.).

L’utilisation de données externes présente cependant les inconvénients suivants :

• Nécessite une grande rigueur dans la gestion des fichiers lorsque le csv doit être mis à jour régulièrement (par exemple en cas de suivi) : nommage correct des fichiers, pas d’effacement des données précédentes… ainsi qu’une rigueur dans la gestion des formulaires sur les appareils (nécessite une resynchronisation du formulaire sur tous les appareils à chaque fois qu’un csv est modifié).
• Difficile à utiliser pour des formulaires multi-langues car les données stockées dans le csv n’utilisent pas la fonctionnalité “::language” de XLSForm et ne sont donc généralement disponibles que dans une seule langue.
• L’utilisation de csv externes n’est pas compatible avec la version web du formulaire “Enketo” et ne peut être utilisée que sur des appareils mobiles.

Base de données avec les valeurs séparées par des virgules (.csv)

Focus outils: Etapes pour importer des données externes dans votre projet KoBoToolbox project

Pour importer des données externes, vous devez :

1. Créez une base de données Excel avec les données que vous souhaitez inclure (base de données simple avec en-tête avec un nom UNIQUE pour chaque colonne, pas de cellules fusionnées, etc.) Chaque fichier csv doit contenir au moins une colonne qui peut être utilisée pour identifier de manière unique chaque ligne.
2. Convertissez votre fichier Excel en un fichier .csv (comma separated value) dans Excel**{: .text-blue-dark }, avec les données que vous souhaitez inclure.

   Faites attention, à sélectionner le format “CSV UTF-8” (et non un autre format de csv) lors de la conversion d’un fichier Excel. Certaines langues n’utilisant pas les caractères latins peuvent en outre ne pas être compatibles avec l’utilisation d’un csv externe. Si votre Windows, Office ou Excel est configuré en français, le csv généré par Excel ne sera pas séparé par une virgule mais par un point-virgule qui n’est pas compatible avec KoBoToolbox. Dans ce cas, vous devez soit :

   • Changer vos séparateurs dans Excel ici
   • Changer la langue de votre Excel en anglais (changement automatique du séparateur)
   • Utiliser une alternative à Excel telle que LibreOfficeCalc pour convertir votre csv avec virgule
   • Utiliser un convertisseur en ligne tel que celui-ci Si vous exportez directement depuis KoBoToolbox les données avec le format csv (télécharger les données / type d’exportation csv), les données exportées ne peuvent PAS être réimportées automatiquement car le csv généré utilise le point-virgule au lieu de la virgule. Il est conseillé d’exporter dans Excel et de le convertir ensuite en csv.

   </div>

3. Ajoutez le fichier .csv dans la section dédiée dans les paramètres de votre formulaire (dans KoBoToolbox, cherchez “ ajouter un document “).
4. Dans votre formulaire, ajoutez :
   • [Facultatif] une question de type “select one” avec aspect de recherche pour sélectionner dans la liste csv externe le bon enregistrement (voir ci-dessous).
   • des questions de type “calculer” pour chaque information que vous souhaitez récupérer dans votre base de données externe, et utiliser la fonction “pulldata” (voir ci-dessous).
   • Si nécessaire, une question de type “note” ou “acquittement” pour afficher les résultats (sinon l’information ne sera pas visible pour l’enquêteur).

3 façons différentes d’intégrer des données externes

Comme nous l’avons expliqué, l’utilisation d’un fichier externe en tant que pièce jointe à votre formulaire peut s’avérer très utile lorsque vous travaillez avec un grand ensemble de données ou que vous souhaitez lier votre formulaire à une autre base de données, car cela peut à la fois améliorer les performances et permettre de mettre à jour une liste d’options sans devoir télécharger une nouvelle version du formulaire. Pour gérer les données externes, vous avez plusieurs options : voici un récapitulatif de quand utiliser chacune d’entre elles.

La première partie ci-dessous détaille comment la fonction pulldata() fonctionne avec un csv externe. Malheureusement, comme le montre le tableau ci-dessus, l’utilisation d’une telle fonction n’est pas toujours possible en fonction de ce que vous souhaitez faire.

Configurer la fontion “pulldata” dans votre XLSForm

La structure générale de cette expression est :

• pulldata(‘nom du fichier attaché’, ‘nom de la colonne à extraire dans le fichier attaché’, ‘identifiant unique de la colonne dans le fichier attaché’, variable de correspondance’)

Un exemple de requête pour une enquête de suivi est:

• pulldata (‘preLoad’, ‘age’, ‘id_key’, ${unique_id})
  • preLoad est le nom du fichier csv contenant la base de données
  • age est le nom de la colonne du fichier csv que nous voulons récupérer
  • id_key est le titre de la colonne du fichier csv qui contient l’identifiant unique des enregistrements cibles
  • ${unique_id} est le nom de la variable, dans l’enquête de suivi, qui contient l’identifiant unique que nous recherchons (par exemple, notre bénéficiaire actuel)

Le nom de la base de données, renommé “preLoad”

Le fichier “preLoad” contient une colonne id_key (avec l’identifiant unique pour chaque bénéficiaire de notre programme) ainsi qu’une colonne “age” (qui est la valeur que nous désirons afficher sur le téléphone pendant le suivi)

Le formulaire de suivi associé XLSForm : La question “unique_id” dans l’enquête de suivi est celle où les enquêteurs indiquent quel bénéficiaire répond

En utilisant ce qui précède comme exemple, si l’id unique indiqué par l’enquêteur était idaho-3-31, alors la valeur retournée sur le téléphone sera 3.

Filtrer une liste par la fonction de recherche

L’utilisation de la fonction pulldata() présente plusieurs limites. Elle ne peut extraire les données que d’une seule colonne de votre fichier csv et si plusieurs lignes correspondent à vos critères pulldata(), elle n’extraira que la première. La fonction de recherche permet une plus grande flexibilité dans le filtrage des données csv et peut également renvoyer plusieurs valeurs correspondantes, ce qui est utile, par exemple, pour alimenter une liste de choix dynamique pour une question select_one ou select_multiple. La fonction de recherche est utile lorsque vous disposez d’une longue liste d’éléments (qu’il s’agisse de noms, d’entités administratives, etc.) et que vous souhaitez les sélectionner.

Nous ajoutons généralement à la fonction de recherche la fonction d’apparence d’autocomplétion à la recherche (filtre basé sur le texte que vous commencez à saisir). Pour la question concernée, elle permettra au répondant de taper les premières lettres de sa réponse et affichera une liste filtrée en fonction du texte qui a été tapé. La fonction d’autocomplétion fonctionne à la fois sur Enketo et sur ODK Collect.

Dans l’onglet “survey” du XLSForm :

Écran d’ODK Collect avec apparition de l’autocomplétion

Cette fonctionnalité pourrait fonctionner pour les questions “select_one” ou “select_multiple”.

Pour utiliser une fonction de recherche dans la liste .csv téléchargée, il est important d’adapter la syntaxe XLS suivante dans la colonne “appearence” : autocomplete search(‘preLoad’). Le nom de la liste devrait alors avoir le même nom que la colonne dans le csv pour laquelle vous voulez filtrer les données.

XLSForm (Survey Tab)

XLSForm (Choice tab)

csv preLoad.csv

La première façon de l’utiliser est assez simple : par exemple, vous pouvez rechercher (‘Jean’) et il extraira toutes les données de la liste (fichier csv) appelée “Jean”. Il suffit de mettre le nom du fichier csv dans l’onglet choix.

Plus complexe : Une fonction de recherche dans la liste .csv téléchargée peut être mise en place - pour cela, il est important d’adapter la syntaxe XLS suivante dans la colonne “apparence”: autocomplete search{‘preLoad’,’matches’,’regionid’,${region}}:

• “preload” est le nom du fichier csv qui a été importé
• “regionid” est le filtre sur lequel la fonction de recherche est basée (souvent le nom de la colonne dans laquelle vous voulez que les valeurs soient prises)
• ${region} est le nom de la variable à laquelle “regionid” doit correspondre dans le XLSForm

Rappelez-vous que la fonction de recherche ne fonctionne que si votre liste de données est dans un csv externe ! Les champs de données extraits d’un fichier .csv sont considérés comme des chaînes de texte. Utilisez donc les fonctions int() ou number() pour convertir un champ préchargé au format numérique.

Vous pouvez également la configurer d’une manière plus avancée. Pour cela, cette fonction doit être combinée avec des options telles que :

• startswith
• endswith
• contains
• matches

Cela vous permettra d’inclure (dans la recherche) toutes les lignes ayant une correspondance dans une colonne spécifiée.

Par exemple: search(‘externalCSV’,’startswith’,’location’,${city})

• le premier paramètre (“externalCSV”) est le nom de votre fichier csv
• le deuxième paramètre est la fonction que vous voulez utiliser pour le rechercher : ici la fonction va regarder le début des mots
• le troisième paramètre spécifie le filtre sur lequel la fonction de recherche est basée (souvent le nom de la colonne dans laquelle vous voulez que les valeurs soient prises)
• le quatrième paramètre est le nom de la variable à laquelle le filtre doit correspondre.

Si vous voulez avoir un csv avec une langue différente, vous pouvez regarder cet article de blog (en anglais).

Sans utiliser un csv : travailler avec un fichier XML

Cette deuxième fonction est dédiée aux utilisateurs avancés. Il est possible d’utiliser des fichiers XML comme alternative aux fichiers CSV pour stocker des données externes auxquelles on peut se référer dans les calculs, les contraintes ou les pertinences. Cette méthode permet au créateur de formulaire de traiter des cas encore plus complexes que ceux vus avec les deux fonctions précédentes en utilisant la fonction instance(). Elle permet d’avoir des critères de filtrage plus avancés que la fonction search() présentée ci-dessus et aussi de travailler avec des métadonnées et des nœuds vraiment complexes (interdépendance entre plusieurs variables, existence de questions groupées dans un formulaire, etc. Vous avez plusieurs possibilités :

• Avoir une question select_one ou select_multiple où votre fichier XML contient la liste des choix. Vous devez spécifier le type de question : “xml-external” et l’instance de la fonction sera dans la feuille “choices”.
• Inclure les données de votre fichier XML dans d’autres formules : calcul, contrainte, pertinent ou encore choice_filter.

Pour coder correctement cette fonction, veuillez suivre les instructions ici.

Par exemple dans un XLSForm :

Ce que signifie la formule :

• votre fichier XML s’appelle: “site_list”
• les données vont être prises dans la colonne “provincename”
• les données de cette colonne ne seront affichées que si les valeurs correspondent aux valeurs spécifiques de la colonne “nom”, la valeur spécifique étant la réponse à la question “site” dans le XLSForm.
• /root/item/ est le chemin dans le fichier XML pour obtenir les données