Salesforce Connector: Installation and Setup

The Salesforce and Engaging Networks connector is designed for advanced Salesforce users to set up. Whilst this page outlines the process for setting up integrations, it is advisable to consult all required stakeholders before beginning the setup and to have read the mapping, syncing, and campaign linking pages to ensure you understand the potential impact on both systems of enabling the connector.

1. Installing the app and authenticating your connection to Salesforce

View instructions for: Installing the app and connecting to Salesforce

The following outlines how to install the Salesforce Connector App for Engaging Networks. If you have added this to your Engaging Networks account, you will receive an access link to install this feature from your Account Representative or the Support Team. Once you’ve received the link, you’ll be ready to install the package.

On the install page;
1. Select: ‘Install for all users’
2. Install
3. Once installed, you will receive a confirmation email from Salesforce.

Picture of installation option for the Salesforce Connector App for Engaging Networks

Validate the install using the Salesforce app launcher > View All

Once installed in Salesforce, assign the “Engaging Networks Connector Administrator” permission to the user’s Permission Set to manage the connector.

Picture of Data and Reports menu in Engagingnetworks

In Engaging Networks, go to data & Reports > integration> Salesforce

Picture of where to find Salesforce intergration option in Engaging Networks

Select Connect to Salesforce to authenticate the connection.

If you wish to link to a sandbox account, tick the “Use test.salesforce.com” option prior to connecting.

Picture of step one of the salesforce intergration in Engaging Networks

Picture of step one and two of intergration completed in Engaging Networks.

For Recurring Gifts: Install the NPSP Extension Package

If your organisation is using Salesforce’s NonProfit Success Pack and representing Recurring Gifts via the Recurring Donation object, then please install the following Engaging NPSP extension package.

Go to: https://login.salesforce.com/packaging/installPackage.apexp?p0=04t4K0000015dwI
On the install page;
1. Select: ‘Install for all users’
2. Upgrade
3. Once installed, you will receive a confirmation email from Salesforce.

Picture of installation option for the NPSP Extension Package

This package will install following two fields, on to npe03__Recurring_Donation__c

engaging_npsp__EN_Parent_Transaction_Id__c
engaging_npsp__EN_Parent_Tracking_Value__c

2. Configure Contact Mapping

View instructions for: Configure Contact Mapping

Once installed and connected, you can configure the contact mapping.

The only required fields to map are Email Address and Last Name. The Salesforce Contact ID, Engaging Networks Client ID, and Engaging Networks Supporter ID will automatically map and indicate the field names in both systems.

In the Salesforce Integration menu in Engaging Networks, select 3. Contact Mapping > Configure Contact Mapping

Picture of step three of the salesforce intergration in Engaging Networks

Match the Engaging Networks Supporter fields, Questions and Opt-ins with the corresponding object in Salesforce.
These fields are mapped by default:
SFDC Contact ID,
EN Client ID
EN Supporter ID
These are required as standard:
Email Address
Last Name

Picture displaying the fields mapped by default

By default, Address 1 is mapped to MailingStreet. If you use Address 1 and Address 2 fields, you shouuld map to engaging__EN_Address_1__c and engaging__EN_Address_1__c.

Select the sync direction by clicking the left < or right > icon.
1. The sync direction for all contact fields can be BOTH, PULL (to Engaging Networks) or PUSH (to Salesforce)
Save > Move onto Salesforce Workflow Setup

Picture showing the syn direction options in Engaging Networks

Creating missing fields, questions or opt-in for mapping

The following are the basic steps to take if you are unable to map a field, question or opt-in from Engaging Networks to Salesforce.

In Salesforce, go to: Setup Menu > Quick Find > SEARCH: Objects and fields > Object manager

Picture of obejects and fields, object manager menu options in Salesforce

In Object Manager > SEARCH: Contact > Select: Fields & Relationships

Pictue of the object manager in Salesforce

Picture of the fields and relationships contact option

Select New > Required Data Type > Next > Add Field Label/ Name > Next > Step 3 > Next > Save
You will then be able to map to this object in Engaging Networks

