Connecting Funraisin to Salesforce

by Scott Dilley - CTO 12 Sep 2019

Every Funraisin site comes with the ability to sync it's data directly to Salesforce, right out of the box with no additional charges or development needed.

This article aims to show you the steps required for setting up your Salesforce sync.

Overview

The Funraisin Salesforce integration comprises of a one-way sync from Funraisin to Salesforce that operates on a schedule. This schedule can be altered to accommodate different volumes, with common schedules being anywhere from daily, bi-daily to every 30 minutes.

As part of the standard integration you will be required to install a managed package (See below), we can provide links for the package installation or you can provide us with access to your Salesforce account and we can install it on your behalf.

For custom integrations this might not be needed.

Version & Compatibility

The Funraisin integration is compatible with the Salesforce Not for Profit pack using household accounts. If you do not support this or do not support household accounts we are still able to sync but we will create accounts automatically for all contacts. The current version is 1.9

De-Duping

As records sync, de-duping will occur for all Contacts and Accounts to try to avoid duplicate records. De-duping on Contacts will check for an existing match on First name, Last name and Email address. De-duping on Accounts will check on Account name.

If you have your own additional matching rules in place this may affect our ability to create contacts.

ID Handling

All Funraisin objects support a field known as “External CRM ID” which is used to store the IDs from external data sources. As data syncs to Salesforce, the Salesforce ID for each object is stored in our own External CRM ID for that object so that you are at any time able to edit an ID within your Funraisin platform.

It is vital that when you merge or delete any record in Salesforce, that you also then update the related record in Funraisin otherwise you will see errors in your error log around "insufficient access to ID xxxxxxx" etc

Limits

The Funraisin > Salesforce sync uses the Salesforce SOAP API so each record that is synced will use at least 1 API call but often a single record will require 2-3 API calls depending on the data being synced.

A site catering for example 10,000 transactions per day could typically require up to 30,000 API calls per day.

Should an API limit be hit when syncing, the sync will retry later which depending on the schedule this could be with an hour or the next day.

Support

For all Salesforce related support enquiries please pop in a support ticket in your Funraisin admin.

^ Back to top

Configuration

To setup your integration you will need to create a user account with a non-expiring password. Login to your Funraisin platform and navigate to the Salesforce module and within the configuration option you will need to enter your account email address, account password, account security token and also upload your enterprise WSDL.

Sandboxes

Syncing to a sandbox prior to launch can be catered for, simply by providing your Sandbox details in the above step.

Then once the site is ready to sync to a production environment we would simply clean all data from Funraisin by removing any existing Salesforce IDs so that data can be re-synced.

Configuration Setttings

Step 1. Navigate to Funraisin > Salesforce when logged in to your platform and you will asked to configure your account. Enter the username, password and security token of the account you want to connect as, as well as specifying what Funraisin objects you want to have synced to Salesforce.

Step 2. Next upload your Enterprise WSDL into Funraisin

That is all that is needed on the platform side, you now need to install our managed package.

^ Back to top

Package Installation

Data from your Funraisin platform will map to most standard Salesforce objects as details further below, however some data captured requires additional Fields and Objects be created on your Salesforce account.

Before syncing data from your Funraisin platform you will be required to install our Managed Package.

https://login.salesforce.com/packaging/installPackage.apexp?p0=04t7F000005IwSm

This will install the following:

Additional Fields

The following Salesforce objects have these additional fields applied

Campaign Member

Fundraising target Currency
Page url Text (255)
Distance target Number
Duration target Number
Step target Number
History Type Picklist (online,offline,diy)
Is Active Picklist (Y,N)
Is Archived Picklist (Y,N)
Number Seats Number
Seat Number Number
Number Tickets Number
Fundraising ID Number

Contact

Is Donor Checkbox
Is Fundraiser Checkbox
Funraisin ID Number (ID)

Campaign

Allow Entries Picklist (Y,N)
Allow Tables Picklist (Y,N)
Campaign Type Picklist (event,page,team,raffle)
Event Type Picklist (online,offline,diy)
Created By Fundraiser Lookup(Contact)
Entry Fee Currency
Entry Limit Number
Entry Type Picklist(rsvp,ticketed,registration)
Event Target Currency
Street Address Text
City Text
Country Text
Is Fundraising Event Picklist(Y,N)
Minimum Tickets Number
Maximum Tickets Number

Opportunity

Primary Contact Lookup(Contact)
Fundraiser Lookup(Contact)
Refund Reason Text
Source Opportunity Lookup(Opportunity)
Order Number Text
Tracking Number Text
Donation Type Text
Payment Method Text
Raffle Tickets Number
Raffle Ticket Start Number
Raffle Ticket End Number

Record Types

Record types can be defined within Funraisin simply navigate to Funraisin > Salesforce > Recordtypes. This will allow you to control record types for various transaction types on Opportunities. For other objects e.g. Campaigns, these can be controlled from within the modules that sync to Campaigns which are Funraisin > Events and Funraisin > Pages

