Microplanning Setup
Overview
Microplanning lets you divide a territory into Work Areas (geographic catchment zones), group them into manageable clusters, and assign them to individual field workers. Once assigned, each worker sees their territory on the CommCare mobile app and records visits within it.
Work areas are uploaded as a CSV, automatically clustered into spatially contiguous groups sized for a single worker, and then assigned through a map-based interface. As workers complete visits, area statuses update in real time and a programme manager can monitor progress, flag inaccessible areas, and download reports.
Prerequisites
What is needed | Details |
|---|---|
MICROPLANNING feature flag enabled for the opportunity | Contact the Connect platform team if not visible |
Opportunity already created and linked to a CommCare HQ app | The deliver app must be linked before configuring microplanning or tasks |
Field workers enrolled | Workers must have accepted the opportunity in the Connect app |
CommCare HQ App Configuration
This section covers the changes needed in your CommCare HQ application to support Microplanning and Tasking. These are specific to these features and are separate from the standard Connect app setup.
Changes Needed for Microplanning
Work Area Case Module
Deliver Form — Work Area Reference
Your deliver form needs to reference the case_id for work_area_id field
This links each delivery visit to a specific work area in Connect, which updates the work area's status automatically.
Deliver Form — Inaccessibility Flagging (optional)
To allow workers to flag a work area as inaccessible from the app:
Add a question to the deliver form asking whether the area is inaccessible.
When submitted with the value
REQUEST_FOR_INACCESSIBLE, Connect updates the work area status for a manager to review.
Microplanning
Upload Work Areas
Work Areas are geographic catchment zones uploaded as a CSV file. Each row represents one zone with its boundary, location details, and target visit counts.
Prepare Your CSV
Download the template from: Opportunity → Microplanning → Upload Work Areas → Download Template
Column | Required | Description |
|---|---|---|
Area Slug | Yes | A unique identifier for this work area within the opportunity. Use simple slug-safe text (e.g. |
Ward | Yes | The administrative ward this area belongs to. Areas in the same ward can be clustered together. |
Centroid | Yes | The centre point as longitude then latitude, space-separated (e.g. |
Boundary | Yes | The polygon boundary in WKT format (e.g. |
Building Count | Yes | Estimated number of buildings or households in this area. Used to size clusters. |
Expected Visit Count | Yes | Target number of visits a worker should make in this area. |
Target Population | Yes | Target Population Count for the work area. Can be left empty if not setting, which defaults to zero. |
Max WAG | Yes | Programme-specific property synced to the CommCare case. |
WAG Serial Number | Yes | Programme-specific property synced to the CommCare case. |
LGA | Yes | Local Government Area name. |
State | Yes | State name. |
Important notes
Area Slug must be unique across the entire file and all existing work areas for this opportunity.
Centroid is longitude first, then latitude — the reverse of how most mapping tools display coordinates.
The entire file is validated before any rows are saved. If one row has an error, nothing is imported — fix all errors and re-upload.
Re-upload is blocked if work areas already exist. Contact the platform team to reset.
Upload Steps
Navigate to Opportunity → Microplanning.
Click Upload Work Areas.
Select your CSV file and submit.
A progress indicator appears — wait for the import to complete.
If there are errors, each one shows the row number and what is wrong. Fix and re-upload.
Cluster Work Areas
Once work areas are uploaded, group them into Work Area Groups before assigning to workers. Clustering creates spatially contiguous groups sized for a single worker.
Work Area Groups are simply text values added to the work areas and don’t exist individually as a model.
How to Cluster
On the Microplanning map page, click Cluster Work Areas.
The process runs in the background — wait a few minutes for completion.
Once done, coloured group regions appear on the map.
Clustering can only be run once per opportunity. Contact the platform team if re-clustering is needed.
How Groups Are Formed
Ward boundaries — areas from different wards are never grouped together.
Proximity — areas that share a boundary or are within 100 metres of each other are candidates for grouping.
Building count — a group will not exceed 300 buildings total.
Group names — assigned automatically, e.g.
Ward1_1,Ward1_2.
Assign Work Areas to Field Workers
Assignment Steps
On the Microplanning map, click Enter Assignment Mode.
Select a Work Area Group from the sidebar — its areas are highlighted on the map.
Choose a Worker from the assignee dropdown. Only active, enrolled workers are shown.
Click Save Assignment.
Repeat for each group.
What Happens After Assignment
Work areas are linked to the selected worker in Connect.
Connect syncs work-area cases to CommCare HQ owned by that worker — on their next sync, the worker sees their territory in the app.
The worker receives a push notification: "New Work Areas Assigned".
Work area status changes from Unassigned to Not Started.
Work Area Status Reference
Status | What it means |
|---|---|
Unassigned | No worker assigned yet |
Not Started | Assigned to a worker but no visits recorded |
Visited | At least one delivery visit recorded in this area |
Request for Inaccessible | Worker flagged this area as potentially inaccessible via the app |
Expected Visit Reached | Target visit count has been met |
Inaccessible | Confirmed inaccessible — reviewed and set by a manager |
Excluded | Removed from the active scope of the opportunity |
Monitor Work Area Progress
From the Microplanning map, a Program Manager can:
See all work areas colour-coded by status.
Filter by status, assigned worker, or date range.
Click into a work area to edit its expected visit count or group assignment.
Download a CSV of all work areas with current status, visit data, and assignment details.
When a worker flags an area as inaccessible, it shows status Request for Inaccessible. A manager must review it and either confirm (Inaccessible) or revert it.