KoboToolbox

KoboToolbox is used to collect households, complaints, meetings and code of conduct commitments in the field. This page explains how to connect a Kobo account and where the data lands in Bemba.

There is no dedicated KoboToolbox screen. Kobo data goes through the screen that matches its use.

Two KoboToolbox servers

The project has its own KoboToolbox server, in addition to the kobotoolbox.org online service, whose free plan caps monthly submissions.

Server	Address	Use
Kobo online	https://kf.kobotoolbox.org	Existing forms whose links are already in circulation
Project server	https://kf.kobo.ucp-pch.org	New forms, no quota

Each MIS project is connected to one server: API address and token. The MIS can therefore read both.

Accounts and links

A KoboToolbox account belongs to a single server. Users of Kobo online do not exist on the project server: an account must be created for them there. Web links already shared from kobotoolbox.org cannot be redirected.

For installing and running the server, see Self-hosted KoboToolbox.

---

Connecting a Kobo account

Project account

1. Open Administration → Projects.
2. Click the Collection synchronisation ⟳ button on the project row.
3. In the KoboToolbox block, fill in the API URL and the API token.
4. Click Save, then Test the saved connection.

The token is never displayed again. Leave the field empty to keep the token already saved.

Global account

The global account serves projects that have no account of their own.

1. Open Administration → Settings, Settings tab, API Integrations section.
2. Tick Enable this integration.
3. Fill in the API URL and the API Token.
4. Click Test connection, then Save.

Finding your token

In KoboToolbox: Account settings → Security → API key.

---

Importing households

Households collected with Kobo are imported with the import wizard shared by all three sources.

Menu: Data Collection → Data Collection → Households tab → Import

1. Source: choose Kobo, then the Data collection institution, the Project and, if needed, the Programme.
2. Questionnaire: choose the form, then click Load fields.
3. Mapping: match the form fields to the Bemba fields. The Auto-detect button suggests the obvious matches.
4. Preview: check the data.
5. Import: click Start import.

Mapping is mandatory for Kobo. Households arrive in pre-collection and wait for validation before entering the registry. Details are in the import tutorial.

Kobo validation status

The import wizard reads every submission of the form, whatever its status in Kobo. Review the submissions in Kobo before importing, or sort them afterwards in pre-collection.

When the form is synchronised automatically, the status set in Kobo is kept with the household:

Kobo status	Kept as
Approved	Approved, with the approver's name
Not approved	Rejected, with the approver's name
On hold	On hold, with the reviewer's name

---

Importing complaints

Declaring the complaint form

1. Open Complaints (GRM) → Complaints.
2. Click New complaint, then Kobo Import.
3. Under Other available forms, click Configure for complaints next to the form.
4. Click Synchronize to read its submissions.

Categorising received complaints

Menu: Complaints (GRM) → Kobo - Complaints

The screen lists complaints awaiting categorisation. The Sync with Kobo button reads the form again. For each complaint:

1. Click Categorize.
2. Choose the project, category, priority and complaint type.
3. Tick Sensitive complaint (SEA/SH) if needed.
4. Tick Send acknowledgment of receipt if the complainant must be notified.
5. Click Validate and save.

A warning flags probable duplicates: same complainant and same subject as an earlier complaint. Categorisation also works offline: it is sent when the connection returns.

See Complaints.

---

Code of conduct

The public code of conduct signature form is a Kobo form.

Menu: Social Services → Code of conduct

The Sync from Kobo button reads new submissions and downloads their images. The screen then shows the list of signatories, statistics and exports.

---

Automatic synchronisation

Two mechanisms avoid manual imports:

• Kobo REST service: KoboToolbox can notify Bemba of each new submission. An administrator sets this up in Kobo.
• Scheduled command: an administrator can synchronise a form with a project's account.

php bin/console app:kobo:sync <form_identifier> --projet=PROJECT_CODE

A project without its own Kobo account is refused by this command.

---

Troubleshooting

Problem	Likely cause	Solution
No questionnaire offered	Project not chosen, or project account missing	Choose the project in the first step; check its synchronisation
"Not configured on this server"	No Kobo account, neither for the project nor global	Fill in the project account
Connection test fails	Wrong token or URL, or wrong server	Check that the URL and the token come from the same server
Empty fields after import	Incomplete mapping	Run the import again with a complete mapping
A surveyor shows no activity	Kobo identifier differs from the user name	Correct their record in Surveyors

---

Good practices

• One Kobo account per project, with a dedicated token.
• New forms on the project server.
• A small test import for every new form.
• Imported households processed without delay in pre-collection.

See also

• Introduction
• Survey Solutions