Integration with Salesforce

RaiseDonors supports two installation types with Salesforce:

• Nonprofit Starter Pack
• Standard

Nonprofit Starter Pack (NPSP)

Inserts Contacts, which automatically creates Accounts.

An Opportunity is created for each fund designation with a donation. This means that if there is one Fund in a donation, there is one Opportunity. If there are three Funds in a donation, there will be three Opportunities.

You must ensure you've run our custom package, which stores the RaiseDonors Donor.Id field in Salesforce.

Standard

Inserts Accounts, which hold the various opportunities.

After creating Opportunities, RaiseDonors then creates a one-off Contact, which is related to the Account. Unfortunately, the Opportunities are only related to the Account. This is because "out-of-the-box" with Salesforce Standard, there is no relationship between Opportunities and Contacts. Therefore, RaiseDonors stores the opportunities against the Account.

Setup Instructions

Access

To get started, you'll first need to have the following information from your Salesforce account available:

• Username
• Password
• Security token

Your username is the email address you use to login to your Salesforce installation. It's recommended to use a dedicated user for this integration. If you choosed to use an active user's account for this integration - you will need to pay close attention to any password updates or changes. If this user updates his/her password and does not update the password in RaiseDonors, the integration will fail.

Your password is the password you use to login to your Salesforce installation.

To locate your security token, log into your Salesforce installation:

1. Go to My Settings
2. Select Personal
3. Select "Reset My Security Token"

If you are using the Lightning Experience, you can follow these instructions,

If your admin assigned you the “Two-Factor Authentication for API Logins” permission, use the code generated by an authenticator app, such as Salesforce Authenticator, for the security token value.

1. From your personal settings, enter Reset in the Quick Find box, then select Reset My Security Token.
2. Click Reset Security Token. The new security token is sent to the email address in your Salesforce personal settings.

If you have an existing security token and don't know what it is, you'll need to reset it.You may also want to review the SOAP API Developer Guide from Salesforce to understand the relationship of security between RaiseDonors and Salesforce

Custom package

For RaiseDonors to complete account matching (i.e. not creating multiple versions of the same donor in Salesforce), we have created a custom package to be installed in your Salesforce environment.

This package does one thing in your Salesforce environment: it adds a new custom field on the Contact Object named "RaiseDonors_DonorID".

Use this URL to install the package into any organization:
https://login.salesforce.com/packaging/installPackage.apexp?p0=04t1a000000VPUe

if you are installing into a sandbox organization, use this URL to install the package:

https://test.salesforce.com/packaging/installPackage.apexp?p0=04t1a000000VPUe

Configurations

RaiseDonors has complete flexibility when it comes to mapping the data. To get started, download and complete the template attached to the end of this article. Everything in yellow will need to be filled. Once completed, please send the template and any other relevant information to [e-mail].

Generally speaking, the integration works by mapping objects and properties from RaiseDonors to Objects and properties in SalesForce. Here is a list of the objects and properties available from RaiseDonors.

RaiseDonors Objects & Fields 