Existing Data

Once connected, Funraisin will only sync new data to your Salesforce account. We will not import or alter your existing data in any way.

Technical Notes

Funraisin uses “Funraisin” as its namespace prefix. All custom field names referenced below should include ‘Funraisin__’ as the prefix if they are referenced via an API.

^ Back to top

Mapping

Objects Mapping

The following  list shows how Funraisin objects are mapped to Salesforce objects

Events map to Campaigns
Donation pages map to Campaigns
Teams map to Campaigns
Donors map to Contacts / Accounts
Fundraisers map to Contacts / Accounts
Registrations
map to Campaign Members
Transactions map to Opportunities

Field Mapping

The below tables show the standard field mapping from Funraisin to Salesforce.

Contacts

All donors, fundraisers, shop customers sync to the Contacts object using the following mapping.

Field API Name Description
First Name FirstName  
Last Name LastName  
Email Email  
Mobile MobilePhone  
Phone Phone  
 
DOB DOB  
Title Salutation  
Address Unit MailingStreet  
Address Street Number MailingStreet  
Address Street MailingStreet  
Address Line 2 MailingStreet  
Address Suburb MailingCity  
Address Postcode MailingPostalCode  
Address State MailingState  
Address Country MailingCountry  
Optin Funraisin__Optin__c  

Accounts

All donors, fundraisers, shop customers sync to the Accounts object using the following mapping when organisation data is provided. Note that if no organisation data is provided then household accounts will be used.

Field API Name Description
Organisation Name Name  
Phone Phone  

Affiliations (optional)

When using NPSP you can choose to enable Affiliations.

Field API Name Value
Contact npe5__Contact__c  
Account npe5__Organization__c  

Campaigns

All events, donation pages and teams sync to the Campaigns object using the following mapping.

Field API Name Description
Name Name  
Description Description  
IsActive IsActive  
Status Status  
Event Type Funraisin__Event_Type__c online,offline,diy
Event vs Page Funraisin__Campaign_Type__c Event or Page
Event Date StartDate  
Event End Date EndDate  
Country Funraisin__Country__c  
City Funraisin__City__c  
State Funraisin__State__c  
Postcode Funraisin__Postcode__c  
Address Funraisin__Street_Address__c  
Entry Limit Funraisin__Entry_Limit__c  
Entry Fee Funraisin__Entry_Fee__c  
Online and DIY events Funraisin__Is_Fundraising_Event__c  
Event Target Funraisin__Event_Target__c  
Entry Type Funraisin__Entry_Type__c Ticketed, registration, rsvp
Member Funraisin__Created_By_Fundraiser__c Contact ID of member who created the event

Campaign Members

All participants in an event including offline event guests sync to the Campaign Members object.

Field API Name Description
Event CampaignID  
Member (participant) ContactID  
Event Type Funraisin__History_Type__c  
Is Active Funraisin__Is_Active__c  
Is Archived Funraisin__Is_Archived__c  
Fundraising Target Funraisin__Fundraising_Target__c  
Number Tickets Funraisin__Number_Seats__c  
Fundraising Url Funraisin__Page_URL__c  

 

Opportunities

All financial transactions sync to the Opportunities object.

Field API Name Description
Event, Team or Page CampaignId  
Member or Donor

AccountId

Funraisin__Primary_Contact__c

npsp__Primary_Contact__c

 
Amount Amount  
Transaction Date

CloseDate

Funraisin__Payment_Date__c

 
StageName StageName Closed Won
Donation Type Funraisin__Donation_Type__c  
Payment Method Funraisin__Payment_Method__c  
Member Sponsored Funraisin__Fundraiser__c  
Team Sponsored Funraisin__Team__c  
Related Transaction Funraisin__Source_Opportunity__c  
Refund Reason Funraisin__Refund_Reason__c  

Soft Credits (optional)

A note on Soft credits when donating to a fundraiser. When a donation is related to a fundraiser,  we create an Opportunity Contact Role for the Fundraiser with a role of Soft Credit.

Field API Name Value
Contact ContactId  
Opportunity OpportunityId  
Role Role Soft Credit

Teams

All teams link to the Campaign object which are a sub-campaign of the Event that they are participating in. All opportunities made to a team are then linked to the Team Campaign instead of the Event Campaign.

Field API Name Description
Team Name Name  
Status Status  
Event ParentId Campaign
IsActive IsActive  
Captain Funraisin__Created_By_Fundraiser__c Contact

Products

All merchandise sync to the Products object.

Field API Name Description
Product Name Name  
Product Code ProductCode  

A note on pricebooks. A Standard pricebook called Funraisin Pricebook will be created for use with all products.

Order and OrderItems

All merchandise sales sync to the Order and OrderItems objects as well as the Opportunity object.

Orders

Field API Name Description
ContactID BillToContactId  ID from the synced customer
ContactID ShipToContactId  ID from the synced customer
Po Number OrderReferenceNumber  our own PO number
OpportunityID OpportunityId  ID from the synced opportunity
Status Draft  
Order Date EffectiveDate  Date of Sale

