Skip to main content

​
Important Integration Nuances

This document provides an overview of important behaviors, considerations, and nuances in the WeGive Salesforce integration. Understanding these details is crucial for effective setup, configuration, and troubleshooting.

​
Data Direction and Synchronization

The integration supports bidirectional synchronization for most objects, allowing data to flow between WeGive and Salesforce.

​
Sync Direction

  • Bidirectional Sync: Most objects support data flow in both directions
  • Pull Operations (Import): Data imports from Salesforce to WeGive on a per-integration schedule (default every 15 minutes, configurable via Pull frequency) using date-based filtering
  • Push Operations (Export): Data exports from WeGive to Salesforce with a delay for ordering, not throttling — 2.5 minutes for recurring donation (scheduled_donation) and Communication List Donor pushes, 5 minutes for every other object. The delay guarantees a recurring donation’s own push (which stamps its Salesforce ID) completes before its first linked gift transaction pushes. Integrations with Realtime push enabled (a per-integration, Nova-only flag, off by default) skip this delay entirely on a dedicated queue; ordering there is enforced by Redis locks instead. See IntegrationLog::queue().

​
Sync Order

WeGive syncs data in a specific order to maintain data dependencies:
  1. Households
  2. Donors (Contacts)
  3. Companies (Accounts)
  4. Campaigns
  5. Funds
  6. Pledges
  7. Transactions (Opportunities)

​
Special Sync Features

  • Merge Handling: Supports Salesforce contact and account merges via MasterRecordId
  • Incremental Sync: Uses LastModifiedDate filtering for efficient synchronization
  • Date-Based Filtering: Only syncs records modified since the last successful sync

​
Record Matching and Creation

The integration uses sophisticated matching logic to prevent duplicates while ensuring data consistency.

​
Matching Strategy

  • Primary Matching: Records are matched by their stored Salesforce ID
  • Email Matching: Contacts can be matched by email address if no Salesforce ID exists
  • Name Matching: Companies can be matched by name if no Salesforce Account ID exists

​
Automatic Creation

  • Missing Prerequisites: Parent records (donors, campaigns, funds) are automatically created before child records
  • Cascading Push: If a transaction references a donor without a Salesforce ID, the donor is pushed first
  • Duplicate Prevention: Existing records are updated rather than creating duplicates

​
Update vs Create

  • If Salesforce ID exists: Update the existing record
  • If no Salesforce ID: Create a new record (after checking for matches)

​
Custom Field Support

WeGive provides extensive support for custom fields through the mapping rules system.

​
Mapping Rules

  • Dynamic Mapping: Custom fields can be mapped through the mapping rules interface
  • Directional Control: Mappings can be:
    • Bidirectional (sync both ways)
    • Import only (Salesforce → WeGive)
    • Export only (WeGive → Salesforce)
  • Value Types: Supports literal values or computed values

​
Custom Objects

  • Supported: Custom objects can be synced on request from WeGive
  • Requirements: Must return an ID and have appropriate relationship fields
  • Examples: Custom pledge objects, custom payout objects

​
Default Mappings

  • Built-in: Default mapping rules are defined in WeGive’s code
  • Override: Defaults can be overridden via the “Mapping Rules” interface
  • Flexibility: Organizations can add new mappings for specific needs

​
Address Handling

Address management requires careful consideration of formats and field types.

​
Address Types

  • Mailing Address: Primary address for the donor/organization
  • Billing Address: Secondary address for billing purposes

​
Field Mapping

  • Concatenation: Address line 1 and line 2 are concatenated for Salesforce street fields
  • State/Country: Some picklist compatibility issues may exist
  • NPSP Addresses: WeGive does not sync to NPSP’s expanded address object

​
Bidirectional Sync

  • Accounts: Address state and country fields sync both ways
  • Contacts: State and country have picklist constraints that may limit sync

​
Financial Data and Currency Handling

Financial data synchronization requires careful handling of amounts and currencies.

