How to Migrate from NPSP to Agentforce Nonprofit

Moving from the Nonprofit Success Pack to Agentforce Nonprofit is not an upgrade. The two products model a constituent differently at the foundation, so this is a data migration project with a reconciliation problem attached. Done well, you also get to delete years of workarounds. Done badly, your year-end totals stop matching and nobody trusts the new org. This guide is the sequence we use, in the order that keeps the numbers correct.

Decide this before you touch anything

Two decisions shape everything that follows. Make them in writing, with the finance lead in the room.

What is the reconciliation standard? Pick the reports that must match the old system exactly, and name them. Usually it is total raised by fiscal year, total by designation or fund, donor counts, and the recurring giving roster. Everything else can be approximate. If you do not set this boundary, you will chase every discrepancy in a 20 year gift history and never finish.

What is the cutover window? Find eight weeks with no campaign, no audit, and no year-end appeal. That window is your hard constraint, and it usually sets the project timeline more than the technical work does.

New org or migrate in place?

Almost always a new org. Here is the honest comparison.

The Person Account row is the decisive one. Agentforce Nonprofit is built on Person Accounts, and turning them on in a long-lived org with a large Contact base is a change you cannot cleanly undo. A new org avoids the whole question.

The one common exception is a small, young NPSP org with almost no customization and one integration. There, an in-place rebuild can work.

The object mapping table

This is the core of the migration plan. Keep it as a live document, because the field-level detail underneath each row is where the work actually is.

Step 1: Inventory and triage customizations

Before any data work, list every custom field, validation rule, flow, Apex class, report, and dashboard in the NPSP org. Then put each item in exactly one of three piles.

• Port. It encodes something specific to your organization that the platform does not provide.
• Replace. The newer model does this as standard. Designations, soft credits, tributes, source codes, and outcome tracking are the usual candidates.
• Delete. Nobody uses it, or it existed to work around an NPSP limitation that no longer applies.

In most orgs we assess, the delete pile is the largest, and the replace pile is the one that saves the most money. Do this triage before you scope the build, because the scope is the port pile plus the migration, and nothing else.

Step 2: Clean and dedupe in the source

Fix data in NPSP, not after the load. Once gift history hangs off a duplicate Person Account, merging is far more expensive and far more likely to lose an audit trail.

1. Run duplicate detection on constituents and merge. Expect the pass rate to be worse than you think, especially where a household and an individual both received mail.
2. Standardize and validate addresses. Bad addresses become bad ContactPointAddress records.
3. Find gifts with no designation, no campaign, or no date and decide the default for each case before the load, not during it.
4. Resolve deceased, do-not-contact, and opt-out flags. These must survive the move exactly, because getting them wrong has legal and reputational consequences.
5. Reconcile your source totals now. Produce the parity reports from NPSP and freeze them as the target numbers.

Step 3: Build constituents and households

Load in dependency order, and keep the NPSP record id in an external id field on every new record. You will need it for every later step and for support questions years from now.

1. Enable Person Accounts in the new org before anything else.
2. Load organization business accounts.
3. Load individuals as Person Accounts.
4. Create household business accounts, then a PartyRelationshipGroup for each with Type set to Household. Use the Subtype and other group fields where they carry meaning for your programs.
5. Create AccountContactRelation records to place people in households, and set the roles you rely on for salutations and mailings.
6. Load ContactPointEmail, ContactPointPhone, and ContactPointAddress records, with the primary and preferred flags set deliberately.
7. Load relationships as ContactContactRelation plus PartyRoleRelationship, remembering that you now write both directions.

Note that creating groups needs the Group Membership permission set, and merging them needs the Merge and Split Groups system permission in a cloned permission set. Sort permissions out before the load rather than during it.

Step 4: Load designations, then gifts

Order matters. A gift cannot point at a designation that does not exist.

