IASO campaign setup kit — guide

This kit lets an AI assistant (Claude, ChatGPT…) set up, in an IASO account, everything a mass distribution campaign of insecticide-treated nets (ITNs) needs: the agents' mobile apps, the forms, the household and worker registries, the stock, the users, the dashboards and the reports for the field.

You import the kit into the assistant and ask it to follow its instructions. It asks you the campaign questions, creates the setup through the IASO API and checks it, asking for your go-ahead before each write.

IASO is an open source platform for mobile data collection, registries and campaign monitoring, developed by Bluesquare.

This guide covers:

1. the result: what you get at the end;
2. how to use the zip;
3. the campaign that is set up, phase by phase;
4. the IASO concepts needed to understand and change the setup.

The screenshots come from a demo account set up with this kit (pyramid "Pays démo", campaign "MII 2027", made-up data). That demo campaign was set up in French: project, form and place names appear in French, the IASO interface in English.

1. The result: what the kit produces

Mobile apps (projects)

Each campaign role gets its app: an IASO project, which the phone loads by its identifier (app_id). Up to six projects:

Each project has its feature flags: mandatory login, entities, GPS point on each form, zip synchronisation, mobile reports, stock…

On the phone

The agent installs the IASO app, sets it up for their project (QR code, or server and app_id typed in), logs in, and the app downloads everything they need.

First synchronisation

Home of the Enumeration app

Household search

The agent finds a household, sees its details, and the app offers the follow-up form set by the workflow; the form gets the household's values.

A household

Follow-up form offered

Distribution: household values

Forms

Fifteen XLSForms, with English and French labels (the language is chosen in the app), checked before upload and attached to the projects that use them.

Entities and workflows

Households, absent or refusing households, households served by routine distribution, special groups and workers are entities: registries the agents find again on the phone. Workflows decide which follow-up forms the app offers on each of them (for example the distribution, once per household).

Stock

A stock keeping unit "nets (pieces)" and one rule per movement: the app computes the balance of each store from receipts, issues, returns, transfers and losses.

Users

One account per agent, with their apps, their working area and their permissions.

QR codes

As soon as the projects are created, the assistant shows in the conversation a QR code to install the IASO app and one QR code per project to set it up. They are also gathered in a qr_codes/qr_codes.html page to print for the training.

Web dashboards

Pages published in IASO, opened in a browser by the coordination team:

• Campaign dashboard: households enumerated, served by routine, absent and refusing, nets needed and given, by region, district or health facility, over a period;
• Worker attendance and payment: calendar of declared and validated days, amount due to each worker according to their role, Excel payment sheet with formulas.

Mobile reports

Reports that open in the app, offline, on the phone's data. One report per app; by default:

The map shows Bluesquare's base map (martin.bluesquare.org) when the phone has a network; without network, the households and the place names still show on a plain background. The assistant asks you at the start whether you want the map, the place names and this base map.

Progress, in the app	Map of households (demo)
Team attendance (demo)	Stock (demo)

The assistant publishes them itself through the IASO API: each upload creates a new version of the project's report, and an earlier version can be published again if the new one is wrong. Phones get the published version at their next synchronisation. The versions can also be seen and managed in IASO, in the project's Mobile report tab (see § 4).

Health pyramid

If the account does not have one yet, the assistant asks where your org units (country, regions, districts, health facilities, villages) come from and imports them into IASO:

• from your DHIS2: every unit, at every level, with its DHIS2 id, code, coordinates and boundaries. You enter the DHIS2 address, login and password yourself on the account's data source in IASO; the assistant never sees them;
• from an Excel file you fill in from the template provided (one row per village or health facility, one column per level, optional GPS coordinates and codes). The assistant checks the file, converts it to a GeoPackage, IASO's import format, and imports it; importing the fixed file again updates the units without duplicating them;
• from a GeoPackage already in the IASO format, for example with district boundaries;
• or a demo pyramid, to try things out.

2. Using the zip

The zip is not software to install. It is a set of instructions (SKILL.md), references, forms, templates and scripts written for an AI assistant. You give it to the assistant, you ask it to follow its instructions, and the assistant guides you, step by step, through building the monitoring tools of your campaign.

What you need

Step 1: put your token in the kit