​
Amount Conversion

  • WeGive: Stores amounts in cents as integers (e.g., 10000 = $100.00)
  • Salesforce: Stores amounts in dollars as decimals (e.g., 100.00)
  • Conversion: Automatically converts between cents and dollars during sync

​
Fee Tracking

  • Separate Fields: Transaction fees and donor-covered fees tracked separately
  • Payout Summaries: Detailed financial breakdowns for payout records
  • Fee Types: Processing fees, platform fees, and other fees

​
Payment vs Opportunity Focus

  • Uses Payments Flag: When enabled, WeGive syncs based on Payments, not just Opportunities
  • Multiple Payments: A single Opportunity with multiple Payments creates multiple Transactions in WeGive
  • Payment Object: Uses npe01__OppPayment__c when uses_payments is enabled

​
Recurring Donations and Pledges

  • WeGive Control: WeGive maintains control over amount, start/end dates, and frequency
  • One-Way Fields: Changes to these fields in Salesforce won’t propagate to WeGive
  • Active Only: By default WeGive only pulls recurring donations where npsp__Status__c = 'Active'; the per-integration sync_all_recurring_donations column (default off) can be flipped to pull recurring donations regardless of status.

​
Custom Financial Objects

  • Custom Pledges: Requires custom object in Salesforce (available in WeGive managed package)
  • Custom Payouts: Requires custom object in Salesforce (available in WeGive managed package)

​
Soft Credits

  • Consolidation: Account Soft Credits and Partial Soft Credits are consolidated into one WeGive object
  • Contact Roles: Opportunity Contact Roles do not sync to Soft Credits

​
Record Types

  • Configuration: Use the API name when configuring record types for opportunities or custom objects
  • Example: “Donation” not “Donations”

​
Household Management

Household management is crucial for organizations using NPSP.

​
Automatic Assignment

  • Individual Donors: Automatically assigned to households based on salesforce_account_id
  • Record Type: Households use the “Household Account” record type in Salesforce

​
Primary Member

  • Tracking: Primary household member tracked via npe01__One2OneContact__c
  • Updates: Primary member status syncs bidirectionally

​
Membership Changes

  • Dynamic: Household membership updates when donor account associations change
  • All Members: All contacts with matching AccountId are added as household members

​
Error Handling and Logging

Comprehensive error handling and logging help maintain data integrity.

​
Processing

  • Batch Processing: Large data sets processed in batches with progress logging
  • Exception Handling: Descriptive error messages for troubleshooting

​
Integration Logs

  • Activity Tracking: All sync activities logged in WeGive
  • Log Types: Successes, errors, and warnings
  • Visibility: Administrators can review logs to monitor sync status

​
Failed Records

  • Ignored Integrations Table: Lists records that repeatedly failed to sync
  • Integration Locks: Records that fail repeatedly are locked from re-attempt
  • Manual Unlock: Administrators can unlock records to retry sync

​
Special Organization Handling

Some organizations require custom implementations.

​
Custom Implementations

  • Organization-Specific: Some organizations have custom field mappings
  • Example Organizations: Custom configurations for specific needs

​
Flexible Configuration

  • Custom API Names: Fund API names can be customized per organization
  • Record Type Detection: Automatic detection and filtering by Salesforce record types
  • Object Naming: Some organizations use custom object names (e.g., payout objects)

​
Events and Fundraising

Events, ticket types, registrations, and registration line items sync to four WeGive4SF custom objects. Unlike most objects in this integration, they are push-only: WeGive writes to Salesforce and never reads these objects back. Edits made in Salesforce are overwritten on the next push. Full field detail is on the Events, Tickets & Registrations page.

​
Dependency Management

  • Parents first: Before pushing a child record, WeGive pushes any parent that lacks a Salesforce ID. A registration pushes its event, its ticket types, and the registrant before itself.
  • Four settings: Events, tickets, registrations, and registration tickets each have their own push setting. Disabling tickets while leaving registration tickets enabled causes registration ticket pushes to fail.
  • Deletions: Events, tickets, and registrations are never deleted in Salesforce; WeGive stamps a deleted date instead. Registration line items that no longer exist in WeGive are deleted from Salesforce on the next registration push.

