Salesforce NPSP Technical Documentation

This document explains the WeGive Salesforce NPSP integration, covering setup, configuration, debugging, and the data synchronization process.

1. Introduction

Overview

• Salesforce is a powerful CRM that serves as the "source of truth" for many organizations.

• WeGive's integration with Salesforce allows for bi-directional data syncing, enabling organizations to leverage data from multiple sources for a unified digital experience.

Purpose

WeGive pulls in data from various sources, including in-person payments, checks, stock donations, and more, ensuring a comprehensive view of donor activity. This positions WeGive as a Customer Data Platform (CDP).

Audience

It's designed for Salesforce administrators who need to understand, configure, and troubleshoot the integration who are also admin users of a WeGive account.

Conventions Used in This Manual

• Record Type API Names: When configuring record types for opportunities in Salesforce, it is important to use the API name and not the ID or display name. The API names are crucial for defining tax-deductible or hidden opportunities.

• Field-Level Permissions: The sources emphasize the need to ensure all fields used in the integration are visible to the API, even if a user has system administrator privileges. Hidden fields can lead to synchronization errors. This is mentioned repeatedly as a crucial aspect of the setup process.

• OAuth Username-Password Flow: It's explicitly stated that this flow must be enabled for instances created after Summer 2023. This highlights a specific requirement for newer Salesforce instances.

• Literal Value Fields: The integration allows the use of literal value fields for hard-coding specific values. This provides flexibility in data mapping.

• Error Messages in Integration Logs: The integration logs provide detailed error messages that are essential for troubleshooting. Understanding the error messages is a key part of debugging the integration.

• Ignored Integrations Table: This table highlights records that have repeatedly failed to sync, indicating potential issues that need to be addressed.

• Default Mapping Rules: There are default rules in the request body that override the visible mapping rules. These defaults are not currently displayed in the interface, which can lead to confusion if a user removes a mapping rule and the field still syncs because of the default.

• Custom Object API Names: Similar to record types, when setting up custom object mappings, it is necessary to use the object's API name. This allows flexibility in choosing which object in Salesforce to map data to.

---

2. Getting Started

System Requirements

To get started with the WeGive Salesforce integration, you will need:

• A Salesforce account with administrator privileges. This ensures you have the necessary permissions to create a connected app and configure the integration settings.

• A WeGive account with Salesforce integration enabled. Enabling the integration in WeGive provides access to the configuration and mapping settings.

The integration relies on the OAuth username-password flow. This flow requires that you provide WeGive with the Salesforce connected app's client ID and client secret, and a Salesforce system administrator username and password. This allows WeGive to securely access and interact with your Salesforce data.

For Salesforce instances created after Summer 2023, the OAuth username-password flow must be explicitly enabled. Failure to do so will prevent the integration from connecting.

The connection will only be successful if both the WeGive and Salesforce instances are the same type (production or sandbox). You cannot connect a production WeGive account to a sandbox Salesforce instance, or vice versa.

Installation & Setup

The setup process assumes you have already enabled the Salesforce integration within your WeGive account, granting you access to the configuration settings.

Once the integration is enabled in WeGive, follow these steps to set it up in Salesforce:

1. Create a Connected App in Salesforce:

• Log into your Salesforce account and navigate to Setup.

• In the navigation search bar, type "App Manager" and select it.

• Click "New Connected App".

• Fill out the following fields under "New Connected Apps":

  • Connected App Name: WeGive

  • API Name: WeGive

  • Contact Email: support@wegive.com

  • Enable OAuth Settings: Check On

  • Callback URL:

    • Production Environment: https://super.givelist.app

    • Sandbox Environment: https://api.sandbox.wegive.com

  • Selected OAuth Scopes: Highlight and move all selected OAuth scopes to the Available OAuth Scopes using the arrows.

  • Require Secret for Web Server Flow: Check On

  • Require Secret for Refresh Token Flow: Check On

• Click "Save" to create the connected app.

2. Access and Copy the Consumer Key and Secret Key:

• In the Lightning Experience App Manager, locate the newly created WeGive app and click "View".

• Scroll to the API (Enable OAuth Settings) section.

• Click on "Manage Consumer Details".

• Copy the Consumer Key (Client ID) and Consumer Secret (Client Secret). You will need to paste these into WeGive later.

3. Configure IP Relaxation Settings:

• Return to the Lightning Experience App Manager and click on the WeGive tab.

• This time, click "Manage" instead of "View".

• Click "Edit Policies".

• Under IP Relaxation, select "Relax IP restrictions".

4. Add WeGive API as a Remote Site:

• From the Salesforce Home screen, click on "Security" and then "Remote Site Settings".

• Click "New Remote Site".

• Under "Remote Site Edit", add the following:

  • Remote Site Name: wegive_api

  • Remote Site URL:

    • Sandbox Environment: https://api.sandbox.wegive.com

    • Production Environment: https://super.givelist.app

• Click "Save".

5. Enable Username-Password Flow for Instances Created After Summer 2023:

