agentleFS
omoji-personalomoji-personal/torque/.agents/skills/salesforce-npsp/SKILL.md

salesforce-npsp

Skill0 starsChanged 3 days agoMITView on GitHub

Work in a Nonprofit Success Pack (NPSP) org, including the Program Management Module and Outbound Funds. Use it before any design, build, data load or diagnosis in an org that has the npsp, npe01, npo02, npe03, pmdm or outfunds packages. Covers the data model, households, TDTM trigger handlers, customizable rollups, enhanced recurring donations, payments, GAU allocations, soft credits, gift entry, PMM attendance, flows on NPSP objects, and the common gotchas with a check for each.

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When writes are in scope, run NPSP Settings > System Tools > Health Check.

    line 46

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Salesforce NPSP

NPSP is a suite of managed packages on standard Account, Contact and Opportunity. It is still supported, but new nonprofit features ship in Nonprofit Cloud, which is a different product (see the salesforce-nonprofit-cloud skill). Moving between them is a migration, not an upgrade. Since December 2025 NPSP is no longer offered as a preconfigured package in new production orgs (Trailhead, see Sources), so existing NPSP orgs and new Nonprofit Cloud orgs will both be met for years.

General build practice is in skills salesforce-build and salesforce-flow; this skill holds what is specific to the packages.

Reference files in this folder, read when the task needs them:

  • references/mechanics.md: TDTM, rollup engines and jobs, recurring donations, payments, allocations, soft credits, gift entry, households, scheduled jobs.
  • references/pmm-ofm.md: Program Management Module objects and attendance, rollup gates, Outbound Funds.
  • references/gotchas.md: the common failure modes, each with an org check.

First checks in an unfamiliar org

Confirm these before designing anything; the answers change most other advice.