Picture step one of the new custom field option in Salesforce

3. Set up Workflow Rules

View instructions for: Set up Workflow Rules

To successfully sync Engaging Networks supporters and Salesforce contacts, two flow rules must be created in your Salesforce account.

To do this, you'll need to set up two separate Record-Triggered Flow automations using the Salesforce Flow Builder.

Accessing Flow Builder

When you save the contact mapping, the Salesforce Workflow setup screen displays in Engaging Networks. At this point, you can open Salesforce in a new tab or window.

Image of the Salesforce Workflow setup screen displays in Engaging Networks

In Salesforce, go to Setup Menu > Setup.

Image of the navigation options in Salesforce

Quick Find > Search: flows > Select: Process Automation - Flows > Setup Flows - New Flows > Select: Record-Triggered Flow

Image of searching flows, process automation, flows

When Flow Builder is open, you are ready to build your first rule.

Rule 1: EN Push False

This Flow updates the “EN Last Modified Date” field on the Contact to tell Engaging Networks which Contacts have been updated since the last pull.

Configure Start:

Select Object > *Object = Contact

Configure Trigger > Trigger the Flow when:

A record is created or updated

Image of configure trigger options in Salesforce

Set Entry Conditions > Condition requirements = Formula evaluates to true

Image of set entry conditions menu in Salesforce

On the Engaging Networks Salesforce Workflow Setup, copy the Rule 1 formula into the *formula box > check syntax

Image of rule 1 formula in Engaging Networks

Engaging Networks generates the conditional block dynamically, based on the fields on the Contact Mapping rule. You can add fields to the ruleset if you have additional business rules that fall outside the set of fields that trigger a sync back to Engaging Networks.

For complex sync setups with many fields, the generated formula may exceed Salesforce's character limit. In this case, you can use “Custom Condition Logic is Met” and add the individual fields one by one.

When to Run the Flow for Updated Records = Every time a record is updated and meets the condition requirements

Image when to run the flow for updated records menu in Salesforce

Optimize Flow> Optimize the Flow for = Fast Field Updates.

Image of fast field updates selection in Salesforce

Flow Builder:

Select the plus icon below the Record-Triggered Flow Start box > Add Element > Assignment.

Assignment:

Label = Update EN Modified

Set Variable Values > Variable = + New Resource

Image of set variable values in Salesforce

New Resource:
1. *Resource Type = Formula
2. *API Name = Now
3. Description = N/A
4. Data Type = Date/Time
5. *Formula > Enter Formula = now()
6. DONE

Image of new resource section in Salesforce

Set Variable Values:
1. Variable ={!$Record.engaging__EN_Last_Modified_Date__c}
  *Replace {!Now}, with the above, if the variable is prepopulated
2. Operator = Equals
3. Value = Now

Variable with enter a valid value warning

Save > Save the Flow:
1. *Flow Label = EN Push False
2. SAVE
3. Activate

Image of completed flow for rule 1 in Salesforce

Rule 2: "EN Push True"

During the supporter sync from Engaging Networks to Salesforce, we set the EN Push field to “TRUE”. This means these updates won’t trigger the EN Push False workflow rule, thus preventing an "echo” of immediately syncing the contacts back to EN. This rule sets the EN Push value to “FALSE” when it is set to “TRUE,” allowing contacts to requalify for the previous flow.

Configure Start:

Select Object > *Object = Contact

Configure Trigger > Trigger the Flow when:
1. A record is created or updated

Image of configure trigger menu in Salesforce

Set Entry Conditions > Condition requirements = Formula evaluates to true

*formula > Enter Formula… = engaging__EN_Push__c = True > Check syntax

When to Run the Flow for Updated Records = Every time a record is updated and meets the condition requirements

Image of when to run the flow for updated records menu in Salesforce

Optimize Flow> Optimize the Flow for = Fast Field Updates.

Flow Builder:

Select the plus icon below the Record-Triggered Flow Start box > Add Element > Update Triggering Record.

Image of adding update triggering record element in Salesforce

Update Records:
1. Label = EN Push
2. *How to Find Records to Update and Set Their Values = Use the contact record that triggered the flow