• If your Salesforce instance was created during or after Summer 2023, you need to enable the OAuth username-password flow. This is a crucial step for newer instances.

• To do this, navigate to "Setup" and search for "OAuth and Open ID Connect Settings".

• Find the WeGive connected app and enable "Username-Password Flow".

6. Configure Field-Level Security in Salesforce:

• It is essential to ensure that all fields involved in the integration are visible to the API. This includes fields used for mapping, filtering, and any other interaction between WeGive and Salesforce.

• To adjust field-level permissions, go to "Setup" and select "Object Manager".

• Choose the relevant object (e.g., Account, Contact, Opportunity) and then select "Fields".

• Click on the field you want to adjust and then select "Set Field Level Security".

• Make sure the field is visible to the WeGive integration.

7. Input Salesforce Details in WeGive:

• Navigate to the Integrations page in your WeGive account.

• Locate the Salesforce integration and click on "General Settings".

• Paste the Consumer Key (Client ID) and Consumer Secret (Client Secret) that you copied from Salesforce earlier.

• Enter your Salesforce system administrator username and password.

• Enter the correct Instance URL:

  • Sandbox Environment: https://test.salesforce.com/

  • Production Environment: https://login.salesforce.com/

• Click "Test Connection" to ensure the connection is successful.

• If the test succeeds, click "Sync Salesforce" to enable the integration.

The WeGive Salesforce integration syncs every 15 minutes to pull data from Salesforce. Pushes from WeGive to Salesforce happen with a 5-minute delay for optimization. You can also manually trigger a sync from the integration settings page in WeGive.

Remember to refer to the help article provided by WeGive for detailed guidance throughout the setup process.

Key Points to Remember:

• Use the correct API names for objects and record types when configuring settings in Salesforce.

• Thoroughly review the mapping rules to understand how data is transferred between WeGive and Salesforce. You can customize these rules to fit your organization's needs.

• Regularly check the integration logs in WeGive to monitor the sync process and troubleshoot any errors.

---

3. User Interface

The Salesforce integration interface in WeGive provides access to various settings and features for managing the integration. This screen lets you configure the connection, customize data mapping, monitor sync activity, and troubleshoot any issues that may arise.

Here are some key elements and functionalities you can expect to find on this screen:

General Settings

• Client ID and Client Secret: Fields for inputting the credentials you obtained when you created the connected app in Salesforce.

• Salesforce Username and Password: The credentials for a Salesforce system administrator account.

• Instance URL: Specify whether you are connecting to a Salesforce sandbox or production instance.

• Sync Settings: Options for customizing how and when data is synced between the two systems.

Mapping Rules

• This section allows you to define the relationships between WeGive fields and their corresponding Salesforce fields.

• You can view the default mappings and customize them to align with your data structure and integration requirements.

• Options for customization include:

  • Import/Export/Both: Specifying the direction in which data flows for each field.

  • Create Only: Sending data only when creating a new record in Salesforce.

  • Literal Value: Hardcoding specific values for certain fields.

Logs

• Provides a detailed log of all integration activities, including successes, errors, and warnings.

• The logs are crucial for troubleshooting sync issues and understanding the data flow between systems.

• You can filter the logs by various criteria to narrow down specific events or errors.

Test Connection and Sync Buttons

• The “Test Connection” button verifies that WeGive can establish a secure connection to your Salesforce instance using the provided credentials.

• The "Sync Salesforce" button initiates a manual data sync between WeGive and Salesforce.

Other Features and Information

• The integration screen might also display a summary of your current integration status (e.g., enabled or disabled).

• The screen might provide access to additional resources such as help articles or support contact information.

The exact appearance and functionalities of the WeGive Salesforce integration screen may vary depending on the specific version of WeGive you are using.

 

---

4. Default Mapping

Setting up object and field mapping in the WeGive Salesforce integration involves configuring how data from specific objects and fields in WeGive corresponds to objects and fields in Salesforce. This mapping ensures that information is transferred accurately and consistently between the two platforms.

In WeGive, the mapping is primarily managed through the “Mapping Rules” section of the Salesforce integration settings. This section provides a visual interface to define the relationships between WeGive objects and fields and their counterparts in Salesforce. You can add new mappings, modify existing ones, or disable mappings that you don't need.

Mapping Rules Customization Options in WeGive:

• Import/Export/Both: This setting controls the direction of data flow. You can choose whether a field should be imported from Salesforce to WeGive, exported from WeGive to Salesforce, or synchronized in both directions.

• Create Only: Select this option if you want a field to be populated in Salesforce only when a new record is created. This prevents updates from WeGive from overwriting existing data in Salesforce.

• Literal Value: This option lets you hardcode a specific value for a field in Salesforce. This is useful for fields that should have a consistent value, regardless of the data in WeGive.

Understanding Object Relationships:

You need to understand the default object relationships between WeGive and Salesforce. For example:

• A new donor in WeGive will create a new Contact and Account in Salesforce if that donor doesn’t exist in Salesforce. If the donor exists in Salesforce, the integration will sync the existing Salesforce data with the WeGive donor.

