Guide du kit de configuration de campagne IASO

Ce kit permet à un assistant IA (Claude, ChatGPT…) de configurer, dans un compte IASO, tout ce qu'il faut pour une campagne de distribution de masse de moustiquaires imprégnées d'insecticide (MII) : les applications mobiles des agents, les formulaires, les registres de ménages et de travailleurs, le stock, les utilisateurs, les tableaux de bord et les rapports pour le terrain.

Vous importez le kit dans l'assistant et lui demandez de suivre ses instructions. Il vous pose les questions de la campagne, crée la configuration par l'API d'IASO et la vérifie, en vous demandant votre accord avant chaque écriture.

IASO est une plateforme open source de collecte de données sur mobile, de gestion de registres et de suivi de campagnes, développée par Bluesquare.

Ce guide présente :

1. le résultat : ce que vous obtenez à la fin ;
2. comment utiliser le zip ;
3. la campagne configurée, phase par phase ;
4. les concepts d'IASO utiles pour comprendre et faire évoluer la configuration.

Les captures d'écran viennent d'un compte de démonstration configuré avec ce kit (pyramide « Pays démo », campagne « MII 2027 », données fictives).

1. Le résultat : ce que le kit produit

Les applications mobiles (projets)

Chaque rôle de la campagne a son application : un projet IASO, que le téléphone charge par son identifiant (app_id). Jusqu'à six projets :

Chaque projet a ses options (feature flags) : authentification obligatoire, entités, point GPS sur chaque formulaire, synchronisation en zip, rapports mobiles, stock…

Sur le téléphone

L'agent installe l'application IASO, la configure pour son projet (QR code, ou serveur et app_id saisis à la main), se connecte, et l'application télécharge tout ce dont il a besoin.

Configuration

Première synchronisation

Accueil de l'application Dénombrement

L'agent retrouve un ménage, voit ses informations, et l'application lui propose le formulaire de suivi prévu par le workflow ; le formulaire reprend les valeurs du ménage.

Recherche des ménages

Un ménage

Formulaire de suivi proposé

Distribution : valeurs du ménage

Scan de chaque moustiquaire

Les formulaires