QuestionRead-only check
NPSP or Nonprofit Cloud?sf package installed list --target-org ALIAS shows npsp, npe01, npo02, npe03, npe4, npe5. SOQL on InstalledSubscriberPackage by namespace is unreliable. SELECT COUNT() FROM GiftTransaction succeeds only in Nonprofit Cloud.
Account modelSELECT npe01__Account_Processor__c FROM npe01__Contacts_And_Orgs_Settings__c (Household Account is the default and current model; this skill describes it, so for any other value stop and read the org's own model first)
Recurring donation modelSELECT npsp__IsRecurringDonations2Enabled__c FROM npe03__Recurring_Donations_Settings__c
Rollup engineSELECT npsp__Customizable_Rollups_Enabled__c FROM npsp__Customizable_Rollup_Settings__c
Another rollup toolA rollup package in the installed package list (for example DLRS, namespace dlrs): describe its rule type, then read each rule's mode and any scheduled job in CronTrigger before adding a rollup or trigger on the same objects
Scheduled jobs aliveSELECT CronJobDetail.Name, State, NextFireTime, CreatedBy.IsActive FROM CronTrigger WHERE CronJobDetail.Name LIKE 'NPSP%'
Errors and who hears about themSELECT npsp__Store_Errors_On__c, npsp__Error_Notifications_On__c, npsp__Error_Notifications_To__c, npsp__Disable_Error_Handling__c FROM npsp__Error_Settings__c; recent npsp__Error__c rows
Handlers switched offSELECT npsp__Class__c, npsp__Object__c, npsp__Active__c, npsp__User_Managed__c, npsp__Usernames_to_Exclude__c FROM npsp__Trigger_Handler__c WHERE npsp__Active__c = false OR npsp__Usernames_to_Exclude__c != null
PMM or Outbound Funds presentpmdm or outfunds in the installed package list

A query that errors can also mean the running user lacks access: treat an error as "not checked" and confirm with the installed package list. Read field and namespace names from the org with describe; installed versions differ.

When writes are in scope, run NPSP Settings > System Tools > Health Check. In a read-only study do not open NPSP Settings at all: field-reported, opening it in a sandbox inserted default trigger handlers and scheduled jobs. Check: count npsp__Trigger_Handler__c rows and NPSP% rows in CronTrigger before and after the study.

Packages

NamespaceOwns
npe01Payment (npe01__OppPayment__c), Contacts and Orgs settings, payment field mappings
npo02Households settings, legacy household object, legacy rollup fields on Account and Contact
npe03Recurring Donation (npe03__Recurring_Donation__c) and its settings
npe4Relationship (npe4__Relationship__c)
npe5Affiliation (npe5__Affiliation__c)
npspEverything else: TDTM, Address, GAU and Allocation, Partial and Account Soft Credit, Levels, Engagement Plans, Data Import and Gift Entry, rollup custom metadata, Error log, RD2 schedules and change log

Data model in brief

  • Households. Each individual Contact sits in a Household Account. A person's employer link is an Affiliation, not a move of the Contact to the company Account. Person-to-person links are Relationships with automatic reciprocals.
  • Gifts. The Opportunity is the gift. npsp__Primary_Contact__c drives the primary contact role and contact hard credit; a blank Primary Contact means no contact hard credit.
  • Payments (npe01__OppPayment__c, master-detail to Opportunity) are the cash. Opportunity Amount and Close Date are the commitment. Pledged and paid totals differ.
  • GAU allocations (npsp__Allocation__c) split a gift, payment, campaign or recurring donation across npsp__General_Accounting_Unit__c funds.
  • Soft credits. Contact roles whose role is in the soft-credit role list (default Matched Donor;Soft Credit;Household Member) give full-amount soft credit. npsp__Partial_Soft_Credit__c gives a partial amount; npsp__Account_Soft_Credit__c credits an organization.
  • Recurring donations. Enhanced recurring donations (RD2) add npsp__RecurringDonationSchedule__c and npsp__RecurringDonationChangeLog__c.
  • Addresses (npsp__Address__c) belong to the household; the default address syncs to the Account billing address and every member's mailing address.

Automation and extension

  • TDTM. One trigger per object dispatches npsp__Trigger_Handler__c rows in load order. To keep a handler off across upgrades, set Active off and User Managed on. Per-user skip: Usernames_to_Exclude__c. Per-transaction bypass in Apex: npsp.TDTM_Config_API or the Callable_API action TDTM.DisableAllTriggers. Any bypass skips contact roles, payments, households, allocations and rollups for those rows; run the matching batch afterwards.
  • Custom Apex in NPSP's order: a global class extending npsp.TDTM_Runnable plus a npsp__Trigger_Handler__c row with User Managed on (confirm the signature against the installed version).
  • UI or Callable only: enabling customizable rollups, RD2, Advanced Mapping and Gift Entry. Setting the custom setting by data load skips the metadata deploy, migration and job rescheduling.
  • Do not deploy edited copies of NPSP or PMM custom metadata records, delete default handler rows, or modify skew and rollup key fields.

Flows on NPSP objects

  • Your record-triggered flow and NPSP's handlers run in the same save. Check in a debug log that the fields your flow reads (Primary Contact, contact roles, payments) are set at the point your flow runs.
  • Gift Entry and the Data Importer commit hundreds of rows in one transaction. Automation on Opportunity, Payment or Allocation must be bulk-safe: no queries or DML in loops, one collection DML per object. Test with a 250-row batch.
  • Creating Contacts in a flow makes NPSP create a Household Account for each in the same transaction, which spends limits your flow does not see.
  • Validation rules on Account and Contact can fail NPSP's rollup updates silently (the error lands in npsp__Error__c). Give such rules a bypass for automated contexts.
  • Several test saves in one anonymous Apex script or one test method can run out of queries, because each save on Contact-like objects fires many package queries (field-reported: "Too many SOQL queries: 101" in five agent contexts). Keep to one to three cases per transaction; a rollback does not refund limits.

One package lesson, observed in a developer org:

  • Never deploy subscriber copies of managed custom metadata records (for example PMM feature gates or NPSP rollup definitions). A copy without the namespace on the record name creates a duplicate DeveloperName that can make the package's own trigger fail on every insert. Edit managed records in Setup; remove a stray copy with a destructive deploy. Check: query the type for duplicate DeveloperName values.

The platform lessons that used to be listed here apply to every org and moved: a handled fault that saves part of a collection, subflow faults, date conversion in GMT and debug runs that commit are in salesforce-flow/references/gotchas.md (items 1, 3, 4 and 6); a new field with no field access is in salesforce-build/references/access-and-sharing.md.

Surfaces

TaskSupported path
Recalculate one donorRecalculate Rollups button (async, minutes)
Recalculate everyoneNPSP Settings > Bulk Data Processes > Rollup Donations Batch
Backfill payments or default allocationsCreate Missing Payments; Batch Create Default Allocations
Add a customizable rollupConfigure Rollups UI, filter group first
Add a field to Gift EntryData Import field, Advanced Mapping entry, template field
Turn on RD2Enablement wizard with a dry run first; treat as one-way (verify)

A path that starts with another skill's name, such as salesforce-flow/references/gotchas.md, is relative to the skills folder that holds this skill.

Sources

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.