• WeGive Campaigns sync with Salesforce Campaigns.

• WeGive donations sync with Salesforce Opportunities.

• WeGive Recurring Plans sync with Salesforce Recurring Donations.

• WeGive Designations sync with Salesforce GAUs (General Accounting Units).

The integration syncs based on payments made in Salesforce. It will not function unless payments are being utilized within Salesforce.

Field-Level Security in Salesforce:

While WeGive handles the mapping rules, you need to ensure proper field-level security is configured within Salesforce. Even if your integration user is a system administrator, hidden fields in Salesforce will cause sync errors. To adjust field-level permissions:

• Go to Setup > Object Manager.

• Choose the relevant object and field.

• Select “Set Field Level Security”.

• Make sure the integration user has visibility to the field.

Custom Objects in Salesforce:

• Salesforce allows for the creation of custom objects, which are useful for mapping data from other systems or creating specialized data structures.

• Examples of custom object usage include event registrations and communication lists.

• WeGive is currently developing a UI to allow customers to create custom object mappings.

Key Considerations:

• When configuring settings in Salesforce, ensure you use the correct API names for objects and record types.

• Thoroughly review and understand the default mapping rules provided by WeGive. Modify them as needed to ensure that data is transferred correctly.

• Leverage the integration logs in WeGive to monitor the sync process and troubleshoot any errors.

By carefully configuring the object and field mapping in WeGive and Salesforce, and paying attention to field-level security settings in Salesforce, you can ensure smooth and accurate data synchronization between the two platforms, enabling a seamless flow of information between your fundraising and donor management systems.

Here are the default object mappings between WeGive and Salesforce:

Key Points about the Object Mappings:

• Transactions in WeGive are represented using a combination of Opportunities and Payments in Salesforce. WeGive primarily syncs based on Payments, not Opportunities.

• Custom Objects: The integration supports the use of custom objects in Salesforce. WeGive is actively developing a UI to allow customers to create custom object mappings, offering flexibility for nonprofits with unique data structures.

• Record Types in Salesforce: For Households, the integration specifically looks for Accounts with a Record Type of "Household Account". This ensures that only household accounts are synchronized.

• GAU Naming: Internally, WeGive refers to GAUs as "Funds," but this terminology is not exposed to users.

• Pledge Object: The integration for Pledges in WeGive only works if the organization has a corresponding "Pledge" object installed in Salesforce.

• Payouts: WeGive Payouts are synchronized to Salesforce, but the specific object used is not detailed in the provided sources. It's likely a custom object, as the sources mention a "compilePayoutPayload" function in the code.

It's crucial to understand that these are the default mappings. WeGive offers extensive customization options through Mapping Rules, allowing organizations to change how fields are mapped or disable the mapping entirely.

In addition to the direct object mappings, the integration considers related objects to ensure data consistency and maintain relationships. For instance, when syncing a Donation, the integration will take into account associated data like the Donor, Campaign, Recurring Plan, and Pledge, updating corresponding fields in Salesforce accordingly. This allows for a more comprehensive and accurate representation of giving data across both platforms.

 

Contacts

The WeGive-Salesforce integration creates a bidirectional link between Contacts in Salesforce and individual donors in WeGive. If a donor doesn’t exist in Salesforce, the integration will create a new Contact and Account for that donor. When a donor already exists in Salesforce, the integration syncs the existing data with WeGive.

WeGive prioritizes syncing on emails. If a Salesforce instance has Contacts without emails, they may not be synced. By default, the integration is configured to only sync Contacts with emails, ensuring that the primary means of communication is consistently maintained. However, you can customize this setting in WeGive to sync all Contacts, regardless of whether they have an email address.

WeGive pulls data from Salesforce every 15 minutes, including updates to Contacts. Pushes to Salesforce from WeGive occur on a 5-minute delay.

Here is a list of fields that are mapped by default between WeGive and Salesforce for individual donors. These mappings can be customized in the WeGive platform:

WeGive Field → Salesforce Field

• email_1 → npe01__HomeEmail__c

• salesforce_account_id → AccountId

• first_name → FirstName

• last_name → LastName

• gender → Gender__c

• communication_settings.opt_out → npsp__Do_Not_Contact__c

• preferred_email → npe01__Preferred_Email__c

• preferred_phone → npe01__PreferredPhone__c

Note:

• npe01__ is a namespace that might indicate fields specific to the Nonprofit Success Pack (NPSP) in Salesforce.

• The field communication_settings.email_enabled is commented out in the source code, meaning it might not be actively mapped by default.

In addition to these fields, WeGive syncs other related data, such as the donor’s household, donation history, and recurring donation information.

When importing recurring donations from Salesforce, the relationship between the recurring donation and the donor can be controlled by how the data is set up in Salesforce. To attribute a recurring donation to a Company (Account) in WeGive, ensure the record in Salesforce only has an Account ID associated with it. If it has both a Contact ID and an Account ID, the recurring donation will be related to the primary Contact instead.

To ensure a successful and efficient sync:

• Thoroughly review the default mapping rules and customize them based on your organization’s specific needs.

