Complete Guide to OneCause Peer-to-Peer & Salesforce Integration
In today’s technology and data driven fundraising world, having your donor data flow between your various applications is critical to nonprofit success. Salesforce is growing as a leading CRM in the nonprofit fundraising space.
To help nonprofits get the most from both their OneCause and Salesforce platforms, we’ve created this comprehensive nonprofit guide.
This newly released guide will walk you through the ins and outs of OneCause and Salesforce integration to help you get the most from your donor data and fundraising software.
- What is the OneCause Peer-to-Peer Salesforce Integration?
- Object Structure Overview
- How OPSI Maps to Salesforce Objects
- Matching: Contact Matching and Creation
- Matching: Account Matching and Creation
- Matching: Overwriting Account/Contact fields
- Matching: Customizing the Contact Matching Algorithm
- Configure: Custom Mapping
- Flowchart: OneCause Peer-to-Peer & Salesforce Integration
1. What is the OneCause Peer-to-Peer Salesforce Integration?
The OneCause Peer-to-Peer Salesforce Integration (OPSI) syncs on-demand or on a daily schedule to upsert (i.e. update or insert) data from the OneCause platform to your instance of Salesforce (SF). Donors and Registrants in OneCause are upserted to your SF Accounts & Contacts, while Donations and Registrations will upsert to your Opportunities.
The OPSI can be installed and set up by your SF Admin.
Once configured, any staff member of your organization should be able to manage the regular processing of data (e.g. Pending Matches).
We recommend only your SF Admin manages any custom mapping to ensure data hygiene and integrity.
Once the OPSI is enabled, the first sync will copy all existing data from OneCause Peer-to-Peer into Salesforce, and subsequent syncs will keep Salesforce updated with new or modified records.
2. Object Structure Overview
The OPSI uses existing SF Standard Objects (such as Opportunity) and creates OneCause Custom Objects in your SF Instance. Since your SF instance will be unique to your Organization, we will not disrupt your Standard Objects by cluttering them with new fields, preferring to send the bulk of our data to the OneCause Custom Objects, which connect to your Standard Objects.
EXAMPLE: Your SF Opportunities will include a few fields about Donations and Registrations that occur in OneCause, but the SF Objects we create called “OneCause Donations” and “OneCause Registrations” (which hang off your Opportunities) will contain much more detail about individual transactions that occurred in OneCause.
Depending on your operational, financial or marketing needs, you may find it useful to write a SF Workflow to copy data from our Custom Objects to the associated Standard Objects to enhance your SF Views or Reports. The OPSI also allows custom mapping to your Standard Objects to meet your needs.
3. How OPSI Maps to Salesforce Objects
A. Standard Objects
These standard Salesforce objects are engaged during the OPSI Sync:
1. Contact & Account
Contact and Account records will be created or updated for new challenge participants, event registrations and donations made in the OneCause platform.
A user in the OneCause platform is uniquely identified by an email address, and only users with valid email addresses will be pushed to Salesforce (i.e. users who participate with only a Twitter or Instagram name will not be pushed unless they complete the registration process by providing an email).
In order to determine if a record should match an existing Contact/Account or if a new Contact/Account should be created, the OPSI Sync platform goes through a matching logic outlined in “Matching: Contact Matching and Creation.”
Once the OPSI is installed in your SF Instance, your Contact records will show relationships with these custom objects: OneCause User, OneCause Registration, OneCause Donation, and OneCause Participant. These relationships are one-to-many.
2. Campaign
Campaigns are created to mirror the hierarchy of OneCause Peer-to-Peer:
• Campaign
• Event
OR if Create Campaigns for Participants is set to true
• Campaign
• Team
• Participant
• Personal Event
• Personal Challenge
• Memorial/Tribute
• Birthday/Anniversary
> Donations (Opportunities) will be associated with the lowest appropriate level of the hierarchy.
> Participants and Donors (Campaign Members linked to Contacts) will be associated with just the top-level Campaign.
3. Opportunity
An Opportunity record is created for each donation or registration transaction. The Opportunity will be populated with the amount of the transaction and will be associated to the Campaign for the page where the donation was made.
Once OPSI is installed, Opportunity records will show relationships with these custom objects: OneCause Registration and OneCause Donation. This relationship is usually one-to-one but can be one-to-many.
B. Custom Objects
1. OneCause User
A OneCause User record will be created with a Master-Detail relationship to the Contact record for each unique user (email address) in OneCause Peer-to-Peer. Since Contacts may have multiple email addresses, there may be multiple OneCause User records for a single Contact.
2. OneCause Campaign (sometimes references as “OneCause Challenge”)
A OneCause Campaign record is created and updated to track information at the campaign level.
The OneCause Campaign object uses the field “OneCause Campaign Id” to stay in sync with our system. Removing or changing data in this field will affect future syncing.
3. OneCause Event
A OneCause Event record is created for each peer-to-peer Event in your peer-to-peer Campaign (including the main event if your Campaign requires event registration to participate).
4. OneCause Donation
A OneCause Donation record contains all the information about online donations in OneCause Peer-to-Peer.
5. OneCause Registration
A OneCause Registration record will be created for each person who registers for an event.
6. OneCause Team
A OneCause Team record is created and updated to track information at the peer-to-peer team level.
7. OneCause Participant
A OneCause Participant record is created and updated to track information at the peer-to-peer participant level.
Note that a participant is distinct from someone who registers for an event. A participant is someone who has a participant page set up (to recruit, make social media posts, complete activities and fundraise). The OneCause Participant record tracks their activities as a participant/fundraiser.
4. Matching: Contact Matching and Creation
The matching process begins by looking at records on your Contacts Object. Each Participant, Registrant, and Donor in OneCause Peer-to-Peer is considered a “User” in OneCause. Users from OneCause Peer-to-Peer are matched to your SF Contacts in this way:
1. The OPSI Sync looks to see if the User has previously been matched to a Contact. If it has, then it maintains that connection.
2. Otherwise, the Sync scores each potential match based on a threshold you set:
a. Perfect match (name, email, and phone or street address)
b. Strong match (name and email)
c. Medium match (email only or name and either phone or address and no email on file)
d. Weak match (name and phone or address but email mismatch)
e. Not a match (name only or less)
3. If there are multiple possible matches, then a Pending Match is created for your review.
NOTES:
-
- Matching on name and email must be exact but are not case sensitive. Therefore “Rich” and “Richard” are considered different names.
- Address matching considers the first 2 or 3 words of the street address along with the ZIP or Postal code to reduce issues like Street vs. ST in the address.
- ZIP code matching is limited to 5 characters or U.S. addresses.
- Matching on phone number throws out all non-numeric characters in the phone number so that formatting is not an issue.
- Once a User is matched to a Contact, that information is stored in a custom record in your SF database. If for whatever reason the match was incorrect or if you need to merge Contacts together, updating that custom user record will cause all future matches to go to the new correct Contact. There is no need to change anything in OneCause Peer-to-Peer.
5. Matching: Account Matching and Creation
If there is no existing Contact to match, a new Contact is created and the Sync will still try to attach the new Contact to an existing Household Account, if appropriate.
6. Matching: Overwriting Account/Contact fields
The Sync does not overwrite existing Name/Address/Email/Phone fields in SF Account or Contact records. By default, it will fill in missing data (such as filling in an Address if it does not yet exist in SF), but the Sync will not overwrite existing fields in your system.
The OPSI philosophy is that your long-term data is more permanent than information provided during a single transaction in our system.
7. Matching: Customizing the Contact Matching Algorithm
The contact matching algorithm of the OPSI Sync can be customized by choosing a different threshold for matching in OneCause under Salesforce > Settings > Contact Settings:
We recommend “Medium” as the best threshold since it will primarily seek to match on emails (which, unlike name, will always be exact). Requiring a Strong or Perfect match means that “Rich” and “Richard” would be a mismatch and fail to tie during a Sync.
While “Medium” is recommended, depending on your email marketing program, you might want to choose “Strong” (if almost all your Contacts have known valid email addresses) or “Weak” (if you think your email addresses might be stale).
8. Configure: Custom Mapping
Your OPSI includes the option to add on custom mapping functionality that can cause specific data to write (or not write) to fields in your SF Instance.
This allows you to maximize the usefulness of synced data your team needs to access.
Custom Mapping can be done on the following SF standard objects:
- Campaign
- Campaign Member
- Account
- Contact
- Opportunity
Any field on your Standard Objects can be mapped to, and there are 4 different ways to map a value:
- Setting a Constant (e.g. writing “OneCause” in a Source field)
- Looking up an ID to connect to a record in your SF instance
- Using JavaScript to specify a value from another OneCause field
- Using JavaScript to evaluate a conditional list of criteria to specify a value from another OneCause field
JavaScript mapping expressions are done through a structured user interface, which writes to a JSON. The JSON can also be edited directly in its raw form as well.
JavaScript matching expressions can contain conditional phrases, it can also transform data (e.g. number to text) and, it can concatenate multiple fields in to one.
Mapping is done on a global level but can be overridden on specific campaigns that need different fields mapped.
9. Flowchart: OneCause Peer-to-Peer & Salesforce Integration
