How Do I Integrate With Salesforce (beta)?

The Salesforce integration in Virtuous Raise allows you to automatically sync your fundraising data with your Salesforce CRM. This guide covers how to configure the integration, map your data fields, and sync records to Salesforce.

Table of Contents

1. Integration Overview
2. Setup and Connection
   • Additional Options
3. Configuration
   • Field Mapping
   • Object Mapping
4. Synchronization Logic

Integration Overview

The integration supports creating and updating the following objects in Salesforce from Virtuous Raise:

• Donors
• Gifts
• Recurring Gifts
• Campaigns
• Segments
• Projects
• Premiums

It supports three main Salesforce configurations: Standard (basic Salesforce setup,) NPSP (Nonprofit Success Pack, standard for many nonprofits,) and Nonprofit Cloud (NPC, the newer industry cloud offering from Salesforce.)

Setup and Connection

Before connecting, make sure you have a Salesforce account with System Administrator permissions (or at minimum, API access and permission to authorize connected apps.)

1. Navigate to Settings > Integrations.
2. Select Salesforce.

3. Click Connect to Salesforce. You will be redirected to Salesforce to log in and authorize Virtuous Raise.
4. Once connected, you will see your Salesforce Organization Name and ID.
5. Toggle Enabled to "Active" to start processing data.

Additional Options

After connecting, configure these option settings:

• Environment: Toggle between “Production” and “Sandbox.” Use Sandbox for testing purposes. Switching environments will require re-authentication with the appropriate credentials.
• Include Tests: If enabled, transactions made in Test Mode in Virtuous Raise will also be synced to Salesforce. Disable this to keep your CRM clean of test data. Click here to learn more about Test Mode. 
• Re-connect: Click "Reconnect to Salesforce" if you need to refresh your authentication tokens or switch users.

Configuration

Virtuous Raise attempts to automatically detect your Salesforce Instance Type (NPSP, Nonprofit Cloud, or Standard) based on installed packages. If you would prefer to manually configure your instance type instead, use the dropdown to select the type. 

Field Mapping

These settings control how Accounts are created when a new donor is synced to Salesforce.

• Household Account Record Type and Account Type: Used for individual donors.
• Organization Account Record Type and Account Type: Used when the donor is an Organization.
• Opportunity Contact Role: The role assigned to the Contact on an Opportunity (e.g., "Donor").

Object Mapping

After you configure your Account Type, Account Record Type, and Opportunity Contact Role mapping, you need to map Virtuous Raise objects to Salesforce objects. If an object is not mapped (e.g., if “Recurring Gift” is left blank), those records will not be synced. The objects to map include:

• Donor
• Gift
• Recurring Gift
• Campaign
• Segment
• Premium
• Project 

For each object, you can map specific Salesforce fields using Standard Fields or you can select to map to Custom Fields in Salesforce.

If Virtuous Raise detects that your configured mappings differ from the recommended best practices for your Instance Type (e.g., NPSP), a notification will appear. Click Apply Recommendations to automatically configure standard object and field mappings for your setup. This is recommended for new integration setups.

Synchronization Logic

1. Donors: Donors are typically mapped to Contacts or Accounts. If mapping to Contacts, the system first tries to find an existing donor using the external ID (CRM Key). If the donor is not found, it searches by Email, FirstName, LastName, and Phone. If mapping to Accounts, the system tries to find an existing Account by Name. If creating a new donor, it will create and link an Account.
   • NPSP Note: For NPSP, the integration often relies on NPSP’s native triggers to create Household accounts for individuals, avoiding duplicate account creation logic.
   • Contact Methods: Emails and Phones are mapped to standard fields (Email, Phone), while others can be mapped to custom fields (e.g., WorkEmail__c).
2. Gifts: The integration syncs Gifts after first syncing the donor record. The Gift is linked to the donor (Contact) and Account and creates an Opportunity Contact Role to link the Contact to the Opportunity. Gifts are linked to Salesforce Campaigns based on the Virtuous Raise Segment and Campaign mapping. The integration updates refunded Gifts in Salesforce (typically changing the StageName to “Refunded”).
3. Recurring Gifts: For NPSP, Recurring Gift schedules are mapped to npe03__Recurring_Donation__c. When a new Recurring Gift is created, the sync will check for existing Recurring donations. All subsequent installments are linked to this Recurring Donation object. For Nonprofit Cloud, Recurring Gift schedules are mapped to GiftCommitment. The GiftCommitmentSchedule field is synced to define frequency and amount. Payments are linked to the schedule via GiftTransaction.
4. Campaigns and Segments: Virtuous Raise Campaigns and Segments can be synced to Salesforce Campaigns. A hierarchy is often established where the Segment in Virtuous Raise links to a Parent Campaign in Salesforce.
5. Projects & Allocations: For NPSP, Projects typically map to General Accounting Units (GAU). Allocations are synced to npsp__Allocation__c. For Nonprofit Cloud, allocations map to GiftTransactionDesignation. For any Gift with Project splits, the sync will update, create, or delete allocations in Salesforce to match the split in Virtuous Raise. 
6. Premiums: Premiums map to Products (Product2) in Salesforce. When a Gift includes a Premium, the sync creates an OpportunityLineItem linking the Opportunity to the Product. This ensures the Product exists and uses the Standard Price Book.