• Regularly monitor the integration logs in WeGive to identify and troubleshoot any potential issues.

 

Accounts (Companies and Households)

In the WeGive-Salesforce integration, Salesforce Accounts represent two types of supporters in WeGive: Companies and Households.

• Household Accounts in Salesforce specifically map to Households in WeGive.

• All other Account types in Salesforce (excluding Household Accounts) map to Companies in WeGive.

It's important to understand how this object relationship interacts with the integration between individual donors in WeGive and Contacts in Salesforce:

• When a new individual donor is added to WeGive and that donor does not yet exist in Salesforce:

  • The integration will create both a new Contact (representing the individual) and a new Account (representing their household) in Salesforce.

• If a new Company is created in WeGive:

  • The integration will create a new Account in Salesforce.

• Contacts in Salesforce can be associated with an Account. This relationship is mirrored in WeGive where individual donors can be members of a Household.

Default Field Mappings for Accounts:

The following fields are mapped by default between WeGive and Salesforce for Companies and Households. You can customize these mappings in WeGive:

WeGive Field → Salesforce Field

• name → Name

• salesforce_contact_id → npe01__One2OneContact__c (create only)

• billing_address.address_1 → BillingStreet

• billing_address.city → BillingCity

• billing_address.state → BillingState

• billing_address.postal_code → BillingPostalCode

• billing_address.country → BillingCountry

• office_phone → Phone

• fax → Fax

Key Considerations:

• The npe01__One2OneContact__c field is marked as "create only," meaning WeGive will only populate this field when initially creating a new Account in Salesforce. Subsequent updates to the salesforce_contact_id in WeGive will not be reflected in this Salesforce field.

• The integration relies on accurate record type identification in Salesforce to distinguish between Household Accounts and other Account types. Any misconfiguration in Salesforce could lead to data discrepancies.

By understanding the object relationships and field mappings for Accounts, you can ensure the integration effectively syncs Company and Household data between WeGive and Salesforce. Regularly reviewing the integration logs helps identify and address any inconsistencies or errors, ensuring data integrity and a comprehensive view of your supporters.

Campaigns

The WeGive-Salesforce integration establishes a bidirectional link between Campaigns in Salesforce and Campaigns in WeGive. This synchronization allows for the seamless flow of campaign data between the two platforms, ensuring consistency and facilitating comprehensive reporting and analysis.

Default Field Mappings:

The following fields are mapped by default between WeGive and Salesforce for campaigns. You can customize these mappings within the WeGive platform:

• name → Name

• parent_campaign.salesforce_id → ParentId (export only)

• start_date → StartDate

• end_date → EndDate

Note:

• The parent_campaign.salesforce_id mapping is marked as "export only," meaning WeGive will only send the parent campaign's Salesforce ID to Salesforce when exporting data. It won't import this information from Salesforce.

Use Cases:

• Unified Campaign Management: By syncing campaign data, organizations can manage their campaigns in either WeGive or Salesforce and have the changes reflected in the other platform. This eliminates the need for manual data entry and reduces the risk of errors.

• Comprehensive Reporting: The integration facilitates more robust reporting by combining data from both WeGive and Salesforce. Organizations can leverage Salesforce's advanced reporting features to analyze campaign performance, track progress towards goals, and gain valuable insights into donor behavior.

• Streamlined Donor Cultivation: With campaign data synchronized, organizations can leverage segmentation and automation tools in Salesforce to target specific donor groups with tailored messaging and outreach efforts, enhancing donor cultivation strategies.

• Custom Object Integration for Events: Salesforce users often create custom objects for event management, as Salesforce lacks a native events object. WeGive can integrate with these custom objects to sync event registration and participation data.

Key Considerations:

• Ensure the correct API names are used for campaigns in Salesforce, especially if using custom objects or fields.

• Thoroughly test the integration to verify data is syncing as expected and adjust mapping rules as needed.

• Monitor integration logs to identify and address any errors or inconsistencies that may occur during the synchronization process.

By effectively leveraging the campaign integration, organizations can streamline their fundraising efforts, enhance reporting capabilities, and gain a more comprehensive understanding of their campaigns' impact.

General Accounting Units (GAUs)

The WeGive-Salesforce integration connects General Accounting Units (GAUs) in Salesforce with Designations in WeGive. This bi-directional synchronization ensures consistent data flow between the systems, streamlining fund management and reporting.

• Name (WeGive) → Name (Salesforce): Syncing the name of the fund or designation.

• Other relevant fields: Potentially including descriptions, external IDs, or custom fields that the organization might have configured.

How This Integration is Used:

• Accurate Fund Allocation: When a donation is made in WeGive and designates a specific fund, the corresponding GAU is automatically updated in Salesforce, ensuring funds are allocated correctly in both platforms.

• Simplified Reporting: The integration allows organizations to create reports that combine financial data from both systems, offering a holistic view of fundraising efforts by designation.

• Streamlined Fund Management: Nonprofits can manage and update their funds/designations in either WeGive or Salesforce, reducing manual data entry and maintaining consistency.

