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 every 15 minutes using date-based filtering
  • Push Operations (Export): Data exports from WeGive to Salesforce with a 5-minute delay for optimization

​
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: WeGive only pulls active recurring donations from Salesforce

​
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

The integration provides robust support for events and fundraising activities.

​
Dependency Management

  • Automatic Parent Creation: Events, tickets, and registrations handle dependencies automatically
  • Registration Flow: Event registrations automatically create/link donors, events, and tickets

​
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 converted from cents to dollars for Salesforce
  • Inventory: Ticket limits and availability tracked

​
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

  • OAuth2: Uses Salesforce OAuth2 password flow for authentication
  • Token Caching: Access tokens cached for 10 minutes to reduce API calls
  • Credential Protection: Sensitive fields hidden in API responses

​
Post-Summer 2023 Requirement

  • New Instances: For Salesforce instances created after Summer 2023, OAuth username-password flow must be explicitly enabled
  • Settings Location: Salesforce Setup → Identity → OAuth and OpenID Connect Settings

​
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

​
Best Practices

​
Before Setup

  1. Ensure all required fields are visible to the API
  2. Enable OAuth username-password flow (for post-Summer 2023 instances)
  3. Match environment types (production-to-production or sandbox-to-sandbox)
  4. Review default mapping rules and plan customizations

​
During Configuration

  1. Map custom fields through the mapping rules interface
  2. Configure record types using API names
  3. Set up integration logs monitoring
  4. Test sync with a small data set first

​
Ongoing Management

  1. Monitor integration logs regularly
  2. Review failed records in the “Ignored Integrations” table
  3. Unlock and retry failed records as needed
  4. Keep mapping rules up to date as fields change

​
Troubleshooting

  1. Check integration logs for specific error messages
  2. Verify Salesforce IDs exist for all prerequisite records
  3. Ensure field visibility to API
  4. Confirm OAuth authentication is working
  5. Review batch processing logs for large data sets
  • Object-Specific Documentation: Detailed field mappings for each object type
  • Setup Guide: Step-by-step integration configuration
  • Mapping Rules: How to configure custom field mappings
  • Troubleshooting Guide: Common issues and solutions