> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wegive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dashboard Settings Reference

> Every control on the Salesforce NPSP Setup screen in the WeGive dashboard: Connection, Sync Configuration, Mapping Rules, and Actions

The Salesforce integration is configured on one screen in the WeGive dashboard: **Settings > Integrations > Salesforce NPSP**. The screen has four tabs. This page lists every control on each tab, what it does, and when in an implementation you use it. For the order of operations, see the [Sandbox-First Implementation Guide](/external/onboarding/salesforce-npsp/install-setup/implementation-guide). For what each setting means for the data, see [Configuration Options](/external/onboarding/salesforce-npsp/configuration-options).

The header above the tabs shows three status badges. Before setup they read **Disabled**, **Not connected**, and **No sync has run yet**; on a healthy integration they read **Enabled**, **OAuth connected**, and **Last synced** with a timestamp. Those three badges are the fastest health check for the integration.

<Note>
  Each dashboard (Test and Live) has its own copy of this screen. Nothing set here carries between them.
</Note>

## Connection tab

Save API credentials, authorize with Salesforce, and verify connectivity. This is the first tab you complete.

| Control | What it does |
| - | - |
| **Enable Integration** toggle | Turns Salesforce synchronization on or off for the organization. When off, no record changes are queued for push and no scheduled pulls run. The toggle stays locked until a connection test has passed, and you should also leave it off until Sync Configuration and Mapping Rules are set. |
| **Client ID** | The Consumer Key from the External Client App in your Salesforce org. |
| **Client Secret** | The Consumer Secret from the same app. Stored encrypted; displayed masked after saving. |
| **Legacy Username** and **Legacy Password** | Fallback fields for the deprecated username-password authorization flow. Leave both blank for a new connection. They exist only for integrations connected before the External Client App flow, and the password field expects the Salesforce password with the security token appended. |
| **Save** | Saves the credentials. Save before authorizing. |
| **Connect with OAuth** | Starts the OAuth authorization. Salesforce prompts you to log in and approve access. Sign in as the integration user, not as yourself. After authorization the header shows **OAuth connected** and this button becomes **Disconnect OAuth**. |
| **Test Connection** | Verifies that WeGive can reach the org with the saved credentials and token, and reads the org's record types. Unavailable until credentials are saved. Run it after connecting, before enabling the integration, and any time the connection is suspect. |
| **Sync** | Opens a Sync dialog instead of running immediately. Same as **Sync with Salesforce** on the Actions tab. Unavailable until the integration is connected. See the Sync dialog section below for what it asks. |
| **Disconnect OAuth** | Revokes the stored token. Use it when re-authorizing as a different user, after a Sandbox refresh, or when rotating the Consumer Secret. Credentials remain saved; only the authorization is removed. |

WeGive detects whether the authorized org is a Sandbox or Production. A Test dashboard authorizes only against a Sandbox and a Live dashboard only against Production. See [External Client App and Connection Setup](/external/onboarding/salesforce-npsp/install-setup/connect-app-setup) for the Salesforce-side prerequisites.

## Sync Configuration tab

Everything that controls what syncs and how. The tab has one **Save** button at the top; changes in any section are saved together.

### Core Settings

| Control | What it does |
| - | - |
| **Two-way sync** | Described on screen as the master switch for pulling: changes in Salesforce update WeGive records. See Known differences below. |
| **CRM sync** | Described on screen as the master switch for pushing: changes in WeGive update Salesforce records. See Known differences below. |
| **Track donations**, **Track donors**, **Track recurring donations**, **Track campaigns**, **Track designations** | Described on screen as coarse per-domain switches. See Known differences below; rely on the per-object Pull and Push toggles to control what syncs. |

### Entity Pull & Push

One **Pull** and one **Push** toggle per object. Pull imports from Salesforce; Push exports to Salesforce. Objects with only a Pull toggle (companies, merge contacts, merge accounts) are read from Salesforce but never written.