Additional Insights:

• WeGive's internal terminology refers to GAUs as "funds," but this naming convention is not exposed to users.

• The integration allows customization, enabling organizations to map GAUs to different objects in Salesforce if needed.

• It's essential to review and customize mapping rules within WeGive to align with your organization's specific requirements.

To gain a deeper understanding of the specific fields mapped for GAUs and Designations, you would need to consult the WeGive API documentation or reach out to WeGive support for a detailed list of available mappings. Regularly monitoring the integration logs in WeGive will also help identify and address any inconsistencies or errors during the synchronization process, ensuring data integrity.

 

Opportunities and Payments

The WeGive-Salesforce integration centers around payments, using Opportunities and Payments in Salesforce to represent Transactions in WeGive. It's important to note that WeGive syncs on the Payment level, not the Opportunity level. So, a single Opportunity in Salesforce with multiple Payments will be reflected as multiple, individual Transactions in WeGive.

Here's a breakdown of the key objects and field mappings:

1. Salesforce Opportunities:

• Opportunities represent a broader concept of a donation or payment in Salesforce.

• WeGive pulls in relevant data from Opportunities, but the core unit of synchronization is the Payment object.

• Opportunity data is used to determine important attributes of the Transaction in WeGive, such as whether the transaction should be marked as tax-deductible or hidden.

2. Salesforce Payments (npe01__OppPayment__c):

• This Salesforce object is central to the integration, representing the actual payment made within the context of an Opportunity.

• WeGive pulls in data from Payments to create and update Transactions.

Default Field Mappings for Transactions and Payments:

The sources don't provide a comprehensive list of all the default mappings. However, based on the available code snippets and context, here are some of the key fields that are likely mapped:

• WeGive Transaction Field → Salesforce Field

  • name → Name (create only)

  • amount → Amount

  • owner.salesforce_account_id → AccountId (create only)

  • created_at → CloseDate

  • campaign.salesforce_id → CampaignId

  • owner.salesforce_id → ContactId (create only)

  • scheduled_donation.salesforce_id → npe03__Recurring_Donation__c (create only)

  • source_type → npe01__Payment_Method__c (export only)

• WeGive Transaction Field → Salesforce Payment Field

  • true → npe01__Paid__c (custom, literal, export) This field is hard-coded to 'true' when exporting to Salesforce.

  • amount → npe01__Payment_Amount__c

  • salesforce_id → npe01__Opportunity__c (create only, export)

  • payout_id → npsp__Batch_Number__c (export)

  • id → npsp__Gateway_Payment_ID__c (create only, export)

  • fee_amount → npsp__Total_Transaction_Fees__c (create only, export)

Associated Objects and Fields:

In addition to the fields listed above, the integration considers data from various associated objects to provide context and maintain relationships:

• Donor/Contact: The integration uses the ContactId and AccountId from the Opportunity to link the Transaction to the correct individual donor or company in WeGive. This draws on the integration between Contacts and individual donors as described in our conversation history.

• Campaign: The CampaignId associated with the Opportunity is used to link the Transaction to the corresponding Campaign in WeGive.

• Recurring Donation: If the payment is part of a recurring donation, the npe03__Recurring_Donation__c field on the Opportunity links it to the appropriate Recurring Donation in WeGive.

• Pledge: The integration also checks for a related Pledge in WeGive and makes the association if one exists.

• Payment Method: WeGive maps the payment method to the npe01__Payment_Method__c field based on the source_type of the Transaction. It uses a mapping array to translate WeGive's payment method terminology (like 'card' or 'bank') to Salesforce values.

Important Considerations:

• Customizable Stage Names: WeGive allows users to customize the mapping of stage names between Salesforce and WeGive, providing flexibility in how transaction statuses are reflected.

• Duplicate Prevention: The integration has built-in checks to prevent the creation of duplicate Transactions in WeGive, even if clear links haven't been established between Salesforce and WeGive records.

• Legacy Integrations: For older Salesforce integrations, certain fields might not be included in the data export to Salesforce.

By understanding the relationships between Opportunities, Payments, and Transactions, as well as the default field mappings, you can ensure a smooth and accurate flow of payment data between WeGive and Salesforce. As always, diligently reviewing the integration logs in WeGive will help you identify and address any inconsistencies, ensuring your payment data is reliable and reflects your organization's financial activity.

 

Recurring Donations

The WeGive-Salesforce integration links Recurring Donations in Salesforce with Recurring Plans in WeGive, ensuring that recurring giving information is synchronized across both platforms. This synchronization facilitates a unified view of recurring donor activity and streamlines management.

While a complete list of default field mappings is not explicitly provided in the sources, the code excerpts and explanations offer insights into key fields and relationships that are considered.

Key Points to Understand:

• WeGive pulls Active Recurring Donations: The integration only pulls recurring donations from Salesforce that are marked as "Active". This is important to note because it means canceled or paused recurring donations in Salesforce will not be reflected in WeGive.

