The NPSP data migration checklist: objects, mapping, rehearsal and cutover

Most of the risk in an NPSP data migration sits nowhere near the extract or the load. It sits in the fortnight before you load anything: deciding what actually moves, agreeing what each record becomes on the other side, and naming the person who signs off that it arrived intact. The tooling is the easy part. Data Loader has not been the bottleneck on any project we have run.

This is the checklist we work from. It assumes you have already decided to move — if you are still weighing that up, start with the migration decision itself and come back here when the answer is yes.

The short version: inventory every object and field before you map anything, rehearse the full load in a partial-copy sandbox until the reconciliation counts match the source, load parents before children with sign-off between each step, and archive every record before you delete it. Everything below is elaboration on those five sentences.

Why this is a migration and not an upgrade

Worth being blunt about the ground you are standing on. NPSP received its last feature work in March 2023. It is still supported, and Salesforce has published no retirement date — so nobody is forcing your hand this quarter. In December 2025 Nonprofit Cloud was renamed Agentforce Nonprofit. NPSP was not renamed, and NPSP data was not moved anywhere as part of that.

That last point is the one that catches people. There is no upgrade path, no toggle, no migration wizard. You are building a new org and moving data into a different model. The model differences are what generate almost all of the mapping work:

• Household Accounts plus Contacts become Person Accounts. One record type on one side, two linked records on the other.
• Service delivery leaves tasks and custom objects and lands in Program Management as Program Enrollments, and in Benefit Disbursements.
• Case Management and Outcome Management are separate configured areas, not a field you tick.

Phase 1: build the NPSP data migration inventory

You cannot map what you have not counted. Before any mapping workshop, produce a single spreadsheet with one row per object and one row per field.

• List every object holding data: standard, NPSP package, and custom. Include the ones nobody mentions — contact detail records, relationships, enquiries, attachments.
• Record the live row count for each object, dated. These become your reconciliation targets.
• For each object, list every field with its API name, type, and whether it is standard, NPSP-package or custom.
• Mark each field: moves, moves transformed, archive only, or drop.
• Get the drop list signed by the service manager, not just the CRM admin.

On an Australian community-care provider we delivered with the implementation partner, the Contact object alone carried 314 fields across standard, NPSP-package and custom. Nobody in the organisation knew that number before we counted. A meaningful share were dead — populated once in 2019 and never again. Finding that early is what keeps the mapping workshop to a sane length, and it is the single biggest driver of what the migration ends up costing.

Phase 2: map fields, and then map values

Field mapping is the visible work. Value mapping is where the load actually fails.

• Map source field to target field for every field marked moves.
• For moves transformed, write the transformation rule in words before anyone writes a formula.
• Map every picklist value, not just the picklist field. A source value of “Active - Reviewing” that does not exist in the target picklist fails the row, and restricted picklists fail loudly while unrestricted ones silently accept rubbish.
• Decide record types per object and which records get which. Record type drives page layout and picklist availability downstream.
• Decide record ownership. Every record needs an owner in the target org, and departed staff are not owners. Agree a default owner for orphaned records.
• Identify required fields in the target that have no source equivalent. Each one needs a default value or the field stops being required.
• Assign an external ID on every object — typically the source record ID.

That last one is not optional. An external ID lets you upsert rather than insert, which makes every load re-runnable. Without it, a half-failed load leaves you reconciling duplicates by hand at eleven at night. With it, you fix the mapping and run the same file again.

Phase 3: prepare the target org to accept a load

A clean target org will reject your data enthusiastically. Automation that is correct for daily use is usually wrong for a bulk load.

• Inventory every validation rule and decide, rule by rule, whether it is deactivated for the load. Historical data legitimately breaks rules written for new records.
• Review duplicate rules and matching rules. A duplicate rule set to block will reject legitimate historical records; set to alert, it will let genuine duplicates through.
• Disable or scope triggers, flows and assignment rules that fire on create, then plan how the work they would have done gets applied afterwards.
• Write down everything you switched off, with an owner for switching it back on. This list is a deliverable, not a sticky note.
• Confirm field-level security — the load user cannot write to a field it cannot see.

Phase 4: rehearse in a partial-copy sandbox

A rehearsal that runs in a developer sandbox with twelve records tells you nothing. Rehearsal loads need real volume and real mess.

• Run the complete load, in production order, in a partial-copy sandbox.
• Validate every object against source counts before calling the rehearsal done.
• Record the failed-record count and the reason for each failure class. Fix the mapping, not the individual row.
• Time each step. Cutover planning needs real durations, not estimates.
• Rehearse at least twice. The second run is the one that tells you whether your fixes held.

On that same provider, 201 risk assessments carrying 4,645 question responses loaded with zero failed records in production — because the rehearsal rounds had already surfaced every picklist mismatch and every required-field gap. Zero failures on the day is a rehearsal outcome, not luck.

Phase 5: load in parent-before-child order, with sign-off

Ordering is not a preference. A child record with no parent is a failed row.

The production order we used was: organisations, then people, then cases, enquiries, relationships and tasks — with sign-off between each step. Not sign-off at the end. Between each step.

• Load organisations (accounts) first.
• Load people, linked to organisations by external ID.
• Load cases, then enquiries, relationships and tasks.
• After each object, reconcile counts and have a named business owner confirm in writing before the next step starts.
• Keep the success and error files from every load, named and dated.

Final reconciliation on that engagement covered 2,313 people, 625 organisations, 2,097 cases and 2,519 contact-detail records. The counts were checked against source, by object, and signed off — which is why nobody spent the following month wondering whether something had gone missing.

Phase 6: move staff in cohorts, with delta loads

Big-bang cutovers fail for organisational reasons more often than technical ones. We moved staff in cohorts, running a delta load after each one to capture everything created in the legacy system while that cohort was still working in it. One delta was around 3,500 records — client sessions, tasks, documents, check-ins and risk assessments.

• Define cohorts by team or service, not alphabetically.
• After each cohort moves, run a delta load for records created or modified since the last extract.
• Use the external ID so deltas upsert cleanly.
• Set a hard read-only date for the legacy system per cohort.
• Keep the legacy system readable, not writable, until the final reconciliation is signed.

The staged cutover pattern is worth reading in full if you have more than one service line.

Phase 7: archive before you delete

17,248 legacy tasks became Benefit Disbursement records on that project. Every original was archived before deletion — extracted, stored, and verified readable.

• Extract and store the source data before any transformation or deletion.
• Verify the archive opens and is complete. An unreadable archive is not an archive.
• Confirm the retention period with whoever owns your records obligations.
• Only then delete.

You can see the full shape of this work in the community-care migration case study.

If you are planning one of these and want a second set of eyes on the mapping before you load anything, have a conversation with us. Thirty minutes on your object inventory is cheaper than a fortnight of reconciliation.