| Object | Pull | Push | Notes |
| - | - | - | - |
| Donors (Contacts) | Yes | Yes | |
| Households | Yes | Yes | The Push toggle currently has no effect; households are not pushed. See Known differences below. |
| Companies (Organization Accounts) | Yes | | Companies are pushed as part of donor pushes. |
| Campaigns | Yes | Yes | |
| Funds (GAUs) | Yes | Yes | |
| Fund allocations | Yes | Yes | Allocations are pushed as part of each transaction and recurring donation push; the Push toggle here does gate the allocation sync, alongside the organization's fund allocation setting. See Known differences below. |
| Recurring donations | Yes | Yes | |
| Transactions (Opportunities and Payments) | Yes | Yes | |
| Soft credits | Yes | Yes | Account and Partial Soft Credits. Opportunity Contact Roles have their own toggle further down. |
| Campaign donors (Campaign Members) | Yes | Yes | |
| Merge contacts | Yes | | Detects Contacts merged in Salesforce and merges the matching WeGive donors. |
| Merge accounts | Yes | | Same for Accounts. |
| Pledges | Yes | Yes | Requires the WeGive4SF pledge object. |
| Communication list donors | Yes | Yes | |
| **Push tag memberships to Salesforce** | | Yes | Default off. Gates both tag definitions and tag assignments. Assignments go through the bulk upload pipeline, never in real time. Each tag must also have its own **Sync to CRM** toggle turned on. See [Tags](/external/onboarding/salesforce-npsp/data-mapping/tag). |
| **Pull tag memberships from Salesforce** | Yes | | Default off. Mirrors tag assignments made in Salesforce back into WeGive. |
| **Push payment methods to Salesforce** | | Yes | Default off. Pushes cards and bank accounts to a custom payment-method object configured under Payment Method Push below. |

### WeGive4Salesforce Pushes

Push toggles for the objects that exist only because the WeGive4SF package is installed. All are push-only.

| Control | Salesforce object |
| - | - |
| **Push payouts** | `wegive__Payout__c` |
| **Push communication lists** | `wegive__Communication_List__c` |
| **Push campaign fundraisers** | `wegive__Fundraiser__c` |
| **Push campaign events** | `wegive__Event__c` |
| **Push campaign event tickets** | `wegive__Event_Ticket__c` |
| **Push campaign event registrations** | `wegive__Event_Registration__c` |
| **Push campaign event registration tickets** | `wegive__Event_Registration_Ticket__c` |

The four event toggles depend on each other; enable them top to bottom. See [Events, Tickets & Registrations](/external/onboarding/salesforce-npsp/data-mapping/event).

### Deleted Record Sync

When a toggle here is on, records deleted in Salesforce are also deleted in WeGive on the next pull. One toggle each for donors (Contacts), households, companies, campaigns, funds (GAUs), fund allocations, transactions (Opportunities), and recurring donations.

<Warning>
  These are one-directional and destructive on the WeGive side. A Contact deleted in Salesforce removes the donor, and their history, from WeGive. Leave them off unless Salesforce is the system of record for deletions and the organization understands the consequence.
</Warning>

### Contact Sync Options

**Sync contacts with emails only.** Imports only Salesforce Contacts that have at least one email address. On by default. Turning it off imports every Contact in the org on the next pull.

### Sync Schedule

**Pull frequency (minutes).** How often the scheduled pull runs. The default is 15 minutes. Pushes are not scheduled; they run within about five minutes of a change in WeGive.

### Stage Names

**Stage Names, Push.** The Opportunity Stage WeGive writes for each gift status when pushing: **Success stage name**, **Refunded stage name**, **Pending stage name**, **Failed stage name**. These values are also recognized on pull. They must match your org's Stage picklist exactly.

**Stage Names, Pull.** Additional Stage values to recognize for each status when importing gifts: **Success stages**, **Pending stages**, **Refunded stages**, **Failed stages**. Add one value at a time. Stages not listed fall back to the push stage names, then to built-in Salesforce defaults. A Stage that matches nothing imports as **failed**, so if imported gifts show as failed in WeGive, look here first.

### Payment Method Labels

**Card payment method name**, **Bank payment method name**, **Paypal payment method name.** The values WeGive writes to the Payment Method field on Payments and Opportunities. Match them to your org's existing picklist values.

### Payment Method Push

Used only when **Push payment methods to Salesforce** is on.

| Control | What it does |
| - | - |
| **Payment method object API name** | The custom object that stores payment methods, fully qualified with namespace. |
| **Card type picklist value** | Written to the object's Type picklist for cards. Restricted picklist; must match exactly. |
| **Bank type picklist value** | Same, for bank accounts. |
| **Upsert external-id field** | Optional. When set and a Payment Methods mapping rule supplies a value for it, the first push upserts on that field instead of inserting, which prevents duplicates. Later updates use the stored record ID. |