Quinze formulaires XLSForm, avec des libellés en anglais et en français (la langue se choisit dans l'application), validés avant le téléversement et rattachés aux projets qui les utilisent.

Les entités et les workflows

Les ménages, les ménages absents ou en refus, les ménages servis en routine, les groupements spéciaux et les travailleurs sont des entités : des registres que les agents retrouvent sur le téléphone. Les workflows décident quels formulaires de suivi l'application propose sur chacun (par exemple la distribution, une seule fois par ménage).

Le stock

Une unité de stock « Moustiquaires (pièces) » et une règle par mouvement : l'application calcule le solde de chaque entrepôt à partir des réceptions, sorties, retours, transferts et pertes.

Les utilisateurs

Un compte par agent, avec ses applications, sa zone de travail et ses permissions.

Les QR codes

Dès que les projets sont créés, l'assistant présente dans la conversation un QR code pour installer l'application IASO et un QR code par projet pour la configurer. Ils sont aussi réunis dans une page qr_codes/qr_codes.html à imprimer pour la formation.

Les tableaux de bord web

Des pages publiées dans IASO, ouvertes dans un navigateur par l'équipe de coordination :

• Tableau de bord de la campagne : ménages dénombrés, servis en routine, absents et refus, MII nécessaires et distribuées, par région, district ou formation sanitaire, sur une période ;
• Présence et paiement des travailleurs : calendrier des journées déclarées et validées, montant dû à chacun selon son rôle, état de paiement Excel avec formules.

Les rapports mobiles

Des rapports qui s'ouvrent dans l'application, hors ligne, sur les données du téléphone. Un rapport par application ; par défaut :

La carte affiche le fond de carte de Bluesquare (martin.bluesquare.org) quand le téléphone a du réseau ; sans réseau, les ménages et les noms des lieux restent affichés sur un fond uni. L'assistant vous demande au début si vous voulez la carte, les noms des lieux et ce fond de carte.

Avancement, dans l'application	Carte des ménages (démonstration)
Présence de l'équipe (démonstration)	Stock (démonstration)

L'assistant les publie lui-même par l'API d'IASO : chaque envoi crée une nouvelle version du rapport du projet, et l'on peut revenir à une version précédente si la nouvelle pose problème. Les téléphones reçoivent la version publiée à leur synchronisation suivante. On voit et on gère aussi ces versions dans IASO, onglet Rapport mobile du projet (voir § 4).

La pyramide sanitaire

Si le compte n'en a pas encore, l'assistant vous demande d'où viennent vos unités d'organisation (pays, régions, districts, formations sanitaires, villages) et les importe dans IASO :

• depuis votre DHIS2 : toutes les unités, à tous les niveaux, avec leurs identifiants DHIS2, codes, coordonnées et contours. Vous saisissez vous-même l'adresse, le login et le mot de passe DHIS2 sur la source de données du compte dans IASO ; l'assistant ne les voit jamais ;
• depuis un fichier Excel que vous remplissez à partir du modèle fourni (une ligne par village ou formation sanitaire, une colonne par niveau, coordonnées GPS et codes facultatifs). L'assistant vérifie le fichier, le convertit en GeoPackage, le format d'import d'IASO, et l'importe ; réimporter le fichier corrigé met à jour les unités sans les dupliquer ;
• depuis un GeoPackage déjà au format IASO, par exemple avec les contours des districts ;
• ou une pyramide de démonstration, pour essayer.

2. Utiliser le zip

Le zip n'est pas un logiciel à installer. C'est un ensemble d'instructions (SKILL.md), de références, de formulaires, de modèles et de scripts écrits pour un assistant IA. Vous le donnez à l'assistant, vous lui demandez de suivre ses instructions, et c'est lui qui vous guide, étape par étape, dans la création des outils de suivi de votre campagne.

Ce qu'il vous faut

Étape 1 : mettre votre jeton dans le kit

1. Décompressez le zip.
2. Ouvrez <adresse IASO>/login/?next=/api/apitoken/ (par exemple https://demo.openiaso.com/login/?next=/api/apitoken/) et connectez-vous avec l'utilisateur de configuration : IASO affiche un jeton (token).
3. Ouvrez iaso_config.txt, à la racine du kit. Vérifiez IASO_URL (l'adresse de votre serveur), collez le jeton après IASO_TOKEN= et enregistrez.
4. Si vous utilisez l'assistant dans un navigateur ou dans son application, recompressez le dossier du kit en zip.

Le jeton donne accès à IASO avec les droits de l'utilisateur de configuration. Ne le collez jamais dans la conversation, et ne partagez pas ce zip.

Étape 2 : préparer la pyramide (si le compte n'en a pas)

Décidez d'où viennent vos unités d'organisation (régions, districts, formations sanitaires, villages) :

• DHIS2 : dans IASO, Admin > Sources de données > Liste des sources de données, modifiez la source du compte (roue dentée), remplissez le nom, l'URL, le login et le mot de passe DHIS2, cliquez sur Vérifier la configuration, puis sur Sauver. L'assistant ne voit jamais ce mot de passe.
• Un fichier Excel : remplissez templates/pyramide_modele.xlsx (une ligne par village ou formation sanitaire, une colonne par niveau) et ajoutez-le au kit, ou à la conversation.
• Un GeoPackage au format IASO : ajoutez-le au kit, ou à la conversation.

Étape 3 : donner le kit à l'assistant

• Claude ou ChatGPT, dans le navigateur ou l'application : ouvrez une nouvelle conversation et importez le zip (bouton pour joindre un fichier).
• Claude Code, ou un autre assistant qui travaille sur votre ordinateur : ouvrez-le dans le dossier du kit.

Puis envoyez ce message :

Voici un kit pour configurer une campagne de distribution de moustiquaires dans IASO. Décompresse-le si besoin, lis SKILL.md, reference/pitfalls.md et reference/architecture.md, puis suis les instructions de SKILL.md étape par étape pour me guider dans la création des outils de suivi de ma campagne. N'utilise que les scripts du kit (scripts/iaso.py), aucun connecteur IASO. Commence par vérifier l'accès et faire une sauvegarde, puis pose-moi les questions de templates/campaign.yaml une section à la fois, y compris les décisions du § 2b (rapports mobiles par application, carte, pages web et qui y a accès, utilisateurs de test). Montre-moi les QR codes dès que les projets existent. Demande-moi confirmation avant chaque étape qui écrit dans IASO. Ne t'arrête qu'après la liste du § 12c (pages web et rapports mobiles publiés compris), et dis-moi à la fin ce que tu as créé et ce que je dois tester sur un téléphone.

Dans un navigateur, l'assistant travaille dans son propre espace : demandez-lui de vous donner en téléchargement les fichiers qu'il produit pour vous (QR codes, fichier des mots de passe, sauvegarde).

Étape 4 : répondre aux questions

L'assistant avance une section à la fois. Avoir ces informations sous la main évite les allers-retours :

IASO refuse les mots de passe de moins de 8 caractères, trop courants (test, password…), uniquement numériques ou proches du nom d'utilisateur. L'assistant génère des mots de passe aléatoires et les écrit dans un fichier, jamais dans la conversation.

Étape 5 : suivre la configuration

L'assistant annonce chaque étape et attend votre accord avant d'écrire dans IASO :

1. vérification de l'accès et sauvegarde du compte ;
2. import de la pyramide ;
3. création des projets, puis affichage des QR codes dans la conversation : vous pouvez déjà installer l'application sur un téléphone de test ;
4. formulaires, types d'entités et workflows ;
5. stock ;
6. utilisateurs et utilisateurs de test ;
7. pages web, publiées pour les personnes convenues ;
8. rapports mobiles de chaque application ;
9. récapitulatif : ce qui a été créé, ce qui reste à faire, ce qu'il faut tester.

La configuration n'est terminée que lorsque tout ce qui a été décidé à l'étape 4 est fait (SKILL.md § 12c). Si l'assistant s'arrête plus tôt, demandez-lui de reprendre la liste.

Étape 6 : tester sur un téléphone

1. Scannez le QR code du Play Store pour installer IASO, puis, dans l'application, le QR code du projet.
2. Connectez-vous avec un utilisateur de test et suivez la liste de vérification que l'assistant vous donne (SKILL.md § 11) : enregistrer un ménage, le retrouver, distribuer, enregistrer un travailleur, un mouvement de stock.
3. Ouvrez les rapports mobiles avec du réseau, puis en mode avion.
4. Avant le lancement, faites supprimer les données et les utilisateurs de test.

Pendant la campagne

Pour modifier la configuration (une question, une liste de choix, un nouveau district, un rapport), revenez vers l'assistant avec le kit : il relit reference/pitfalls.md, car modifier un formulaire déjà utilisé par les téléphones demande plus de précautions que le créer. À la fin de la configuration, désactivez l'utilisateur de configuration, ou retirez-lui ses permissions d'écriture.

Le README.md du kit détaille chaque étape.

3. La campagne configurée, phase par phase

Une campagne de distribution de MII se déroule en quelques phases successives. Le kit fournit, pour chacune, l'application des agents, ses formulaires et ce qui permet de la suivre.

La présence des travailleurs (formulaire 09) court sur toute la campagne, de la formation à la fin de la distribution.

1. Préparation

Objectif : que chaque agent ait un compte, un téléphone configuré et sa zone de travail, et que chaque travailleur soit enregistré avant le premier jour payé.

• Pyramide et zones. Les unités d'organisation sont importées (DHIS2, Excel ou GeoPackage). Chaque utilisateur est rattaché à sa zone : l'application ne télécharge que ce sous-arbre.
• Comptes. Un compte par agent (jamais de compte partagé), rattaché à ses applications. Les utilisateurs des applications avec des registres reçoivent la permission « Entités ».
• Téléphones. Lors de la formation, chaque agent installe IASO et scanne le QR code de son application ; il se connecte et fait une première synchronisation.
• Enregistrement des travailleurs (formulaire 08, application Travailleurs et présence) : le chef d'équipe enregistre chaque travailleur (nom, sexe, rôle, téléphone de mobile money, pièce d'identité, photo). Le téléphone prévient si la pièce d'identité est déjà enregistrée.
• Présence (formulaire 09) : chaque jour de formation ou de terrain, le chef d'équipe ouvre le travailleur et déclare la journée ; le superviseur la valide le soir, avec sa signature.

Ce que l'on suit : le rapport mobile Présence de l'équipe montre au chef d'équipe qui est validé, à valider ou pas encore saisi aujourd'hui ; la page Présence et paiement donne la vue d'ensemble.

À surveiller : les journées déclarées mais non validées ne seront pas payées ; un travailleur enregistré deux fois.

2. Dénombrement

Objectif : enregistrer chaque ménage de la zone et calculer les MII dont il a besoin.

Application Dénombrement, agents de dénombrement, en porte à porte :

1. L'agent remet un ticket QR au ménage et le scanne : c'est l'identifiant du ménage, que l'on retrouvera à la distribution. Le même ticket ne peut pas être enregistré deux fois.
2. Il enregistre le chef de ménage (nom, âge, pièce d'identité, téléphone), le nombre de personnes et d'espaces de couchage, et la position GPS. Le téléphone calcule les MII nécessaires selon la règle d'allocation de la campagne, et affiche un récapitulatif à vérifier avant d'enregistrer.
3. Ménage absent ou qui refuse (formulaire 03) : seule sa position est enregistrée, avec un code court à écrire sur la porte. Une revisite (formulaire 04) est proposée tant qu'il n'est pas dénombré.
4. Ménage déjà servi par la distribution de routine (formulaire 05) : il est compté, avec les MII déjà reçues, sans recevoir de ticket.

Ce que l'on suit : ménages dénombrés, MII nécessaires, absents et refus à revisiter, par formation sanitaire ; la carte des ménages dans le rapport mobile Avancement montre les zones déjà couvertes.

À surveiller : les absents et refus non revisités ; un écart entre les ménages dénombrés et la population attendue ; les téléphones qui ne synchronisent pas.

3. Logistique et stock

Objectif : savoir à tout moment combien de MII se trouvent dans chaque magasin, et où elles sont parties.

Application Stock, magasiniers des districts et des formations sanitaires :

Les quantités se saisissent en ballots et en pièces ; l'application calcule le total et affiche le solde du magasin après chaque mouvement.

Ce que l'on suit : le rapport mobile Stock (solde, totaux par mouvement, derniers mouvements) pour le magasinier.

À surveiller : un solde négatif ou qui ne correspond pas au comptage physique ; des sorties sans retour en fin de journée.

4. Distribution

Objectif : remettre à chaque ménage dénombré les MII calculées, une seule fois, et en garder la trace moustiquaire par moustiquaire.

• Aux ménages (application Distribution, formulaire 02) : 1. l'agent retrouve le ménage en scannant son ticket, ou en le cherchant par nom ; 2. l'application affiche le chef de ménage, sa pièce d'identité et le nombre de MII à remettre ; 3. l'agent scanne le QR code de chaque moustiquaire remise. Le téléphone refuse une moustiquaire déjà scannée, et le ticket du ménage scanné à la place d'une moustiquaire.

Une fois la distribution enregistrée, elle n'est plus proposée pour ce ménage. L'application Distribution ne permet pas de créer de ménages : seuls les ménages dénombrés sont servis. - Aux groupements spéciaux (prisons, camps, internats…, formulaires 06 et 07) : l'équipe enregistre le groupement (type, effectif, MII prévues), puis la distribution, une seule fois, avec la signature du responsable.

Ce que l'on suit : ménages servis et MII distribuées par rapport aux ménages dénombrés et aux MII nécessaires ; la carte du rapport Avancement distingue les ménages servis des ménages restants.

À surveiller : les ménages dénombrés non servis en fin de distribution ; les moustiquaires non scannées (code illisible) ; l'écart entre les MII sorties du stock et les MII distribuées.

5. Supervision

Application Supervision, formulaire 15, rempli par les superviseurs lors de leurs visites : composition des équipes, présence validée, stock suffisant et conforme à l'application, téléphones et synchronisation, refus et revisites, points forts et points faibles, et pour chaque problème une action, son responsable et son échéance.

Ce que l'on suit : les fiches de supervision dans IASO, par zone et par date.

6. Paiement des travailleurs

La page Présence et paiement calcule, pour chaque travailleur, les journées validées et le montant dû selon les tarifs de son rôle (taux journalier, forfait payé une fois, plafond de jours, frais de mobile money), et produit un état de paiement Excel avec ses formules. Seules les personnes qui préparent les paiements y ont accès : elle affiche les numéros de téléphone et de pièce d'identité.

Le suivi au quotidien

4. Les concepts d'IASO

Compte et modules

Un compte IASO regroupe tout ce qui concerne une organisation ou une campagne : sa pyramide, ses projets, ses formulaires, ses utilisateurs. Ses modules activent des fonctions : la campagne a besoin de Data collection - Forms (formulaires), Entities (registres et workflows), Stock management (stock) et Embedded links (pages web).

Pyramide et types d'unités

La pyramide est l'arbre des unités d'organisation : pays, régions, districts, formations sanitaires, villages. Chaque niveau est un type d'unité. Les soumissions et les entités sont rattachées à une unité, et une application télécharge les types d'unités qui lui sont associés dans la zone de son utilisateur.

Les unités appartiennent à une source de données (par exemple « la pyramide du ministère ») et à une version de cette source. Le compte a une version par défaut : c'est la pyramide qu'utilisent les projets, les utilisateurs et les téléphones, et c'est là que le kit importe les unités, depuis DHIS2 ou depuis un GeoPackage. Les identifiants DHIS2 sont enregistrés sur la source de données.

Projets, applications et options

Un projet est ce que charge un téléphone : un app_id, ses formulaires, ses types d'unités et ses options (feature flags). Le même téléphone peut passer d'un projet à l'autre.

Formulaires et versions

Un formulaire est un XLSForm. Chaque téléversement crée une version ; les téléphones reçoivent la dernière à leur synchronisation. Les noms de champs ne changent pas d'une version à l'autre : les entités, workflows, règles de stock et tableaux de bord s'y réfèrent.

Chaque formulaire rempli est une soumission, consultable dans IASO :

Entités et types d'entités

Une entité est un objet suivi dans le temps : un ménage, un groupement, un travailleur. Son type d'entité définit son formulaire de référence (qui la crée), les champs affichés dans les listes et le détail, et la recherche de doublons (par exemple sur le QR code du ticket, avec blocage si le ticket existe déjà).

Workflows

Le workflow d'un type d'entité contient :

• des suivis : quel formulaire l'application propose sur l'entité, et à quelle condition (par exemple, la distribution tant qu'aucune MII n'a été distribuée) ;
• des changements (changes) : quelles réponses du formulaire de suivi mettent à jour l'entité (par exemple, les MII remises deviennent les MII distribuées du ménage, ce qui ferme la distribution).

Un workflow se modifie dans une nouvelle version, publiée ensuite.

Stock

Une unité de gestion de stock (SKU) décrit ce qu'on compte (ici les moustiquaires, en pièces), dans quels projets et à quels niveaux. Une version de règles dit, pour chaque formulaire de stock, quelle question ajoute ou retire du solde. L'application applique ces règles aux formulaires remplis sur le téléphone.

Utilisateurs et permissions

Un utilisateur a des projets (les applications qu'il peut ouvrir), des unités d'organisation (sa zone : l'application ne télécharge que ce sous-arbre) et des permissions. Pour les applications qui ont des entités, la permission Entités (iaso_entities) est indispensable : sans elle, l'application ne télécharge ni n'affiche les ménages, groupements ou travailleurs.

Pages web

Une page est un document HTML publié dans IASO à l'adresse <adresse IASO>/pages/<nom>/, visible seulement par les utilisateurs choisis. Les pages du kit lisent les soumissions par l'API, avec la session de l'utilisateur connecté.

Rapports mobiles

Un rapport mobile est un zip (avec un index.html à la racine) que l'application télécharge et ouvre hors ligne quand le projet a l'option « Activer les rapports ». Il lit les données du téléphone par un pont JavaScript. Tout ce qu'il utilise doit être dans le zip (la bibliothèque de carte MapLibre, par exemple) : seul le fond de carte se charge par internet, quand il y a du réseau. Chaque projet a un rapport ; chaque nouvel envoi crée une version, et la version publiée est celle que reçoivent les téléphones. On le publie par l'API (scripts/iaso.py mobile-report-upload) ou dans l'onglet Rapport mobile du projet.

Application mobile

Tout le monde utilise l'application générique IASO du Play Store (Bluesquare). Au premier lancement, on scanne le QR code du projet (ou on saisit l'adresse du serveur et l'app_id), puis on se connecte. À chaque synchronisation, l'application envoie ses soumissions et reçoit les formulaires, la zone, les entités, les workflows, le stock et le rapport mobile.

IASO est une plateforme open source développée par Bluesquare : bluesquarehub.com · code source : github.com/BLSQ/iaso