1. Unzip the zip.
2. Open <IASO address>/login/?next=/api/apitoken/ (for example https://demo.openiaso.com/login/?next=/api/apitoken/) and log in with the setup user: IASO shows a token (token).
3. Open iaso_config.txt, at the root of the kit. Check IASO_URL (the address of your server), paste the token after IASO_TOKEN= and save.
4. If you use the assistant in a browser or in its app, zip the kit folder again.

The token gives access to IASO with the rights of the setup user. Never paste it in the conversation, and do not share this zip.

Step 2: prepare the pyramid (if the account has none)

Decide where your org units (regions, districts, health facilities, villages) come from:

• DHIS2: in IASO, Admin > Data Sources > Data Sources list, edit the account's source (gear icon), fill in the DHIS2 name, URL, login and password, click Test settings, then Save. The assistant never sees this password.
• An Excel file: fill in templates/pyramid_template.xlsx (one row per village or health facility, one column per level) and add it to the kit, or to the conversation.
• A GeoPackage in the IASO format: add it to the kit, or to the conversation.

Step 3: give the kit to the assistant

• Claude or ChatGPT, in the browser or the app: start a new conversation and import the zip (attach file button).
• Claude Code, or another assistant working on your computer: open it in the kit folder.

Then send this message:

Here is a kit to set up a net distribution campaign in IASO. Unzip it if needed, read SKILL.md, reference/pitfalls.md and reference/architecture.md, then follow the instructions of SKILL.md step by step to guide me through building the monitoring tools of my campaign. Use only the kit's scripts (scripts/iaso.py), no IASO connector. Start by checking access and making a backup, then ask me the questions of templates/campaign.yaml one section at a time, including the decisions of § 2b (mobile report per app, map, web pages and who can open them, test users). Show me the QR codes as soon as the projects exist. Confirm with me before each step that writes to IASO. Do not stop before the checklist of § 12c (web pages and mobile reports published included), and tell me at the end what you created and what I must test on a phone.

In a browser, the assistant works in its own space: ask it to give you, as downloads, the files it produces for you (QR codes, password file, backup).

Step 4: answer the questions

The assistant goes one section at a time. Having this information at hand avoids back and forth:

IASO refuses passwords shorter than 8 characters, too common (test, password…), entirely numeric or close to the username. The assistant generates random passwords and writes them to a file, never in the conversation.

Step 5: follow the setup

The assistant announces each step and waits for your go-ahead before writing to IASO:

1. access check and backup of the account;
2. pyramid import;
3. projects, then the QR codes shown in the conversation: you can already install the app on a test phone;
4. forms, entity types and workflows;
5. stock;
6. users and test users;
7. web pages, published for the agreed people;
8. mobile reports of each app;
9. summary: what was created, what is left, what to test.

The setup is only finished when everything decided in step 4 is done (SKILL.md § 12c). If the assistant stops earlier, ask it to go back to the checklist.

Step 6: test on a phone

1. Scan the Play Store QR code to install IASO, then, in the app, the project's QR code.
2. Log in with a test user and follow the checklist the assistant gives you (SKILL.md § 11): register a household, find it again, distribute, register a worker, a stock movement.
3. Open the mobile reports with network, then in airplane mode.
4. Before launch, have the test data and test users deleted.

During the campaign

To change the setup (a question, a choice list, a new district, a report), come back to the assistant with the kit: it rereads reference/pitfalls.md, because changing a form that phones already use takes more care than creating it. At the end of the setup, deactivate the setup user, or remove its write permissions.

The kit's README.md details each step.

3. The campaign, phase by phase

A net distribution campaign runs in a few successive phases. For each one, the kit provides the agents' app, its forms and what is needed to follow it.

Worker attendance (form 09) runs through the whole campaign, from the training to the end of the distribution.

1. Preparation

Goal: every agent has an account, a configured phone and their work area, and every worker is registered before the first paid day.

• Pyramid and areas. The org units are imported (DHIS2, Excel or GeoPackage). Each user is attached to their area: the app only downloads that sub-tree.
• Accounts. One account per agent (never a shared account), attached to their apps. Users of the apps with registries get the "Entities" permission.
• Phones. During the training, each agent installs IASO and scans the QR code of their app; they log in and do a first synchronisation.
• Worker registration (form 08, Workers & attendance app): the team leader registers each worker (name, sex, role, mobile money phone, ID number, photo). The phone warns if the ID number is already registered.
• Attendance (form 09): each training or field day, the team leader opens the worker and declares the day; the supervisor validates it in the evening, with a signature.

What is monitored: the Team attendance mobile report shows the team leader who is validated, to validate or not recorded yet today; the Attendance and payment page gives the overall view.

Watch out for: days declared but not validated will not be paid; a worker registered twice.

2. Enumeration

Goal: register every household of the area and compute the nets it needs.

Enumeration app, enumeration agents, door to door:

1. The agent gives the household a QR ticket and scans it: it is the household's identifier, used again at the distribution. The same ticket cannot be registered twice.
2. They register the head of household (name, age, ID number, phone), the number of people and of sleeping spaces, and the GPS position. The phone computes the nets needed with the campaign's allocation rule, and shows a summary to check before saving.
3. Household absent or refusing (form 03): only its position is registered, with a short code to write on the door. A revisit (form 04) is offered as long as it is not enumerated.
4. Household already served by routine distribution (form 05): it is counted, with the nets already received, without receiving a ticket.

What is monitored: households enumerated, nets needed, absent and refusing households to revisit, by health facility; the map of households in the Progress mobile report shows the areas already covered.

Watch out for: absent and refusing households not revisited; a gap between households enumerated and the expected population; phones that do not synchronise.

3. Logistics and stock

Goal: know at any time how many nets are in each store, and where they went.

Stock app, store keepers of districts and health facilities:

Quantities are entered in bales and pieces; the app computes the total and shows the store's balance after each movement.

What is monitored: the Stock mobile report (balance, totals by movement, last movements) for the store keeper.

Watch out for: a negative balance or one that does not match the physical count; issues without returns at the end of the day.

4. Distribution

Goal: give each enumerated household the computed nets, only once, and keep track of them net by net.

• To households (Distribution app, form 02): 1. the agent finds the household by scanning its ticket, or by searching its name; 2. the app shows the head of household, the ID number and the number of nets to hand over; 3. the agent scans the QR code of each net handed over. The phone refuses a net already scanned, and the household ticket scanned instead of a net.

Once the distribution is saved, it is no longer offered for this household. The Distribution app cannot create households: only enumerated households are served. - To special groups (prisons, camps, boarding schools…, forms 06 and 07): the team registers the group (type, size, planned nets), then the distribution, only once, with the signature of the person in charge.

What is monitored: households served and nets distributed against households enumerated and nets needed; the map of the Progress report tells served households from the remaining ones.

Watch out for: enumerated households not served at the end of the distribution; nets not scanned (unreadable code); the gap between nets issued from the stock and nets distributed.

5. Supervision

Supervision app, form 15, filled in by supervisors during their visits: team composition, attendance validated, stock sufficient and matching the app, phones and synchronisation, refusals and revisits, strengths and weaknesses, and for each problem an action, its owner and its deadline.

What is monitored: the supervision checklists in IASO, by area and date.

6. Worker payment

The Attendance and payment page computes, for each worker, the validated days and the amount due according to the rates of their role (daily rate, one-off allowance, maximum days, mobile money fees), and produces an Excel payment sheet with its formulas. Only the people who prepare payments can open it: it shows phone and ID numbers.

Day-to-day monitoring

4. IASO concepts

Account and modules

An IASO account holds everything of an organisation or a campaign: its pyramid, projects, forms and users. Its modules turn features on: the campaign needs Data collection - Forms (forms), Entities (registries and workflows), Stock management (stock) and Embedded links (web pages).

Pyramid and org unit types

The pyramid is the tree of org units: country, regions, districts, health facilities, villages. Each level is an org unit type. Submissions and entities belong to an org unit, and an app downloads the org unit types attached to it, in its user's area.

Org units belong to a data source (for example "the ministry's pyramid") and to a version of that source. The account has a default version: it is the pyramid that projects, users and phones use, and the kit imports the org units into it, from DHIS2 or from a GeoPackage. The DHIS2 credentials are saved on the data source.

Projects, apps and feature flags

A project is what a phone loads: an app_id, its forms, its org unit types and its feature flags. The same phone can switch between projects.

Forms and versions

A form is an XLSForm. Each upload creates a version; phones get the latest at their next synchronisation. Field names do not change from one version to the next: entities, workflows, stock rules and dashboards refer to them.

Each filled-in form is a submission, which can be viewed in IASO:

Entities and entity types

An entity is something followed over time: a household, a group, a worker. Its entity type sets its reference form (which creates it), the fields shown in lists and details, and the duplicate search (for example on the ticket QR code, blocking when the ticket already exists).

Workflows

The workflow of an entity type holds:

• follow-ups: which form the app offers on the entity, and on which condition (for example, the distribution as long as no net was given);
• changes: which answers of the follow-up form update the entity (for example, the nets given become the household's nets distributed, which closes the distribution).

A workflow is changed in a new version, then published.

Stock

A stock keeping unit (SKU) describes what is counted (here nets, in pieces), in which projects and at which levels. A rules version says, for each stock form, which question adds to or removes from the balance. The app applies these rules to the forms filled in on the phone.

Users and permissions

A user has projects (the apps they can open), org units (their area: the app only downloads that subtree) and permissions. For apps with entities, the Entities permission (iaso_entities) is required: without it, the app neither downloads nor shows households, groups or workers.

Web pages

A page is an HTML document published in IASO at <IASO address>/pages/<name>/, visible only to the chosen users. The kit's pages read the submissions through the API, with the session of the logged-in user.

Mobile reports

A mobile report is a zip (with an index.html at its root) that the app downloads and opens offline when the project has the "Enable reports" feature flag. It reads the phone's data through a JavaScript bridge. Everything it uses must be in the zip (the MapLibre map library, for instance): only the base map is loaded from the internet, when there is a network. Each project has one report; each new upload creates a version, and phones get the published version. It is published through the API (scripts/iaso.py mobile-report-upload) or in the project's Mobile report tab.

Mobile app

Everyone uses the generic IASO app from the Play Store (Bluesquare). On first launch, scan the project's QR code (or enter the server address and the app_id), then log in. At each synchronisation, the app sends its submissions and gets the forms, the area, the entities, the workflows, the stock and the mobile report.

IASO is an open source platform developed by Bluesquare: bluesquarehub.com · source code: github.com/BLSQ/iaso