Microplanning Setup

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

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

Column

Required

Description

Area Slug

Yes

A unique identifier for this work area within the opportunity. Use simple slug-safe text (e.g. ward1_area_01).

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. 3.3792 6.5244). Note: longitude comes first.

Boundary

Yes

The polygon boundary in WKT format (e.g. POLYGON((3.37 6.52, 3.38 6.52, ...))).

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

  1. Navigate to Opportunity → Microplanning.

  2. Click Upload Work Areas.

  3. Select your CSV file and submit.

  4. A progress indicator appears — wait for the import to complete.

  5. 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

  1. On the Microplanning map page, click Cluster Work Areas.

  2. The process runs in the background — wait a few minutes for completion.

  3. 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

  1. On the Microplanning map, click Enter Assignment Mode.

  2. Select a Work Area Group from the sidebar — its areas are highlighted on the map.

  3. Choose a Worker from the assignee dropdown. Only active, enrolled workers are shown.

  4. Click Save Assignment.

  5. 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

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.