### Record Type Configuration

| Control | What it does |
| - | - |
| **Service revenue record type ID** | The Opportunity record type ID WeGive assigns to non-tax-deductible transactions it pushes. |
| **Tax deductible record type ID** | The Opportunity record type ID WeGive assigns to donations it pushes. |
| **Household record type name** | The Account record type name for households. Default `Household Account`. |
| **Non-household record type name** | The Account record type name for organizations. Default `Organization`. |
| **Primary contact column** | The Account field that identifies the primary household contact. NPSP's default is `npe01__One2OneContact__c`. |

### Opportunity Record Types

**Service Revenue Record Types.** Record types treated as non-tax-deductible revenue on import. **Hidden Record Types.** Record types that are never imported and never shown to donors. Add record type names one at a time. Use these to keep grants, in-kind gifts, pledges tracked as Opportunities, proposals, and similar non-gift Opportunities out of WeGive.

### Contact Role Soft Credits

**Pull contact role soft credits.** Imports soft credits from `OpportunityContactRole` records in addition to Account and Partial Soft Credits. Off by default; most NPSP orgs do not need it.

### Processing Options

| Control | What it does |
| - | - |
| **Send processing ACH as success** | Treats ACH transactions still in processing as successful when pushing to Salesforce, so the Opportunity closes immediately rather than after bank settlement. |
| **Push both Contact and Account on recurring donations** | When on, an individual's recurring donation also carries the household Account on `npe03__Organization__c` so NPSP can roll up household giving, and a company's recurring donation also carries the primary individual's Contact on `npe03__Contact__c`. When off, each recurring donation carries one link only. |

## Mapping Rules tab

Field-level mappings between WeGive and Salesforce, grouped by category and then by object. Each object shows its rule count and expands to the rule list. Every rule shows the Salesforce field, the WeGive field, its direction (**Bi-directional**, **Import only**, or **Export only**), and whether it is a saved rule or a default.

| Category | Objects |
| - | - |
| **Supporters** | Accounts (organizations), Individuals (Contacts), Households |
| **Donations** | Opportunities, Payments, Recurring Plans, Pledges, Campaign Donors, Soft Credits, Payment Methods |
| **WeGive Custom Objects** | Campaign Events, Campaign Event Tickets, Campaign Event Registrations, Campaign Fundraisers, Communication Lists, Communication List Donors, Payouts |
| **Campaigns and Funds** | Campaigns, Funds |

Each object has its own **Add Rule** and **Save** buttons. A new rule needs the Salesforce field API name, the WeGive field API name, and a direction. The valid WeGive field names for each object are listed on that object's page under [Data Mapping](/external/onboarding/salesforce-npsp/data-mapping/overview).

