KoboToolbox
The KoboToolbox page allows you to manage collection form synchronization and data import into Bemba.
Access
Menu: Collection → KoboToolbox
Overview
Global Statistics
At the top of the page, cards display key indicators:
| Indicator | Icon | Description |
|---|---|---|
| Active forms | Document | Number of configured forms |
| Total submissions | Database | Total available submissions |
| Last sync | Clock | Date of last synchronization |
| Active webhooks | Lightning | Number of configured webhooks |
Form List
Displayed Columns
| Column | Description |
|---|---|
| Name | KoboToolbox form name |
| Type | Form type (PMT, Validation, Monitoring, Complaint) |
| Submissions | Number of available submissions |
| Last sync | Date of last synchronization |
| Status | Active/Inactive |
| Actions | Configure, Synchronize, View |
Form Types
| Type | Badge | Description |
|---|---|---|
| PMT | Blue | Household collection for PMT calculation |
| Validation | Green | Community validation |
| Monitoring | Purple | Beneficiary monitoring |
| Complaint | Orange | Complaint registration |
Configure a Form
Access
Click the Configure icon (gear) on a form.
Configuration Parameters
| Field | Description |
|---|---|
| Form type | Select: PMT, Validation, Monitoring, Complaint |
| Active | Enable/disable synchronization |
| Webhook | Webhook URL (optional) |
Detailed Form Types
PMT - Household Collection
Form for socioeconomic data collection:
- Household information
- Family composition
- Housing characteristics
- Assets and income
Community Validation
Validation form by local committees:
- Information confirmation
- Community observations
- Recommendations
Beneficiary Monitoring
Monitoring visit form:
- Beneficiary status
- Transfer usage
- Difficulties encountered
Complaint Registration
Field complaint collection form:
- Complaint description
- Complainant information
- Attachments (photos)
Synchronize Data
Simple Synchronization
- Click Synchronize on a form
- Choose synchronization mode:
| Mode | Description |
|---|---|
| Normal | Imports only new submissions |
| Force resynchronization | Re-imports all submissions |
- Confirm synchronization
Preview
Before import, the system displays statistics:
| Statistic | Description |
|---|---|
| Total submissions | Total number of submissions |
| New to import | Not yet imported submissions |
| Already processed | Submissions already in Bemba |
| Households involved | Number of households to create/update |
| Average completion rate | Average % of form completion |
Advanced Synchronization
Access
Click Advanced sync to open filtering options.
Available Filters
| Filter | Type | Description |
|---|---|---|
| Enumerator | Selection | Filter by enumerator |
| Region | Selection | Filter by region |
| Sector | Selection | Cascade from region |
| Locality | Selection | Cascade from sector |
Cascade Filters
First select the region to see available sectors, then the sector to see localities.
Grouping Options
| Option | Description |
|---|---|
| Both | Groups by enumerator AND geographic area |
| By enumerator | Creates a batch per enumerator |
| By area | Creates a batch per geographic area |
Process
- Select desired filters
- Choose grouping mode
- Click Preview
- Verify statistics
- Click Launch synchronization
Webhook Management
What is a Webhook?
A webhook allows automatic reception of new submissions as soon as they are validated on KoboToolbox.
Configure a Webhook
- Access form configuration
- Enable the Webhook option
- Copy the generated URL
- Paste the URL in KoboToolbox settings
Benefits
- Real-time automatic import
- No manual synchronization needed
- Immediate notification of new data
Import Rules
Approved Submissions Only
By default, only submissions with Approved status are imported. This ensures:
- Data validated by a supervisor
- Upstream quality control
- Avoiding data entry errors
Duplicate Detection
The system automatically detects:
| Criterion | Action |
|---|---|
| Same submission ID | Ignored (already imported) |
| Same household (code) | Data update |
| Potential duplicate | Flagged for verification |
Synchronization History
Access
History is visible in the Last sync column and via the History button.
Displayed Information
| Information | Description |
|---|---|
| Date/Time | Synchronization moment |
| User | Who launched the sync |
| Mode | Normal, Forced, Advanced |
| Result | Success, Partial, Failure |
| Statistics | Imported, Ignored, Errors |
Use Cases
Daily Collection Import
- Access KoboToolbox
- Check new submissions
- Launch a normal synchronization
- Verify imported households
Re-import After Correction
If errors were corrected in KoboToolbox:
- Access the concerned form
- Click Synchronize
- Select Force resynchronization
- Confirm the action
Targeted Import by Area
To import only data from a locality:
- Click Advanced sync
- Select region → sector → locality
- Preview the data
- Launch import
Import by Enumerator
To verify a specific enumerator's data:
- Click Advanced sync
- Select the enumerator
- Choose By enumerator as grouping
- Preview and import
Troubleshooting
No Submissions Found
| Cause | Solution |
|---|---|
| Form not deployed | Deploy the form on KoboToolbox |
| Invalid API token | Check token in settings |
| No approved submissions | Approve submissions in KoboToolbox |
Errors During Import
| Error | Cause | Solution |
|---|---|---|
| Missing data | Required fields not filled | Check KoboToolbox form |
| Area not found | Non-existent locality code | Update geographic reference |
| Unknown enumerator | Email not recognized | Create enumerator in Bemba |
Data Not Updated
- Verify that Force mode is used
- Check code correspondences
- Consult import logs
Best Practices
Configuration
- Configure the correct type for each form
- Enable webhooks for automatic import
- Test with a small sample first
Synchronization
- Perform regular syncs (daily)
- Use filters for targeted imports
- Always check the preview
Data Quality
- Ensure supervisors approve submissions
- Check flagged duplicates
- Correct errors in KoboToolbox before re-importing