Image of update records label in Salesforce

Image of how to find records to update and set their values menu in Salesforce

Set Filter Conditions:
1. Condition Requirements to Update Record = None—Always Update Record

Image of set filder conditions in Salesforce

Set Field Values for the Contact Record
1. Field = engaging__EN_Push__c
2. Value = $GlobalConstant.False

Image of set field values for the contact record in Salesforce

Save > Save the Flow:
1. *Flow Label = EN Push True
2. SAVE
3. Activate

Image of completed flow for rule 2 in Salesforce

Confirm that the Rules are in place.

Once you've completed the setup of both rules:

Return to the Salesforce Workflow setup screen in Engaging Networks > Check.
I have created and activated both Workflow rules in this Salesforce account >
Continue

4. Set up Transaction Mapping

View instructions for: Set up Transaction Mapping

Once your contacts are syncing, the next step is to set up how Engaging Networks supporter actions are displayed in Salesforce.

To install Transactional mapping, go to 'Data & Reports > Integration> Salesforce > 5. Transactional Mapping: select Configure Transactional Mapping.

Picture of step five of the salesforce intergration in Engaging Networks

On first access, the Transaction Mapping interface will prompt you to bulk-install all default mappings.
1. To do this, select install
2. Or select cancel
  If you’d prefer to choose the transaction mappings to install

Picture of the install default mappings pop up menu in Engaging Networks

Picture of the installed mappings in Engaging Networks

Once you’ve completed the install process for a mapping, you can view* the mapping rules in detail on Salesforce:
1. Open app launcher > Engaging Networks Connector> Mapping Rule

Picture of the app launcher in Salesforce

Picture of the Engaging Networks connector control panel

*Mapping rules can also be viewed and edited in Engaging Networks by selecting the pencil icon next to the relevant rule.

On the mapping rules screen in Salesforce, select the down arrow next to the relevant rule to edit/view it, or manually process it.

Picture of the mapping rules edit option in Salesforce

5. Sync Settings

View instructions for: Sync Settings

The sync settings area in Engaging Networks offers configuration options for push and pull operations. Once you’ve enabled the required setting, click Save.

Contacts:

Setting

Description

When contact data comes from Salesforce, if the field value is blank, then clear the field in Engaging Networks

If a contact's field is empty when pulled, the value is cleared on Engaging Networks for the supporter.

When enabling this setting, one consideration is the impact on existing Engaging Networks contacts from new Salesforce Contacts.

Respect “EN Account ID” on the Contact record

For most integrations, this will likely be unchecked, as its purpose is to help clients running multiple EN accounts consolidate them into a single Salesforce org. When Contacts are pulled, Engaging Networks will only pull Contacts whose engaging__Account_Id__c field matches the client ID. This has no relationship with the Account object or householding.

Data Sync:

Setting

Description

Sync Contact data to Salesforce

Start the job to push supporters as Contacts into Salesforce every twenty minutes.

Upon enabling this sync method, an internal timestamp is configured to the current time. Only supporters who are modified after this time will qualify thereafter. If you turn off the sync, this timestamp will be cleared. On re-enabling, the timestamp will again use the current time.

Disabling and re-enabling this setting can be helpful when importing large files into Engaging Networks that don’t need to be updated in Salesforce.

Matching Rules:
Engaging Networks utilizes Salesforce’s Bulk API to upsert supporters as Contacts. If Matching Rules is enabled, when Engaging Network receives Duplicate errors returned on the batch being imported, a secondary job will run to try find suitable Contacts based on the following rules:

Rule

Description

Fuzzy Matching

Fuzzy match on First Name
Exact match on Email Address
Fuzzy match on Last Name

If a suitable match is found, the ID will be copied to the Contact ID, and the supporter record will be eligible for re-push.

Leverage Salesforce

Exact Match on Email Address

Utilises Salesforce’s native Matching and Deduplication functionality to identify the correct Contact.

