Customizing the Virtuous CRM Integration

How to customize the Virtuous CRM integration to make sure that your Fundraise Up data is showing up the way you want

Now that you've connected your Virtuous CRM Integration, you can customize it further and start automatically syncing donations from your Virtuous CRM Integration settings page. To get started, kindly use the guide below:

Step 1: Review integration behavior, default mappings, and known limitations

Step 2: Adjust General Settings

Step 3: Add Mapping Rules

Step 4: Apply Special Rules, if necessary

Step 5: Send a test record

Step 6: Enable Automatic Sync

Step 7: Sync your historical data


Step 1: Review integration behavior, default mappings, and known limitations

When a Fundraise Up record is created or updated, it’s automatically synced with Virtuous.
All syncing happens in real-time, and is one-way, from Fundraise Up to Virtuous. This means changes made in Fundraise Up will appear in Virtuous, but changes made in Virtuous will not appear in Fundraise Up. Here are some specifics regarding how certain records are created and updated:

Gifts

The integration makes Gifts in Virtuous CRM to represent all Donations, and fills in certain key fields by default like "amount" and "date." See full default mappings below.

As of September 2022, donations will be sent in their original currency.
This will allow you to leverage the multicurrency support built in to Virtuous, allowing you to review donations both by their original amount and currency, and their converted amount in your account's default currency.

If a donation that has been synced is refunded while the auto-sync is still on, the refund will sync to Virtuous CRM as a "reversing transaction" associated with the original Gift.

Contacts

When a donation is synced in and creates a Gift in Virtuous CRM, the integration attempts to find an existing Contact based on your "Match Contact" setting. We'll cover this more in Step 2.

The relevant possible values here are:

  • Email
  • Name and Phone
  • Name and Address 

If it does find a matching Contact, Virtuous associates the Gift with that Contact.
If it does not find a matching Contact, Virtuous makes a new Contact and associates the Gift with that new Contact.

Recurring Gifts

The integration makes Recurring Gifts in Virtuous to represent any synced Recurring Plan.
Any Gifts made in Virtuous CRM that represent installments of a Fundraise Up Recurring Plan get associated with the corresponding Recurring Gift in Virtuous CRM.

If a Recurring Plan is either canceled then reactivated, or the amount is changed, due to syncing considerations we will cancel the existing Recurring Gift in Virtuous and sync over a new one, effective as of when the change happened.

Default Mapping

We seek to make our CRM Integrations fill in every standardized field and create every standardized record that's expected. Below is how we've mapped Fundraise Up fields to standard Virtuous CRM fields. These mappings are not represented in the Integration setting's mapping rules and cannot be changed, so it's important that you understand them. Last updated 10/28/2022

Contact Default Mapping
Fundraise Up Field Name Virtuous CRM Field Name Notes
Supporter First Name + Supporter Last Name Name If "On Behalf Of" is NULL, then the Contact Type will be "Household"
On Behalf Of Name If "On Behalf Of" is not NULL, then the Contact Type will be "Organization"
Supporter First Name Informal Name  
Supporter Phone Number Primary Phone (Home Phone)  
Supporter Email Primary Email (Home Email)  
Mailing Address Line 1 Address Line 1  
Mailing Address Line 2 Address Line 2  
Mailing City City  
Mailing State/Region State/Province/Region  
Mailing Zip/Postal Postal Code  
Mailing Country Code Country  

 

Gift Default Mapping
Fundraise Up Field Name Virtuous CRM Field Name Notes
Payment Method Gift Type If "Credit Card," then value will be "Credit." If it's any form of direct debit, then value will be "Electronic Funds Transfer." For all other payment methods, the value will be "Other."
Donation ID Transaction ID  
Donation Amount Amount  
Success Date Gift Date  
Success Date Receipt Date  
Anonymous Donation Private Boolean field

 

Recurring Gift Default Mapping
Fundraise Up Field Name Virtuous CRM Field Name Notes
Donation Amount Amount  
Donation Frequency Frequency The integration will only make Recurring Gifts for Weekly, Monthly, Quarterly, and Annual Recurring Plans, as those are fully supported in the Virtuous CRM API. Daily and Biweekly plans are currently not supported, so they are sent as one-time donations.
Success Date Start Date  
Next Donation Date Next Payment Date  
Anonymous Donation Private Boolean field

 

Known Limitations


Fundraise Up integrations are API-based, meaning that the software suite that data is being synced into controls how records can be made, whether they can be edited, and so forth. Before using the Virtuous CRM integration, we recommend reviewing the following known limitations:

  • The integration will only make Recurring Gifts for Weekly, Monthly, Quarterly, and Annual Recurring Plans, as those are fully supported in the Virtuous CRM API.  Daily and Biweekly plans are currently not supported. (Stay Tuned!)
  • Currently, only two types of custom fields can hold text: Text and Paragraph. Text is intended for short messages and has a limit of 140 characters, while Paragraph is open-ended.

Step 2: Adjust General Settings


It's good to start in the tabbed area (with tabs labeled General Settings, Mapping Rules, and Special Rules) so that you can cover your most common donation scenarios. Any changes you make in any of the tabbed sections are not saved until you hit the Save Changes button at the bottom of that area. The screen will have the General Settings tab open by default, as shown here:

Screen Shot 2021-08-09 at 9.34.35 AM

Within General Settings, you'll find a few checkboxes and a few dropdowns. There's only one required field in this area (Match Contact), and it's filled in with the most common selection by default. 

Setting Notes
Sync test data If this is enabled, and automatic sync is turned on, it will automatically sync test data. To have more control over the data that's synced, we recommend syncing one record of a time, which is covered in Step 5.
Sync subaccounts Only applicable if subaccounts are enabled on your account. This option will sync parent and subaccount data.
Track Payments (in Virtuous CRM) Enable this if you'd like us to create and maintain Recurring Gift Payments pre-emptively, to predict upcoming installments of a Recurring Gift based on the stored payment schedule.
Default Project In Step 4, we'll cover conditional Project matching, but if one of those rules aren't triggered, then the Project will default to whatever you select here.
Match Contact This is set to "By Email" by default, and that's our recommended best practice, as people have names, addresses, and phone numbers in common more regularly, and change them more often.
Default Segment In Step 4, we'll cover conditional Segment matching, but if one of those rules aren't triggered, then the Segment will default to whatever you select here.
Default Comment This governs what data will be written into the Notes field on Gift records. By default, the merge tag for Fundraise Up's "Comment" field is pre-filled in this box so that donor's comments during checkout would be put in the notes field, but you can edit as you prefer!


Step 3: Add Mapping Rules

The second tab is Mapping Rules, which allows you to make 1-to-1 mappings of fields in Fundraise Up to fields in Virtuous CRM.

Screen Shot 2021-08-19 at 1.53.00 PM

As covered in Step 1, some mappings are already built-in by default (i.e. donation amount to amount), so this area covers things that are not mapped by default. To add a rule here, you'll click the Add Rule button to start choosing what Fundraise Up object the mapping should start with.

The available Fundraise Up entities to map data from are:

  • Account
  • Campaign
  • Designation
  • Donation
  • Checkout Question
  • Custom Field
  • UTM Parameter
  • Static Value
    • This allows you to enter a specific value to pass in for every Donation.

The available Virtuous CRM entities to map data to are:

  • Project
    • You can make sure your Gifts and Recurring Gifts end up associated to the right Projects by matching on either the Project: Name or Project: Code values.
    • So, for example, if all of your Designations in Fundraise Up are named the exact same as your Projects in Virtuous, you could map Designation: Name -> Project Name.
  • Segment
  • Gift Custom Fields
  • Contact Custom Fields
  • Recurring Gift Custom Fields

In Virtuous, there are two types of custom fields that can hold text: Text and Paragraph. Text is intended for short messages, and has a limit of 140 characters. Paragraph is open-ended.

As such, we recommend mapping any Fundraise Up fields that house long-form text (Donation: Tribute Message, for example) to Paragraph custom fields in Virtuous.


Step 4: Apply Special Rules, if necessary

Your defaults will have you covered most of the time, but what about the edge cases? Special Rules allow you create mappings based on "if this, then that" logic. Any mappings set here will override your default Segment and Project mappings set in Step 2. 

Screen Shot 2021-08-19 at 1.53.23 PM

To add a rule here, you'll click the Add Rule button to start choosing what Fundraise Up object the Special Rules' mapping should start with. Fundraise Up offers Campaigns and Designations as the basis for our side of any Special Rule going into Virtuous CRM.

Virtuous CRM can then say what Project or Segment matching the above criteria Gifts and Recurring Gifts should get written towards in Virtuous CRM.

So, let's say you want all donations from your "After School Program" Fundraise Up campaign to go to the "Extracurricular" Project in Virtuous CRM. The Special Rule would be made as follows:




Step 5: Send a test record

Now that you understand the default behavior of the integration, and have made necessary changes, it's time to sync a test record. There are multiple ways to make a test donation, click here to see all of the different methods. Once you've made a test donation, locate the test donation record (HINT: you need to enable "test data" in the dashboard), scroll to the bottom, locate the Virtuous section, and then hit "Syncronize."

This will sync just this one test record, giving you maximum control over what data syncs. Feel free to repeat this step as m any times as you'd like until you're satisfied with the integration.


Step 6: Enable Automatic Sync

Now that you're satified with your integration, the one of the last steps is to turn on the Automatic Sync. Once you chose to Enable Automatic Sync, all new donations from that point on will begin automatically syncing to Virtuous.


Step 7: Sync your historical data

What if you launched Fundraise Up before you completed setting up your Virtuous sync?How do you get past donations and donor data in? What about changes that've been made to your mappings; how do you get that new data in? 

For scenarios like those, we offer the ability to run a sync that'll add any new records and update any previously synced ones. As the bottom of the Virtuous CRM Integration page, you'll find a button labeled Synchronize in a section that summarizes the last sync run.

Screen Shot 2020-09-15 at 2.29.21 PM

Clicking that Synchronize button will launch a popup labeled Synchronize Donations, which will provide you the following options:

  • All donations
  • Specify period
    • This will offer a date range selector, so that you can sync only donations made in your date range of choice. 

Once you click Start Synchronization, the sync will begin.

Refreshing the page and scrolling back down to the footer will show you the progress/results of that latest manually-started sync.