<Warning>
  Rules added to Campaign Events, Campaign Event Tickets, or Campaign Event Registrations are saved but not applied on push; only Campaign Event Registration Tickets honor custom rules. Use WeGive custom fields with a Salesforce API name for those objects instead. See [Events, Tickets & Registrations](/external/onboarding/salesforce-npsp/data-mapping/event#registration-tickets).
</Warning>

Before mapping a custom Salesforce field, confirm the integration user has read and edit field-level access to it. A rule that targets a field the user cannot see fails the whole record on push. If you add a field in Salesforce and it does not appear as an option, run **Clear Describe Cache** on the Actions tab.

## Actions tab

On-demand maintenance.

| Control | What it does |
| - | - |
| **Sync with Salesforce** | Opens a Sync dialog instead of running immediately. Same as **Sync** on the Connection tab. See the Sync dialog section below. |
| **Clear Describe Cache** | Discards WeGive's cached copy of your org's object and field metadata and re-fetches it. Run this after adding custom fields, changing field types, or adding picklist values in Salesforce so the change is visible to mapping rules and pushes. Takes a few seconds. **View describe cache** shows what WeGive currently holds. |

### Sync dialog

Both the Connection tab's **Sync** button and the Actions tab's **Sync with Salesforce** button open the same dialog rather than running a sync immediately. It asks two things before queuing the job:

| Control | What it does |
| - | - |
| **Sync Mode** | **Sync all records** re-runs a full historical pull for the selected data set, ignoring what has already synced. **Sync records since last update** only pulls records changed since the last successful sync. This option only appears once the integration has a previous sync to compare against; a first-ever sync only offers Sync all records. |
| **Data Set** | Which object type to sync: All entities, or a specific one (Households, Donors, Companies, Campaigns, Designations/GAUs, Fund allocations, Recurring donations, Pledges, Transactions, Campaign donors, Soft credits, Contact role soft credits, Communication list donors, Merge donors, Merge companies, and the Deleted-record variants of most of the above). Tag memberships is an additional option when **Pull tag memberships from Salesforce** is enabled. |

Confirming queues the job in the background; you can navigate away while it runs.

## Known differences between the screen and behavior

The data mapping pages describe what the integration does; this page describes what the screen shows. Where the two differ, the mapping pages are the reference. Current differences:

* Rules added to Campaign Events, Campaign Event Tickets, or Campaign Event Registrations on the Mapping Rules tab are saved but not applied on push, and the Bi-directional and Import only directions have no effect on any of the four push-only event objects. See [Events, Tickets & Registrations](/external/onboarding/salesforce-npsp/data-mapping/event#registration-tickets). This is a known issue.
* Rules added to Communication Lists, Communication List Donors, or Campaign Fundraisers are likewise saved but not applied; those objects push a fixed field set. See [Communication Lists](/external/onboarding/salesforce-npsp/data-mapping/communication-list) and [Fundraiser](/external/onboarding/salesforce-npsp/data-mapping/fundraiser). This is a known issue.
* The **Push households** toggle under Entity Pull & Push has no effect. Households are never pushed to Salesforce; see [Account](/external/onboarding/salesforce-npsp/data-mapping/account#household-salesforce-id-origin). This is a known issue.
* The default Pledge rules seeded on every new integration reference fields that do not exist on `wegive__Pledge__c`, so pledge pushes fail until those rules are deleted. See [Pledge](/external/onboarding/salesforce-npsp/data-mapping/pledge). This is a known issue.
* The **Push fund allocations** toggle does gate the allocation push. `Salesforce.php` checks `$this->integration->push_fund_allocations` (alongside the organization's `enable_fund_allocations` setting) before calling `syncAllocationsToSF()` in all three push paths: the scheduled-donation push (\~line 4382), transaction create (\~line 4930), and transaction update (\~line 4838). The dashboard's save validation (`UpdateSalesforceRequest::withValidator()`) also rejects turning this toggle on unless **Push transactions** or **Push recurring donations** is also on, since allocations only ride along with one of those two parent pushes — confirming the toggle is a real, enforced gate, not a no-op.
* **Two-way sync**, **CRM sync**, and the five **Track** switches are stored as integration settings (`crm_sync`, `two_way_sync`, `track_donations`, `track_accounts`, `track_donors`, `track_recurring_donations`, `track_campaigns`, `track_designations` on `salesforce_integrations`) but are not read anywhere in `app/Integrations/Salesforce.php`, `app/Models/SalesforceIntegration.php`, or `app/Processors/SalesforceOauth.php`. Those same column names are read and enforced on a different integration — `NeonIntegration.php` gates several methods behind `$this->track_donors`, `$this->enabled`, and `$this->crm_sync` — so the fields are functional in that CRM's code path but are confirmed dead/unused for Salesforce specifically. The per-object Pull and Push toggles are what actually gate each Salesforce object.

## Related screens

Three other screens in the dashboard matter during implementation and support:

* **Settings > Integrations > Integration Logs.** Every queued job, with successes, warnings, and errors. Entry types are `create` and `update` (one record pushed), `pull` (a scheduled or manual incremental pull), `pull-all` (a full pull), and `push-missing` (a sweep for records that never reached Salesforce). Only one push per record is queued at a time; further edits while it is pending do not add entries. This is the sync log referenced throughout these docs.
* **Settings > Integrations > Integration Locks.** Records that failed repeatedly and are locked from retry. Unlock a record here after fixing the underlying cause.
* **Settings > Communications > Triggers.** Triggered messages (receipts, welcome emails, recurring notices). Pause these before the first data pull; see the [Implementation Guide](/external/onboarding/salesforce-npsp/install-setup/implementation-guide#phase-5-configure-the-integration-in-the-test-dashboard).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.