​

Important Integration Nuances

The WeGive Salesforce integration has several important nuances that impact its setup, configuration, and data synchronization processes. Understanding these details is crucial for effective use and troubleshooting.

​

Data Direction and Synchronization

The integration supports bidirectional synchronization for most objects, allowing data to flow both ways between WeGive and Salesforce. This flexibility enables organizations to maintain data consistency across both platforms.

• Bidirectional Sync: Most objects support both import from and export to Salesforce
• Pull Operations: Import data from Salesforce to WeGive using date-based filtering, every 15 minutes
• Push Operations: Export WeGive data to Salesforce, creating or updating records, with a 5-minute delay for optimization
• Order of operations: WeGive syncs data in a specific order: households, donors, companies, campaigns, funds, pledges, and then transactions
• Merge Handling: Supports Salesforce contact and account merges via MasterRecordId

​

Record Matching and Creation

The integration employs sophisticated matching algorithms to prevent duplicate records while ensuring data consistency. When records are created or updated, the system automatically handles relationships and dependencies.

• Email Matching: Contacts are matched by email address if Salesforce ID is not present
• Automatic Creation: Missing parent records (donors, campaigns, funds) are automatically created during sync
• Duplicate Prevention: Existing records are updated rather than creating duplicates

​

Custom Field Support

WeGive’s integration provides extensive support for custom fields and objects, allowing organizations to tailor the integration to their specific needs. The mapping rules system offers flexibility in how data is synchronized between platforms.

• Dynamic Mapping: Custom fields can be mapped through the mapping rules system. Mappings can be bi-directional, pull only, or push only and integrate with a literal value or computed value
• Custom Field Values: WeGive custom field values are synchronized to corresponding Salesforce fields
• Custom Objects: Possible on request from WeGive. Salesforce custom objects must return an ID and have appropriate relationships to ensure synchronization
• Flexibility: Default mapping rules are defined within WeGive’s code and cover common use cases. These defaults can be overridden or new custom mappings can be added via the “Mapping Rules” interface

​

Address Handling

Address management in the integration requires careful consideration of various formats and standards. The system handles multiple address types and formats while maintaining data integrity.

• Multiple Address Types: Supports both mailing and billing addresses
• Address Concatenation: Address line 1 and 2 are concatenated for Salesforce street fields
• State/Country Validation: Comments in code indicate picklist compatibility issues with some fields
• WeGive does not sync to NPSP’s expanded address object

​

Payments, Amounts and Currency Handling

Financial data synchronization is a critical aspect of the integration, requiring careful handling of currencies, amounts, and related transactions. The system manages various financial scenarios while maintaining accuracy.

• Cent Conversion: WeGive stores amounts in cents, converted to dollars for Salesforce
• Fee Tracking: Separate fields for transaction fees and donor-covered fees
• Payout Summaries: Detailed financial breakdowns for payout records
• Payment focus: WeGive primarily syncs based on Payments, not just Opportunities. A single Salesforce Opportunity with multiple Payments will be reflected as multiple, individual Transactions in WeGive if the uses_payments flag is enabled
• Recurring Donations (and Pledges): WeGive maintains control over key fields like amount, start/end dates, and frequency. Changes to these fields in Salesforce will not be propagated to WeGive. WeGive only pulls active recurring donations from Salesforce
• Custom Pledges: Requires a corresponding custom object in Salesforce, optionally available in the WeGive managed package
• Custom Payouts: Requires a corresponding custom object in Salesforce, optionally available in the WeGive managed package
• Soft Credits: From Salesforce’s Account Soft Credit and Partial Soft Credit objects are consolidated into a single SoftCredit object in WeGive. Opportunity Contact Roles do not sync to Soft Credits
• Types: When configuring record types for opportunities or custom objects, it is important to use the API name

​

Household Management

Household management is a crucial aspect of the integration, particularly for organizations using NPSP. The system handles complex household relationships and membership changes efficiently.

• Automatic Assignment: Individual donors are automatically assigned to households based on salesforce_account_id
• Primary Member: Household primary member is tracked via npe01__One2OneContact__c
• Membership Sync: Household membership is updated when donor account associations change

​

Error Handling and Logging

The integration includes comprehensive error handling and logging capabilities to help administrators monitor and troubleshoot synchronization issues. This system ensures transparency and helps maintain data integrity.

• Batch Processing: Large data sets are processed in batches with progress logging
• Exception Handling: Comprehensive error handling with descriptive error messages
• Integration Logs: All integration activities are logged for troubleshooting in WeGive to monitor sync activities, including successes, errors, and warnings
• “Ignored Integrations Table”: Lists records that have repeatedly failed to sync
• Integration Locks: When a record is repeatedly failing to sync, that record will be locked from re-attempt. Administrators can view the locked records, and remove the locks to attempt a resync on that record

​

Special Organization Handling

Some organizations require custom implementations to meet their specific needs. The integration supports this through flexible configuration options and custom field mappings.

• Custom Implementations: Some organizations (e.g., ID 1784288, 1784269) have custom field mappings
• Flexible API Names: Fund API names can be customized per organization
• Record Type Detection: Automatic detection and filtering by Salesforce record types

​

Event and Fundraising Dependencies

The integration provides robust support for events and fundraising activities, handling complex relationships between various components while maintaining data consistency.

• Automatic Parent Creation: Events, tickets, and registrations have dependency management
• Registration Flow: Event registrations automatically create/link donors, events, and tickets
• Fundraiser Integration: Campaign fundraisers support peer-to-peer fundraising tracking
• Ticket Price Conversion: Ticket prices converted from cents to dollars for Salesforce
• OAuth2: Uses Salesforce OAuth2 password flow for authentication
• Token Caching: Access tokens are cached for 10 minutes to reduce API calls
• Credential Protection: Sensitive fields are hidden in API responses

​

Campaigns & Marketing Considerations

Campaign management and marketing activities require special consideration in the integration, with support for various campaign types and marketing-related features.

• Campaign Members: Are synced bi-directionally (optionally configurable) and are created in WeGive when a contact is sent a message, creates a payment, or creates a recurring plan or pledge plan. Custom field mapping for Campaign Members is currently not available
• One Parent: When creating a campaign in WeGive, you can select a single parent campaign from the existing campaigns in salesforce, and assign that campaign as a parent-child campaign relationship
• Communication List Subscriptions: Handled through special CL_{list_id} field mappings

​

Performance Considerations

The integration is designed to handle large volumes of data efficiently while respecting system limitations and maintaining performance.

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

​

Technical and Security Considerations

Security and technical aspects are crucial for maintaining a reliable and secure integration between the two platforms.

• Integration Architecture: The integration uses Salesforce’s OAuth2 password flow for authentication and caches access tokens for 10 minutes to reduce API calls
• After Summer 2023: For Salesforce instances created after Summer 2023, the OAuth username-password flow must be explicitly enabled to ensure a successful connection
• API Field Visibility: It is essential that all fields involved in the integration are visible to the API in Salesforce, even for system administrators, to prevent synchronization errors
• Sandbox vs Production: The connection will only be successful if both the WeGive and Salesforce instances are the same type (production or sandbox)

By understanding these nuances, Salesforce administrators and WeGive users can more effectively configure, manage, and troubleshoot the integration, ensuring accurate and consistent data flow between the two platforms.