Engaging Networks initiates an API request to Salesforce, based on the Contact mapping field settings. Salesforce then responds with an API response based on the Matching and Deduplication rules configured in the respective Salesforce account. If an Email Address is matched, the supporter and contact are linked together using the top options determined by Salesforce’s priority score.

Example of matching API request

It’s important for the Salesforce administrator to configure the necessary rules for this functionality to operate accurately.

Endpoint:

CODE

POST /services/apexrest/engaging/dupcheck

Body:

CODE

{
 "objectType":"Contact",
 "supporterId":1122,
 "fields":{
 "FirstName":"Dan",
 "LastName":"Smoth",
 "Email":"dan@engagingnetworks.net"
 }
}

Response:

CODE

{
   "success":true,
   "objects":
      {
         "supporterId":"1122",
         "duplicates":
            {
               "objectType":"Contact",
               "matchingRule":"EN_Fuzzy_Match",
               "matchConfidence":100.0,
               "id":"0035e000016anXsAAI",
               "emails":{
                  "Email":"dan@engagingnetworks.net"
               },
               "duplicateRule":"Standard_Contact_Duplicate_Rule"
            },
         "duplicateFound":true
      }
   ,
   "errors":

Batchsize:

Setting

Description

Batchsize

Define how many rows of data will be pushed per batch as Contacts. It is recommended to use the highest possible batch size to reduce queues when high-volume contact updates are being made.

If the Batch Size is small and a large update is applied across many supporters, it may exceed Salesforce API limits.

Sync Contact data from Salesforce

Start the job to pull Contacts from Salesforce every twenty minutes. By default, all modified Contacts will be pulled.

Results of these jobs do not appear in the Connector logs; instead, they appear as CRM Data Import jobs in the Job Monitor.

Exclude:

Setting	Description
Exclude	There is an optional ‘Exclude’ filter if there is a requirement not have Engaging Networks pull all Contacts.
Sync Transaction data to Salesforce	Enable the daily transaction sync to push supporter actions to Engaging Networks Staging Records.
Sync Extended Supporter Details	No info
Reflect the merges done in Salesforce	Engaging Networks will enable a job to review the ‘merge audit’ logs produced by Salesforce when contacts are manually merged within Salesforce. This 'merge mirror' job operates concurrently with the Contact 'pull' and 'push' jobs, but does not immediately synchronise changes made in Salesforce. While Salesforce supports merging 3 contacts at a time, the “Reflect merges done in Salesforce” setting only supports the merging of 2 contact records at a time. This feature won’t work if more than 2 contacts are merged at once in Salesforce.

6. Additional setup items and considerations

View instructions for: Additional setup items and considerations

To help manage the Engaging Networks <> Salesforce integration, the following should be actioned:

Set the SFDC Campaign ID as a Campaign Reference

Under Account Settings, Campaign Reference 6 should be enabled and labelled SFDC Campaign ID. See Campaign Linking for instructions on implementation.

Picture of the campaign reference set as the SFDC campaign ID in Engaging Networks

Receive Contacts and Transaction push notifications:

To receive email alerts on Contact and Transaction push issues, Inside Engaging Networks, and under your User preferences, check the Integrations option.

Picture of the notifications setup options in Engaging Networks

Expose Contact ID under Lookup Supporters:

This allows users to view and/or update the Contact Id that references the supporter to Salesforce. When using the search function, the Contact ID will also be displayed in the first column.

To expose Contact ID, go to Lookup Supporters > Search Record > Manage Supporter gadget > Settings Icon > and scroll till you find the fields

Picture of the manage supporter gadget in Engaging Networks

Picture of the SF Contact ID displaying in the Engaging Networks supporter lookup

Export Contacts and Importing in Contact Id:

To import Contact information into Engaging Networks, first extract Contacts from Salesforce and ensure the ID field is included.

Go to Data & Reports > Import > Select the file > Add new records and update existing supporters > Map Data

Picture of the Engaging Networks import process

Map the headers to the supporters' fields, ensuring the ID maps to the Contact ID field > Import
1. When the job has been completed, you can spot-check the import by looking up the supporters using Data & Reports > Lookup Supporters.

Picture of the field mapping required as part of the Engaging Networks import process.