• DONOR
  • Id
  • FName
  • LName
  • Email
  • Phone
  • Billing Address.Address1/city/state/zip/country
  • Shipping Address.Address1/city/state/zip/country
  • DateCreated
  • LastModified
  • LastModifiedBy
  • LastIPAccess
  • NesletterOptIn (yea, we know it's misspelled)
  • Notes
• Donation 
  • Id
  • Amount (Total)
  • AuthorizationNumber
  • EmailReceiptCopy
  • Last4ofCC
  • MotivationCode
  • SourceCode
  • Status
  • Notes
  • DateCreated
  • LastModified
  • LastModifiedBy
  • LastIPAddress
  • CardBrand
  • PaymentMethod
  • CampaignId
  • DonorId
  • GatewayName
  • GatewayTransDetails
  • TransactionId
  • TestMode
  • Name
  • Email
  • Phone
  • RecurringDonationProfilesId
  • Comment
  • CCExpiry 
• DonationFundAllocations
  • Amount
  • Fund
• Fund
  • Name
  • Code
• Donation.Campaign
  • Id
  • Title
  • Url
  • MotivationCode
  • SourceCode
  • MinDonationAmount
  • DateCreated
  • LastModified
  • LastModifiedBy
  • PayFreqType
  • ProductCode
  • DownloadUrl
  • QuantityIncluded
  • FairMarketValue
  • IsDonation
  • GoalAmount
  • PageContent
  • PageContentTitle
  • PageContentImage
  • PageContentButtonText
  • PageContentVideo
  • PageContentLogo
  • ProductCodeName
  • PublicTitle 
• Miscellaneous 
  • REPLACE_TODAYS_DATE (gets todays date in your timezone)
  • Replace_SalesForceLookup_Contact.AccountId (real-time look up in SF for the account id from a contact)

How do I find my Sales Force Property Name?

• Log into your Salesforce installation.
• Click on Setup.
• On the left navigation menu under BUILD, click Customize.
• Find the object you are searching for (ex: Contacts), and click on Fields.

The table on the right now lists all the fields for the selected object. Be mindful, there are two tables on the right side. It usually simplest to use the search feature of your web browser to locate the field.

Standard Fields
The third column, "Field Name" is the programmatic name we are looking for. The value is the entire word in the 3 column.

Custom Fields and Relationships (usually below Standard Fields)
The third column, "API Name" is the programmatic name we are looking for. The value is the entire word in the 3 column, which can contain odd things like "__c" and "npsp__".

If the fields Data Type is "Lookup", it's a bit trickier. You need to take the fieldName and add an "Id" to the end. For example, look at our sandbox, we need to use the "Primary Campaign Source". The true FieldName in this case would be "CampaignId".

The value to use in this instance is NOT the textual representation of the Campaign. In this case, you'd navigate to the specific campaign you want to use in this instance (to be associated with this donation), and copy the unique ID of the Campaign. That ID is then associated with the "CampaignId".
 

Events to consider

For each event in RaiseDonors, a specific configuration can be built.

• Standard Donation. This is what you'd expect, send the donation and donor information into Salesforce.
• Setting up of a recurring donation. Are there specific business rules that are only applicable when setting up a new recurring donation?
• Instance of a recurring donation. Are there specific business rules that are only applicable to a recurring donation instance (future)?
• Ending/Stopping a recurring donation profile. When a profile is terminated, are there any updates you'd like to be applied to the donor record in Salesforce?
• Modifying a recurring donation profile. When a profile is edited, are there any updates you'd like to be applied to the donor record in Salesforce?
• Refunding or Voiding a donation. When a refund is initiated through RaiseDonors, we have two choices in how to update Salesforce.
  • Keep the original opportunity and perform various updates to the data.
  • Create a new, negative amount entry in Salesforce.
    When keeping the original entry, how would you like the integration to update the opportunity in Salesforce? Perhaps set the Status of the Opportunity to "closed"?
    When creating a new negative opportunity, you'll need to provide the full mapping of information just like you did for "Standard Donation".

Matching donors to contacts

It is completely customizable and up to you! With each mapping you provided in the "Standard Donation", you can assign if it is should be included in the matching logic. You can have as many fields as you wish or as few fields as you wish. In each field, you can specify...

• QUALITY - how specific should we be?
• Exact - must be an exact match (case insensitive)
• First - match the first few letters
• Last - match the last few letters
• None - do not match at all

Each condition you create is aggregated together into an "AND" operator. So if you want to 3 objects in the matching logic, example:

• Donor.FirstName (First - 3 chars)
• Donor.LastName (Exact)
• Donor.BillingZip (Exact)

These will all be placed together as follows, "Does any information in SalesForce have a Donor.FirstName (first 3 chars) AND Donor.LastName (exact) AND Donor.BillingZip (exact) matching?"

Data consistency

In the mapping RaiseDonors can provide the following configurations.

• For State, RaiseDonors can send full-text or ISO2 (example: Texas or TX)
• For Country, RaiseDonors can send full-text, ISO2, ISO3 (example: United States of America, US, USA)

Miscellaneous

What if I have multiple campaign Id's configured in the RaiseDonors configuration?For example, if I have a campaign ID for a one time donation but have a different campaign Id configured for the recurring setup. If both are sent to SalesForce, it will error out. So how does RaiseDonors know which one to use?

We can specify a flag on the 'master' field to use. In the example above, we can specify which campaign Id would be given precedence when one or more are provided. We have a token 'WhenDuplicateEntryUseThisOne' that handles this.