• Control Over Key Fields: WeGive is designed to maintain control over critical aspects of the recurring donation, such as the frequency, amount, and start date. Therefore, even if these fields are updated in Salesforce, the changes will not be reflected in WeGive. This ensures that any modifications to a recurring plan are managed within WeGive to prevent inconsistencies.

• Ownership by Account or Contact: Recurring donations can be associated with either a Contact (individual) or an Account (household or company) in Salesforce. WeGive handles this distinction by allowing the Salesforce record to specify either the AccountId alone (for company or household ownership), or both the AccountId and ContactId (for individual ownership). If both are present, the recurring donation will be attributed to the individual contact in WeGive.

Default Field Mappings (based on code and context):

• WeGive ScheduledDonation Field → Salesforce Field:

  • amount → npe03__Amount__c

  • source.salesforce_id → npe03__Contact__c

  • start_date → npe03__Next_Payment_Date__c

  • campaign.salesforce_id → npe03__Recurring_Donation_Campaign__c

  • fund.salesforce_id → npe03__GAU_Allocation__c

Associated Objects and Considerations:

• Donor/Contact: As discussed in the previous response about contacts and individuals, the integration uses the npe03__Contact__c and npe03__Organization__c fields on the Recurring Donation in Salesforce to determine the correct donor relationship in WeGive (whether it's an individual, household, or company).

• Campaign: The npe03__Recurring_Donation_Campaign__c field links the Recurring Donation to the associated Campaign in WeGive, ensuring consistent tracking.

• Fund/GAU: Similar to campaigns, the npe03__GAU_Allocation__c field connects the recurring donation with its designated fund in WeGive.

• Payment Method: Although not explicitly listed in the code excerpts, the integration likely takes payment methods into account, mapping the method from Salesforce to the corresponding option in WeGive.

Using the Recurring Gift Integration Effectively:

The integration between recurring gifts in Salesforce and recurring plans in WeGive provides several benefits:

• Centralized Recurring Gift Management: Organizations can leverage the strengths of both platforms, potentially using Salesforce for comprehensive donor management and WeGive for a more user-friendly interface for managing recurring donations.

• Automated Updates and Reduced Errors: When a recurring donation is created or modified in WeGive, the information is automatically reflected in Salesforce, minimizing the need for manual data entry and the risk of errors.

• Improved Reporting and Analytics: By synchronizing data, organizations can generate reports that include both WeGive and Salesforce data, leading to more comprehensive insights into recurring giving trends, donor behavior, and overall revenue projections.

For a complete and up-to-date list of all default field mappings, you should consult the WeGive API documentation. In addition, regularly monitoring integration logs in WeGive can help identify and address any discrepancies that might arise, ensuring the accuracy and reliability of your recurring giving data.

 

Pledges (Suggested Custom Object)

The WeGive-Salesforce integration handles Pledges by utilizing a custom object in Salesforce named Pledge_Plan__c. This custom object is necessary because Salesforce does not have a native object specifically for pledges. The integration allows for the synchronization of pledge data between the two systems, ensuring that pledge information is consistently updated.

Here's a breakdown of the key aspects of the Pledge integration:

• Custom Object Requirement: It's essential to have the Pledge_Plan__c custom object set up in Salesforce for the Pledge integration to function correctly. This object should be configured to mirror the fields and relationships required to represent a Pledge in Salesforce.

• WeGive Controls Key Fields: Similar to Recurring Plans, WeGive maintains control over key fields related to the Pledge, including the total amount, start date, end date, installment frequency, and the number of installments. Even if these fields are modified in Salesforce, the changes will not be propagated to WeGive. This ensures that the management of the Pledge and its associated financial details remain within WeGive.

• Association with Donor, Campaign, and Fund: The integration considers the relationships between the Pledge and the Donor, Campaign, and Fund. When a Pledge is synced, the corresponding Salesforce records for the Donor (Contact or Account), Campaign, and Fund (GAU) are also updated or created if they don't exist.

Default Field Mappings (based on the code and context):

Here are some of the fields that are likely mapped by default between WeGive's Pledge object and Salesforce's Pledge_Plan__c custom object:

Associated Objects and Considerations:

The integration also considers various associated objects and fields to provide a complete picture of the pledge and its relationships:

• Donor/Contact: The Contact__c and Account__c fields on the Pledge_Plan__c object in Salesforce link the Pledge to the corresponding Donor in WeGive, whether it is an individual (Contact) or a company/household (Account).

• Campaign: The Campaign__c field connects the Pledge to the associated Campaign in WeGive, enabling consolidated tracking of pledge-related donations.

• Fund/GAU: The GAU_Allocation__c field associates the Pledge with the appropriate Fund/GAU in WeGive, providing a clear understanding of how the pledged funds will be allocated.

While this information provides a good overview of the Pledge integration, it's important to note that a complete and up-to-date list of all default field mappings should be obtained from the WeGive API documentation. Regularly reviewing the WeGive integration logs is also highly recommended to identify and resolve any potential data discrepancies. This ensures that your pledge data is accurate and reflects the current status of pledges made through your organization.

Payouts (Optional Custom Object)

Request information from your WeGive account manager.

• One-Directional Sync: The integration for payouts is one-directional, meaning that data is sent from WeGive to Salesforce but not vice versa.

• Payout Summary Data: The compilePayoutPayload function in the WeGive code indicates that the payout data sent to Salesforce likely includes summary information from the payout. This summary data might consist of:

  • Number of transactions included in the payout

  • Payout date

  • WeGive payout ID

  • Payment processor used for the payout

  • Breakdown of funds released (potentially including fees, net amounts, and other relevant financial details).

 

Campaign Membership (Optional Association)

Request information from your WeGive account manager.

 

Communication Preferences & Data Privacy (Optional Association)

Request information from your WeGive account manager.

 

Event Registration Record (Optional Association)

Request information from your WeGive account manager.

 

---

5. Customized Mapping or Advanced Configurations

Although the current user interface has some limitations, the underlying code and functionality provide a robust foundation for customization.

Custom Object Mapping Process:

Currently, there is no dedicated user interface in WeGive for mapping custom objects, but WeGive is actively developing such a UI to streamline the process. Custom objects are mapped via request. Custom fields are mapped via the UI.

Steps:

• Add a New Object Mapping: The planned UI will allow users to define a new object mapping. Currently, you must request one from your account manager.

• Define the API Name: Users will specify the API name of the custom object in Salesforce.

• Build the Request Body: Users will construct the request body, defining how data should be structured and sent to the custom object in Salesforce.

Flexibility of Custom Object Mapping:

Charlie emphasizes that WeGive doesn't require a strict adherence to specific object structures in Salesforce. The system is designed to be flexible, as long as the custom object in Salesforce:

• Returns an ID: WeGive relies on the returned ID to maintain synchronization and prevent duplicates.

• Has Appropriate Relationships: The relationships between the custom object and other objects in Salesforce should align with the mapping rules defined in WeGive.

Example (GAU/Funds):

Charlie highlights an existing example of custom object mapping with GAUs (General Accounting Units), referred to as "Funds" within WeGive. While the default mapping links WeGive's "Funds" to Salesforce's npsp__General_Accounting_Unit__c object, there's a customization option that allows users to define a different API name for "Funds" in Salesforce. This demonstrates the existing flexibility even without a dedicated UI.

Custom Field Mapping:

WeGive offers a high degree of flexibility for mapping custom fields between the systems. The system allows users to map WeGive's custom fields to any custom field in Salesforce.

Default Mapping Rules:

The code snippets in the sources reveal a significant detail about WeGive's integration architecture: default mapping rules are defined within the code itself. These rules establish the initial mappings between WeGive objects and fields and their corresponding Salesforce counterparts. These default rules provide a solid starting point and cover common use cases for synchronization.

Overriding Default Mappings:

Users can override these default mappings or add new custom field mappings using WeGive's Mapping Rules interface. The flexibility of custom field mapping allows organizations to:

• Send data from custom questions, form submissions, or calculated fields to custom fields in Salesforce.

• Map data bidirectionally, ensuring consistent updates in both systems.

• Use literal values for hard-coding specific values to Salesforce fields.

Challenges and Considerations:

Although WeGive offers significant flexibility for mapping custom objects and fields, some challenges need to be addressed:

• Limited UI for Custom Objects: The absence of a dedicated UI for mapping custom objects currently relies on manual configuration, requiring technical expertise. The planned development of this UI will simplify the process and improve accessibility for non-technical users.

• Clarity and Documentation: The sources acknowledge the need for clearer documentation and user interface improvements, particularly concerning field mapping options and default rules. Enhanced documentation will empower users to understand the integration's capabilities and configure it effectively.

Overall, the WeGive-Salesforce integration aims for flexibility in handling custom object and field mappings. The current limitations in the UI are acknowledged, and there are plans to introduce improvements that will further enhance the flexibility and user experience. The integration's ability to accommodate diverse data structures and adapt to custom fields makes it a powerful tool for organizations seeking to synchronize data between WeGive and Salesforce.

---

6. Troubleshooting

Troubleshooting the WeGive-Salesforce integration involves a combination of understanding the integration's mechanics, utilizing built-in debugging tools, and carefully examining error messages. Here are some key steps and strategies:

Understanding the Basics

• Data Sync Process: WeGive pulls data from Salesforce every 15 minutes and pushes data with a 5-minute delay. This asynchronous process optimizes performance but means there's a slight lag in data updates.

• Order of Operations: WeGive syncs data in a specific order: households, donors, companies, campaigns, funds, pledges, and then transactions. Understanding this order helps in anticipating dependencies and potential issues.

• Key Configuration Points: OAuth settings, field-level permissions in Salesforce, and mapping rules are crucial for a successful integration.

Utilizing Debugging Tools

• Integration Logs: The most valuable tool for troubleshooting is the "Integration Logs" section in WeGive. These logs provide detailed information about each sync attempt, including timestamps, data involved, and any errors encountered.

• Ignored Integrations Table: This table in WeGive lists models that have repeatedly failed to integrate (typically after three consecutive failures). Addressing these persistent errors is essential for seamless data flow.

• Manual Sync Trigger: WeGive allows you to manually trigger a sync from Salesforce, either for all data or just data updated since the last successful sync. This can be helpful after making significant changes in Salesforce or resolving persistent sync errors.

• Donor Record Logs: Individual donor records in WeGive also contain integration logs, providing a focused view of sync attempts related to that specific donor.

Common Issues and Troubleshooting Steps

• Field Permission Errors: Hidden fields in Salesforce, even for admin users, can cause sync errors. Carefully review field-level security settings in Salesforce and ensure that all fields included in mapping rules are visible to the integration user.

• Duplicate Prevention Rules: Salesforce's duplicate prevention rules can sometimes block legitimate records from being synced. Review these rules and adjust them as needed to accommodate data coming from WeGive.

• Mapping Rule Misconfiguration: Incorrectly configured mapping rules can lead to data mismatches or sync failures. Double-check your mapping rules, ensuring that the WeGive fields are mapped to the correct Salesforce fields and that any literal values or custom logic are accurately defined.

• Custom Object and Field Compatibility: When syncing custom objects or fields, verify that they are properly configured in both WeGive and Salesforce. The API names, data types, and relationships should align to avoid data inconsistencies.

• OAuth Issues: OAuth configuration problems can prevent WeGive from accessing Salesforce data. Verify that the connected app in Salesforce has the necessary permissions and that the OAuth flow is enabled for your Salesforce instance.

• Network Connectivity: Occasional network issues can disrupt the integration. Ensure that the WeGive servers can communicate with your Salesforce instance.

Proactive Measures

• Monitor Integration Logs Regularly: Regularly review the integration logs to identify potential issues before they become significant problems.

• Test in Sandbox Environments: Before implementing any major changes to your integration, test them thoroughly in a sandbox environment to avoid unintended consequences in your production data.

• Maintain Clear Documentation: Keep a record of your mapping rules, custom object configurations, and any other customizations to facilitate troubleshooting and future modifications.

By following these steps and making use of the debugging tools available, you can effectively troubleshoot the WeGive-Salesforce integration, ensure data accuracy, and maintain a smooth flow of information between the two systems.

Contacting Support

support@wegive.com

---

7. Maintenance and Updates

Regular maintenance and thoughtful software updates are essential for ensuring the smooth operation and long-term success of the WeGive-Salesforce integration. Here are suggestions based on the provided sources and our conversation:

Regular Maintenance Tasks

• Monitor Integration Logs: Regularly review the integration logs in WeGive to identify any errors, warnings, or unusual patterns. Address any issues promptly to prevent data discrepancies or sync failures.

• Check Ignored Integrations Table: Periodically check the Ignored Integrations table in WeGive. If any models consistently fail to sync, investigate the root cause (e.g., field permission errors, duplicate prevention rules) and resolve the issue.

• Verify Mapping Rules: As your organization evolves or your data needs change, double-check your mapping rules to ensure they still meet your requirements. Update mappings as needed to accommodate new fields, custom logic, or changes in your Salesforce data structure.

• Review Salesforce Field-Level Security: Periodically audit field-level security settings in Salesforce, particularly after making changes to user roles or permissions. Ensure the WeGive integration user has access to all fields included in your mapping rules.

• Test After Salesforce Updates: Whenever you apply updates or changes to your Salesforce instance (including NPSP updates), thoroughly test your WeGive integration to ensure compatibility and continued functionality.

Software Update Considerations

• Proactive Communication: Review WeGive’s communications about planned software updates, including release notes, timelines, and potential impacts on the Salesforce integration. This allows you to prepare and mitigate any potential disruptions.

• Sandbox Testing: Before deploying any WeGive software updates to your production environment, test them rigorously in a sandbox environment. This helps identify and address any compatibility issues or unexpected behavior related to the Salesforce integration.

• Staged Rollouts: Consider implementing WeGive software in a staged rollout approach. Start with a small group of users or a limited dataset to monitor the impact of the update on the Salesforce integration. Gradually expand the rollout once you've confirmed stability and functionality.

• Feedback and Reporting: Provide feedback to WeGive about your experience with software updates, including any challenges or suggestions for improvement. This feedback helps WeGive refine its update process and enhance the integration's robustness.

Additional Considerations

• Documentation Maintenance: As you make changes to mapping rules, custom object configurations, or other aspects of the integration, keep your documentation updated. This helps ensure consistency, facilitates troubleshooting, and makes it easier to onboard new team members or manage future updates.

• Training and Knowledge Sharing: Regularly train your team members responsible for managing the WeGive-Salesforce integration. Share best practices, troubleshooting tips, and updates on the integration's features to foster a proactive approach to maintenance and updates.

By following these suggestions for regular maintenance and software updates, you can proactively address potential issues, minimize disruptions, and ensure the WeGive-Salesforce integration continues to meet your organization's needs reliably.

---

8. Appendix

Documentation

https://docs.api.wegive.com/

---