1. Create GiftDesignation records from your General Accounting Units. Take the chance to retire funds nobody has used in five years.
2. Load GiftTransaction records. Map amount, date, payment method, campaign, and source code. Keep the NPSP Opportunity id as an external id.
3. Create GiftTransactionDesignation records from your allocations. Then reconcile the total per designation against the frozen NPSP figure before you go further.
4. Load GiftSoftCredit records. Verify that your parity report still shows the same hard credit total, because soft credit errors show up here as inflated revenue.
5. Load GiftTribute records for in-honor and in-memory gifts.

The pledge and payment question deserves its own attention. In NPSP a pledge is an Opportunity with multiple Payment records. In the newer model a pledge is a GiftCommitment with a GiftCommitmentSchedule, and each received payment is a GiftTransaction linked back to that commitment. If you load both the pledge and the payments as Gift Transactions, you double your revenue. We cover the correct modelling in the fundraising implementation guide.

Step 5: Rebuild recurring giving

This is the step with the most operational risk, because real money moves on a schedule and donors notice mistakes immediately.

1. Extract every active Recurring Donation with its amount, frequency, next charge date, designation, and payment method.
2. Create a GiftCommitment for each, with a GiftCommitmentSchedule that reproduces the frequency and next date exactly.
3. Set default designations with GiftDefaultDesignation so generated transactions land in the right fund without manual work.
4. Use GiftDefaultSoftCredit where a recurring gift should credit an influencer, such as a board member who secured it.
5. Coordinate with your payment processor. Tokens, customer ids, and schedules have to line up. Agree exactly which system owns the schedule after cutover.
6. Test with a small live cohort before you move everyone. A declined card on migration weekend must produce a retry, not a silent lapse.

Step 6: Reach rollup and report parity

Do not migrate rollup values. Recalculate them in the new org using Data Processing Engine definitions and the standard summary objects, then compare against your frozen NPSP numbers. Migrated totals paper over load errors, and you will find the errors later at the worst possible moment.

Reconcile in this order, and stop when a level fails rather than pushing on:

1. Total raised per fiscal year, all funds.
2. Total per designation per fiscal year.
3. Donor count and new donor count per year.
4. Top 100 donors by lifetime giving, matched name by name.
5. Active recurring giving: donor count, monthly value, next charge dates.

Then rebuild the board pack and the audit reports. Have the finance lead sign off in writing that the new org produces the same numbers. That signature is what lets you switch off the old system.

Step 7: Repoint integrations

Every system that touches donation data needs work, because the objects it wrote to no longer exist. Typical list:

• Payment processor and online giving forms. They must create Gift Transactions and respect commitments.
• Email and marketing tools. Contact Point objects now hold email and consent. Map opt-out carefully.
• Accounting. Your journal entries or subledger feed keys off designations and gift dates.
• Wealth screening and prospect research. Results now belong on the philanthropic assessment and indicator objects rather than in custom fields.
• Event, volunteer, and forms tools. Anything writing Contacts should be checked against the Person Account model.

Use Named Credentials and log every callout, so that when something fails at 2am on cutover weekend you can see what happened. Our callout framework guide covers the pattern.

Step 8: Cut over

1. Freeze the source. Announce a hard stop for data entry in NPSP, with a named person enforcing it.
2. Run the delta load. Move everything created or changed since your last full extract.
3. Reconcile again. Same reports, same standard. This is a gate, not a formality.
4. Switch users. Activate users in the new org, deactivate write access in the old one.
5. Repoint live integrations and watch the first transactions land.
6. Keep the old org read-only for a full reporting cycle. At least one quarter, ideally through your next audit. It costs little and it answers the questions that only surface later.

Five mistakes that cause rework

• Loading gifts before designations. You end up with unallocated revenue and a manual repair job.
• Treating NPSP payments as separate gifts. The classic double counting error. Pledges are commitments, receipts are transactions.
• Skipping dedupe because the timeline is tight. The timeline gets tighter later, and by then the duplicates own gift history.
• Porting customizations without triage. You pay to rebuild workarounds for problems the new platform already solved.
• No named reconciliation standard. Without it, the project has no definition of done and the finance team never signs off.

Frequently asked questions