1. Background / Context

Village Mapping for an ASHA worker can already be changed through the Provider Admin Portal, under Activities → Work Location Mapping → Edit, where the admin can select a different village from the mapping dropdown.

However, if data was already entered against a user while they were incorrectly mapped to the wrong village, that data currently stays attached to the wrong village even after the mapping is corrected. Fixing this today requires a developer to manually correct the data at the database level.

2. Problem Statement

When a user's village mapping is corrected on the Provider Admin Portal, historical data entered under the wrong village is not automatically re-associated with the corrected village — requiring manual, developer-driven database correction for every case.

3. Goal / Desired Outcome

When a user's village mapping is changed through the Provider Admin Portal, transfer all data previously entered under the wrongly mapped village — beneficiary records, visits, services, and reports — to the newly assigned village, eliminating the need for manual backend correction, while ensuring this only happens in genuine correction scenarios and not legitimate reassignments (pending resolution of the open design question in Section 9/10).

4. User Story

As a Provider Admin, I want a user's historical data to automatically move to the corrected village when I fix their village mapping, so that I no longer need to request a manual database correction every time a mapping error is found.

5. Scope

In scope:

• Migration of all historical data types associated with the user under the old village — beneficiary records, visits, services, and reports — to the new village, once mapping is changed.
• Migration applies to all such data regardless of how old it is (no date cutoff).
• Audit logging of the migration (what was moved, from village, to village, changed by, date/time, record counts).

Out of scope:

• Correcting or re-syncing data that has already been submitted to external Government MIS systems — flagged as an open question requiring compliance input.
• Any change to how the Village Mapping field itself is edited on the Provider Admin Portal (already functional today).
• Bulk correction across multiple users in a single action — this covers the single-user mapping-change flow only.

6. Requirements / Functional Details

1. When an admin changes a user's village mapping from Village A to Village B via Work Location Mapping → Edit, the system identifies all data currently associated with that user under Village A.
2. All identified data — beneficiary records, visits, services, and reports — is re-associated with Village B as part of the same operation.
3. The migration must be atomic: either the mapping change and the full data migration both complete successfully, or neither does (no partial migration).
4. No data should be deleted, duplicated, or lost during migration — only the village association on existing records changes.
5. An audit record is created capturing: user, old village, new village, changed by, date/time, and a count of records migrated per data type.
6. Data migration behavior by type:

1. Key open design point: village mapping changes happen for two different reasons — correction (village entered incorrectly, migration desired) vs. reassignment (user genuinely worked in the old village; migration would be incorrect). The BRD recommends the admin explicitly indicate intent at the time of the mapping change (e.g., "This is a correction" vs. "This is a reassignment"), with auto-migration triggering only for the correction path. This needs sign-off before development (see Section 10).

7. Acceptance Criteria

• Given an admin corrects a user's village mapping from Village A to Village B, when the change is saved, then all of that user's beneficiary, visit, service, and report data previously under Village A is now associated with Village B.
• Given a migration completes, then an audit record exists capturing old village, new village, changed-by, date, time, and record counts per data type.
• Given a migration is triggered, then no records are lost, duplicated, or left attached to both villages simultaneously.
• Given the correction-vs-reassignment design question is resolved, then the chosen mechanism correctly triggers migration only for genuine corrections.

8. Technical Notes / Dependencies

• Migration must run as a single atomic transaction per mapping change; partial migrations must roll back entirely.
• Migration covers all historical data with no date cutoff — volume could be large for long-tenured users; the migration process should be designed to handle this without timing out or degrading portal performance (exact scale to be sized with Engineering).
• Only users with the appropriate Provider Admin permission can change village mapping and trigger migration.
• Correcting/re-syncing data already submitted to external Government MIS systems is out of scope and would require a separate, compliance-approved process.

9. Risks & Assumptions

• Open design question (BRD Section 4.2): the system does not yet define how to distinguish a genuine correction from a legitimate reassignment. Applying auto-migration without this distinction risks incorrectly rewriting historical data for users who were legitimately reassigned. Needs resolution/sign-off before development.
• Whether data already submitted to external Government MIS systems should also be corrected/re-synced is unresolved — pending compliance input.
• No upper bound is defined for how much historical data a single migration might need to move; whether this requires a background/asynchronous process rather than an instant one is unresolved.
• Whether the admin should see a preview/confirmation (e.g., record counts to be migrated) before triggering migration, given the scale and irreversibility of the action, is unresolved.
• Whether a rollback/undo option is needed if a migration is triggered in error is unresolved.

10. Attachments & Links

Source BRD (Confluence): BRD : Enable Edit of User Name, Employee ID and Village Mapping in Employee Master — AMRIT - AMRIT - Confluence