OrderItems

Field API Name Description
OrderID OrderId ID from the synced order (above)
ProductID Product2Id ID from the synced product (above)
Quantity Quantity  

Regular Givers

As part of the NPSP sync you can optionally choose to have regular givers synced to the NPSP RG object.

Field API Name Description
Amount npe03__Amount__c  
Contact npe03__Contact__c  
Date Estapblished npe03__Date_Established__c  
Donor npe03__Donor_Name__c  
Installment npe03__Installment_Amount__c  
Start Date npsp__StartDate__c  
Period npe03__Installment_Period__c weeky, monthly, yearly
Expiry Month npsp__CardExpirationMonth__c
Expiry Year npsp__CardExpirationYear__c
Day of Month npsp__Day_of_Month__c
Status npsp__Status__c Active or Closed

^ Back to top

Custom Fields

For mapping non-standard data such as custom questions that might be asked during registration, or fundraising / fitness related data that doesn't fit into the standard Salesforce data model you are able to add additional custom fields to your standard objects and map them via your Funraisin login.

Simply choose the data source e.g. donor, fundraiser, team, registration which each maps to a specific object e.g. contact, campaign, campaign member. Add in your API field name and select the data you want us to send to that field and we will do the rest.

Web to Lead Forms

Webforms are forms that are created by admins via the Funraisin interface therefore their structure is unknown. Each webform is able to be synced to any Salesforce object with each field within the form having its own mapping to individual Salesforce fields.

Syncing Webforms

1. Choose Object.
Edit your webform and specify which Salesforce Object you want it to sync to by adding in the Object API name.
If this form is part of an event registration flow you can specify which field in your object relates to the ContactID of the fundraiser / donor
Also if this form is part of a registration entry flow you can set the object behaviour to Update, whereas for standard in-page forms that aren't linked to any donor or fundraiser leave it set to insert

2. Sync Fields
After specifying the object we sync to and it's behaviour you will need to map each field in your form to the fields in your object. Simply choose "Form fields" from your webform and then edit each field that you want mapped to Salesforce. Under the "CRM Options" field enter in your field's API name.

For webforms used within event registration or donation journeys, the submission will be linked to the relevant Contact ID however for standard page based forms e.g. contact us forms the submissions can only be linked to a single object.

Error Handling

Any error encountered whilst we are trying to sync data to Salesforce will be logged in your platform, along with the actual payload of data we were attempting to send. You can monitor these errors in Funraisin > Salesforce > Error Log.

Please note that we will comtinue trying to sync your data for as long as there is data needing to be synced, so any errors encountered will simply repeat every hour until they are corrected. This can sometimes make your errors seem more than what they actually are, often it is only a few records that need correcting but due to all the connected records it might appear to be a lot more in your error log.

Our advice is to monitor your error log every few days and then also clear out all errors every few days so you can be assured to be only dealing with the latest ones.

Where possible we will also display Salesforce errors in other parts of the admin where they might relate to. For example if you are viewing a donation record or a transaction record in the admin you will notice a Salesforce errors tab, any errors we encountered related to the record you are looking at will also be displayed here.

Common Errors

Below are some of the more common errors you may encounter.

INVALID_OPERATION_WITH_EXPIRED_PASSWORD: The users password has expired, you must call SetPassword before attempting any other API operations

This generally means that the account you are using to connect with has an expired password. You will need to reset the password in Salesforce and then enter this password, PLUS the new security token into the fields provided in Funraisin > Salesforce > Account

Insufficiant Rights to ID xxxxxxxxxxx

This is the most common error and is Salesforce's way of telling you that one of the IDs we are using is no longer valid. Usually this means that the ID we have on file is old and the most  common cause is that a record has been merged or deleted in Salesforce and not updated in Funraisin. To clear this error you will need to check all related IDs and make sure they do in fact exist in Salesforce and if they don't, update them in Funraisin.

Unable to find Account ID xxxxxx

This is an error from Funraisin not Salesforce and this is telling you that we are not able to sync the record in question as we don't yet have an Account ID on file for the connected record. This will only ever appear wyen trying to create Opportunities and as mentioned, this is usually a temporary error since we generally get the Account ID for any contact on the second sync. The first sync is when we create a contact and then the second snc is usually when we retrieve the household account so usually this error can be ignored. If however you notice this same error appear repeatedly for the same transaction, that then means that we have not yet been able to create the Contact so that would then mean you would need to look into why and look for any other errors related to the donor or fundraiser etc

Which Record?

This is from Salesforce and it is telling you that when we tried to create a Contact there were multiple matches found that fall outside of our standard de-dupe rules and it is asking us which contact we'd like to use. This means that you have additional matching rules in place in your Salesforce account and this is most likely going to stop us from syncing some contacts so our advice is to remove these rules and allow us to use our standard re-dupe matching rules whcih is first name + last name + email address.