This article explains set up and mappings for Qgiv’s Salesforce integration.
Click here to download a spreadsheet of information we send to Salesforce by default during export, when applicable.
Click here to download a spreadsheet of additional fields in Qgiv you can map to Salesforce.
The instructions for the Qgiv integration with Salesforce described in this article will work for both SF Classic and SF Lightning.
Please note: The integration does require that the Nonprofit Success Pack Version 3 be installed within your SF instance.
Please note: Online and offline + verified transactions and gift matches are exported. Refunds, voids, and chargebacks are not exported. Users can exclude offline and matching transactions from the Salesforce export by toggling the Exclude Offline & Matching Donations? button on in the integration's settings. It's also possible to export declined transactions to Salesforce to track and address declined donations.
Contents:
- Getting Started
- General Settings
- Export Settings
- Soft Credit Support
- Declined Transactions Support
- Recurring Support
- Default Values
- Extra Info
- Optional Mappings
- Custom Mappings
- Running an Export and Export History
- Viewing Your Qgiv Data in Salesforce
- Backing Up, Re-Authenticating, or Deleting the Integration
- Enabling the Service Integrations Notification
Getting Started
To set up the integration, click the Integrations icon along the left side of your screen.
Locate the Salesforce tile in the CRM section and click Connect.
In the Environment drop-down, choose your Salesforce server type: Production, Development, or Sandbox. In most cases, you'll select Production.
Click Connect.
You'll be asked to enter your Salesforce username and password, and then click Log In.
General Settings
You'll be taken to a screen where you can configure your settings.
Settings are organized into tabs along the left side of the page. You'll be prompted to Save after you make changes on a tab.
On the General tab, use the calendar to choose the Export Data Starting On date. If you'd like to export data from a date prior to the current date, you can set your calendar accordingly so historical transaction data will be exported.
IMPORTANT: The date you set aligns with the transaction dates you'll be exporting. If you set the date to today, only transactions from today and future dates will be exported.
The Export Data Ending On field lets users input a date to end exports from the integration. Leave this field blank if you want the integration to export indefinitely.
In the Frequency drop-down, choose Manual, Hourly, Daily, or Every 15 Minutes exports.
If you choose Daily exports, you’ll also be able to choose the time (Eastern) for the export to occur.
Beneath the Frequency drop-down is the Maximum Transactions field. This required field specifies the maximum number of transactions Qgiv will export to the integration at a single time. The default setting is to export a maximum of 100 transactions. You can adjust this number higher or lower, but the number field cannot be blank.
Also note that smaller limits provide a safer export, reducing the likelihood of export issues due to a service interruption.
Export Settings
The next tab house the Export settings.
Exclude Offline & Matching Donations, when toggled on, excludes offline and matching donations from exports.
IMPORTANT: If you choose to export offline and matching donations, only verified transactions will be included.
The Exclude Facebook Donations toggle excludes donations made through Facebook.
If you have State and Country Picklists enabled in Salesforce, click the State and Country Picklists are Enabled toggle so it's in the "on" position.
Next in the Export settings, you'll see a series of drop-downs in which you'll configure the information associated with your Account and Opportunity records in Salesforce.
In the Organization Account Record Type drop-down, select the record type for company donations. Organization is the correct option for most situations, as selecting another value here can cause failures when exporting company donations. Individual donations are unaffected by this drop-down and will always use the Household Account record type.
You'll then need to select an Opportunity Record Type, Opportunity Lead Source, and Opportunity Stage. These settings will determined how opportunities are organized in Salesforce upon export.
Using the Opportunity Creation Behavior drop-down, determine how transaction opportunities should be created during export. Your options are Per Transaction, Per Line Item, or Per Line Item with GiftAssist as a Separate Line Item. This means that your GiftAssist donations from donors will come across as their own item rather than being affixed to donations or registrations.
If you'd like to Exclude $0 Opportunities From Being Created, toggle on that option.
Please note: The Exclude $0 Opportunities setting requires that you select Per Transaction or Per Line Item with GiftAssist as a Separate Line Item in the Opportunity Creation Behavior drop-down.
Contact Matching Logic
Last in Export settings, select the Contact Matching Logic.
The options here determine how the integration will identify existing records in the CRM to import Qgiv information to if they're already in the database.
Using the "Last Name" options, the matching logic can match records by household, so if two people with the same last name, street address, and zip code donate, the integration can apply the gift to an existing record without creating a new record.
For example, Robert Smith can donate as "Mr. and Mrs. Smith" or Jane Smith, who lives at Robert Smith's address, can make a donation and the matching logic will apply the gift to Robert Smith's record in the database.
IMPORTANT: In the case of “Email OR” matching, both sides of the OR statement are equally weighted. In other words, if you select “Email OR (First Name AND Last Name AND Zip Code),” the integration will prioritize finding matching name and zip code equally with finding a matching email address, rather than looking for a matching email address before moving on to other criteria. In the event the system finds two different records with matching criteria, tiebreaker logic will determine which record to match with.
The integration's matching logic also references common nicknames, so if a donor is listed in Salesforce by their legal name but uses their nickname when donating later, the integration won't create a new record in Salesforce if the last name and either the email or zip code are the same.
For example, a donor in your database named Robert Smith can donate as Bob Smith and the matching gift logic will apply the donation to Robert Smith's record in the Salesforce database.
If no match is found, a new account is automatically created.
Please note: The Contact Matching Logic drop-down only applies to individual or household donations. We match to company donations based on the following criteria: Company Name + Zip Code.
Soft Credit Support
The Enable Soft Credits toggle enables the exporting of soft credits for peer-to-peer transactions.
With soft credits enabled, you can also select the Soft Credit Opportunity Contact Role.
Declined Transactions Support
On the next tab, determined whether you'd like to Export Declined Transactions. Declined transactions will not be exported unless you enable this toggle.
With the setting enabled, you can also select the Declined Opportunity Stage.
Recurring Support
Qgiv’s service integration with Salesforce supports recurring donations. Salesforce users on either Legacy or Enhanced Salesforce configurations can enable recurring donation support by toggling on the Enable Recurring Support option shown below.
To read a detailed set of instructions on how to set up recurring donations in Salesforce, check out the Enable Recurring Support article for Qgiv’s Salesforce Integration.
Recurring support offers Qgiv the option to create Salesforce Opportunities with created installment payments for recurring donations. Should those donations be changed or cancelled, a status can be specified during the export to apply to changed opportunities. This makes it easy for Salesforce users to determine when changes to recurring gifts occurred and what that reason was. In many cases, the original recurring donation is closed, and a new Opportunity is created to reflect the most recent changes. On a cancellation or closure the fulfilled opportunities are left alone and the pledged opportunities are marked as “Closed Lost,” which means they’ll never be updated to paid. Then, the recurring donation is closed out and a new recurring donation entry is created.
Default Values
On the Default Values tab, choose a Campaign and General Accounting Unit (GAU) from the drop-down menus. The selections you make will be your default mapping locations.
You can select Unmapped if you do not want any value to be used. If you choose Unmapped, a value won't be set in the resulting record(s) (e.g. Campaign will not be populated in an Opportunity record, and a GAU Allocation will not be created).
Please note: If your Campaign specifies a GAU within Salesforce, you should not select a GAU from the drop-down menu. This can result in an error because Salesforce attempts to allocate more than 100% of the donation's value to that GAU.
Extra Info
If there’s any extra information you’d like to add to the Opportunity Description field in DonorPerfect upon export, you can choose from the options in the drop-down menu on the Extra Info tab.
You can read more about what those extra info fields mean here.
You can make multiple selections—they’ll appear one at a time below the drop-down menu as you select them.
Not all information is available for each transaction type (e.g. Participant Name will only show up for peer-to-peer registrations).
Optional Mappings
Once you’ve saved, click the Mappings tab to display your Optional Mappings options. This is where you’ll configure mappings if you’d like specific data sets mapped to something other than the default values in the settings area.
Mappings can be grouped by Mapping Type or by Form using the Group by drop-down menu.
You can also filter your mappings to display only specific Mapping Types or only certain Forms and Events.
To add a new mapping, click the Add New Mapping button and then select the Mapping Type from the drop-down.
For example, if you’d like to export data for a specific form, select Standard Qgiv Form > Form from the drop-down menu. Then, use the Form drop-down to select the form.
If you’d like to exclude the Qgiv data from your exports, check the box labeled Exclude from Export.
Excluding can be useful for something like a $0 category for a peer-to-peer campaign.
If you’d like to export the data to Salesforce, do not check the box, and then select the destination Campaign and General Accounting Unit.
When you’ve configured your mapping, click Add Mapping.
You can Edit or Delete a mapping by clicking the three dots at the right side of the mappings table.
If you’d like to delete multiple mappings, check the box next to the mapping’s names, and then click Delete Mappings at the top of the table.
The process is similar for each data set shown in the Optional Mappings area. There may be some slight variations in how many choices you have in each drop-down.
For example, if you’re mapping restrictions, you’ll see another drop-down menu, and still another if you’ve set up sub-restrictions.
When mapping events, you’ll be given the option to drill all the way down to event packages, if desired.
You can also map text campaigns:
Peer-to-peer events just require a form selection and export destination.
You can choose to export other peer-to-peer data, as well.
Peer-to-Peer Classifications
Peer-to-Peer Categories
Peer-to-Peer Restrictions
Peer-to-Peer Store Purchases
You can also map auction transactions.
Auction
Auction Restriction
Auction Package
Auction Item
Custom Mappings
You can also add Custom Mappings. You may already have similar mapping set up through the Extra Info fields. If you don't want this information to appear in both places, be sure to delete the Extra Info mappings once you set up your custom mappings.
Custom mappings allow you to dictate which target objects and fields you want data to go into in the integration. Custom fields must be active in the destination before you can map to them from Qgiv. There are three custom mapping types: static, custom field, and standard field. For each type, you can map to a target object + field using the data from that custom type. See the attached standard field mappings spreadsheet for details.
Static
With static field mappings, you can add static values in Qgiv to target records in the integration service.
Custom Field
With custom field mappings, you can map custom field answers in Qgiv to target fields based on unique custom field reporting labels. For example, you can track custom fields for your fundraising events, such as gathering meal choices.
Standard Field
With standard field mappings, you can map standard field values to a target field.
Some values will be specific to a transaction line item (e.g. restriction name), while others will be for the entire transaction (e.g. transaction ID).
Click here to download a spreadsheet that details all Service Integration Standard Field mappings.
Please note: Qgiv's integration with Salesforce also supports lookup fields. Within static field custom mappings, users can map certain fields to Salesforce lookup fields. Lookup fields are fields Salesforce uses to associate two records together in a relationship.
Supported lookup fields include the following:
Please note: If you try to map to the same target object + field (regardless of the type), we will only save the most recent mapping.
Don't forget to save your work!
Running an Export and Export History
When you’re ready to run an export, click Export, which is located in the upper-right corner of your settings window. This is only necessary if you chose the Manual export option.
Otherwise, Hourly exports are scheduled to run once per hour at 15 minutes past the hour, but they are not guaranteed to run at exactly 15 minutes past. Actual run times depend on the server load. Daily exports will run at the time you chose.
IMPORTANT: If you're exporting for the first time or have a large number of transactions to bring over, we'd recommend setting your export start and end dates to export one week at a time to avoid hitting API limits.
You’ll receive a message in a pop-up alerting you that your export was completed. If successful, you’ll see the following:
Clicking View Export History will open the Export History Report, but will display only the records associated with this export.
If there were any issues during the export, you’ll see a message similar to the following:
At the top of your integration management screen, you’ll see an Export History tab. Here, you’ll see some basic information about your past exports, including the Export ID, Date and Time, Status, and Total Transactions.
Clicking the Export ID will take you to the more detailed Export History report, filtered by the transactions that were exported in that batch.
To view the full Export History report, click View All Export History.
When you do so, you’ll open the Export History Report, which includes a table which details all exported records across your service integrations.
In the Export History Report you may notice an icon that looks like the outline of a person with a plus sign. This means a new record was created as the result of a new donor or registrant.
Additionally, you may notice an additional alert icon in the Export Status column. Hover over the icon to see more details. The message will also display in the Export History Report.
Follow the link to learn more about the Export History Report.
Please note:
- If you selected Per Transaction in the Opportunity Creation Behavior drop-down, we will create a single Opportunity record in Salesforce and associate a single Campaign (if mapped) and one GAU Allocation per line item (such as registration fee, donation, store purchase, etc.).
- GAU Allocation mappings will happen on a per-line level. For example, if a registration fee and a donation occur in the same transaction, we'd create one allocation for the registration and one for the donation.
- Campaign mappings will be the most specific for all line items. If there is a tie, we choose only one. For example, if we mapped to an event package AND a form, we'd use the campaign mapping for the event package.
- GiftAssist costs are included in the Opportunity amount and get spread across all GAU Allocations.
- If you did not select Per Transaction in the Opportunity Creation Behavior drop-down, we will create a single Opportunity record in Salesforce PER line item (such as registration fee, donation, store purchase, etc.), and associate a single Campaign, if applicable for each, and a single GAU, if applicable.
To read about how we choose which mapping to use, read our Mapping Specificity article.
You can download a .CSV file that shows how Qgiv fields map to Salesforce fields. It's attached to this article!
Viewing Your Qgiv Data in Salesforce
To access the gift portion of a Qgiv transaction, go to your Dashboard. The mappings you set up in Qgiv will populate in the various Salesforce tabs.
Please note: The images in this section are from Salesforce Classic. If you're using Salesforce's Lightning experience, your Dashboard may look slightly different.
For transaction information, go to the Opportunities tab, and for recurring donations, go to the Recurring Donations tab.
You can access the donor portion of a Qgiv transaction from the Accounts tab or the Contacts tab.
For the name of the transaction, you'll see Qgiv Transaction or Qgiv Recurring followed by a file number in either Opportunities or Recurring Donations.
Backing Up, Re-Authenticating, or Deleting the Integration
If you have a lot of optional mappings, you may want to back them up to a CSV file. This is useful if you need to deactivate a service or adjust your connection and want to make sure your mappings are safe.
Click the Mappings Backup link to access the Mappings Backup & Recovery settings.
From here, you can download your mappings as a CSV file, as well as upload a previously downloaded backup file.
The Re-authenticate link lets users reconfirm their integration credentials or enter credentials for a different account.
When you click Re-authenticate, you'll be prompted to Activate the integration or Cancel the reauthentication process. Clicking cancel keeps the integration set up the way it was before clicking Re-authenticate.
If this service integration is no longer needed, it can be deleted by clicking Delete Integration in the left-hand navigation.
You'll be prompted to confirm your choice to delete the integration by typing the word DELETE.
After deleting the service integration, if you need to re-enable it you can reconnect just like when you originally set up the service integration.
To save you time and prevent you from accidentally creating duplicate records, you'll be prompted to Restore export history when you establish your integration again. Note that this will not import any past integration settings. If you would rather start with a clean slate, select Start from scratch instead.
Enabling the Service Integrations Notification
To be notified via email when a service integration becomes inactive, the integration is locked for an extended period, or a transaction fails to export, you can turn on the Service Integrations notification.
To manage notifications, navigate to the Notifications area of your org-level control panel.
Click Manage for each user you’d like to receive the notification.
Then, search for Service Integrations at the top of the screen, or scroll down to Service Integrations in the System Notifications section.
Check the box next to the notification to activate it.
Scroll to the bottom of the screen and click Save Settings to save your changes.