​
Registrations

  • Multiple ticket types: A registration containing more than one ticket type has no ticket lookup on the registration record. Ticket-level detail lives on wegive__Event_Registration_Ticket__c.
  • Company registrants: The registration object has a Contact lookup only. Company registrations arrive with an empty Contact lookup and are identifiable by wegive__WeGive_Donor_Id__c.
  • Transaction ID: wegive__Transaction_Id__c is WeGive’s transaction ID as text, not a lookup to the Opportunity.

​
Fundraising Features

  • Peer-to-Peer: Campaign fundraisers support peer-to-peer fundraising tracking
  • Parent-Child: Fundraiser hierarchies are maintained

​
Ticket Management

  • Price Conversion: Ticket prices are converted from cents to dollars on push
  • Mapping rules: Registration line items are the only event object that supports custom mapping rules

​
Campaign and Marketing Features

Campaign management requires special consideration.

​
Campaign Members

  • Bidirectional Sync: Campaign Members sync both ways (optionally configurable)
  • Automatic Creation: Created when contacts receive messages, make payments, or create recurring/pledge plans
  • Custom Fields: Custom field mapping for Campaign Members is currently not available

​
Campaign Hierarchies

  • Single Parent: When creating a campaign in WeGive, you can select one parent campaign
  • Parent-Child: Parent-child relationships are maintained in both systems

​
Communication Lists

  • Special Field Mapping: Handled through CL_{list_id}_{slug} field patterns
  • Subscription Tracking: Donor subscriptions tracked in both preference objects and Contact fields

​
Performance Considerations

The integration is designed for efficiency and scale.

​
Optimization

  • Incremental Sync: Date-based filtering for efficient synchronization
  • API Limits: Respects Salesforce API limits with appropriate timeouts
  • Relationship Loading: Eager loading of related models to minimize database queries

​
Batch Processing

  • Large Datasets: Handled in batches to prevent timeouts
  • Progress Tracking: Batch progress logged for monitoring

​
Security and Authentication

Security is crucial for maintaining a reliable integration.

​
Authentication

  • OAuth 2.0 Authorization Code flow: WeGive connects through an External Client App in your org and authorizes as the integration user. See External Client App and Connection Setup.
  • Refresh tokens: WeGive stores the access and refresh tokens encrypted and refreshes automatically. No Salesforce password is stored. If refresh fails repeatedly, the integration is disabled and must be reconnected.
  • Token Caching: Access tokens are cached for up to 10 minutes, never past their expiry, to reduce API calls
  • Credential Protection: Sensitive fields are hidden in API responses
Integrations connected before the External Client App flow used the OAuth username-password flow with a Connected App. That path is deprecated. Existing connections continue to work through the Legacy Username and Legacy Password fields on the Connection tab, but new connections and reconnections use Connect with OAuth and the External Client App flow described above. Leave the legacy fields blank on any new setup.

​
API Field Visibility

  • Critical: All integration fields must be visible to the API in Salesforce
  • Admin Access: Required even for system administrators
  • Impact: Hidden fields will cause sync errors

​
Environment Matching

  • Sandbox vs Production: Connection only works if both WeGive and Salesforce are the same type
  • Production to Production: Production WeGive must connect to Production Salesforce
  • Sandbox to Sandbox: Sandbox WeGive must connect to Sandbox Salesforce

​
Ongoing Management

  • Monitor integration logs regularly
  • Review failed records in the “Ignored Integrations” table, and unlock and retry them once the underlying cause is fixed
  • Keep mapping rules up to date as fields change in either system
  • Re-authorize the Test dashboard after every Sandbox refresh; a refresh removes the External Client App, Remote Site, trigger handler exclusions, and permission set assignment on the Sandbox side
When troubleshooting a failed sync, check the integration log for the specific error first, then verify the field is visible to the API for the integration user, that Salesforce IDs exist on prerequisite records, and that authorization is still valid.