Salesforce Connector – Additional setup items and considerations

To help in the management of the Engaging Networks <> Salesforce integration, it is recommended that the following be actioned.

Set SFDC Campaign Id as a Campaign Reference

Under Account Settings, Campaign Reference 6 should be enabled and labeled SFDC Campaign ID.

image-20240701-150617.png

See Campaign Linking for instructions on implementation.

Receive Contacts and Transaction push notifications

To receive email alerts on Contact and Transaction push issues, Inside Engaging Networks and under your User preferences, update the page to have the Integrations option checked.

Expose ‘Contact Id’ under Lookup Supporters

A useful account management addition is to expose ‘Contact Id’ on the Lookup Supporters > Manage Supporter gadget.

This will allow an Engaging Networks user to view and/or update the Contact Id that references the supporter to Salesforce.

When using the search function Contact Id will be exposed in the first column.

Supporters/Contacts – sync active segments

Before going live, ideally both Engaging Networks and Salesforce are manually synced so that each system is as true to each other as possible, historically speaking.

Clean data will produce a smoother integration and determining which segments will be most active will allow supporters and their transactions to match the right Contacts from the start.

At the time of importing Contacts into Engaging Networks or Supporters into Salesforce, it is recommended that the data is in good health. This could include personal data, subscription lists, segmentable fields etc.

It is not a requirement to import all Contacts into Engaging Networks, but consider syncing Contact Ids that have active recurring donations, active advocates/fundraisers and those that are emailed.

Examine user flows between both systems if all Contacts/Supporters are not going mirrored prior to going live. The Engaging Networks sync offer the ability to ‘Clear’ blank fields coming over from Salesforce. You would not want to ‘wipe’ good data in Engaging Networks due to a ‘new Contact’ in Salesforce updating an existing supporter in Engaging Networks.

It is therefore essential to decide which system is the most up to date for key pieces of data.

For example, a scenario you do not want to action is :

Engaging Networks holds the most recent ‘Opt In’ data for supporters.

An admin exports all Salesforce Contacts and overrides valid ‘Opt In’ data for supporters in Engaging Networks.

This would also be true if the Salesforce admin adds the ‘Opt In’ to the Contact Mapping and Salesforce has not been mirrored, prior to launch. If a Contact is updated in Salesforce, it will be pushed to Engaging Networks and will override valid preferences in Engaging Networks.

Confirming with key stakeholders in the process as to what data should live in each system is an important milestone.

Export Contacts and Importing in Contact Id

To import Contact information into Engaging Networks, first extract Contacts from Salesforce and ensure Id has been included.

Inside Engaging Networks, head to Data & Reports > Import and select the file.

Next, map the headers to the supporters fields. Map with files header fields with paying close inspection that Id maps with Contact Id.

After confirming the mapping is correct, clicking Import will trigger the process. When the job has been completed, you can spot check the import by looking up the supporters using Data & Reports > Lookup Supporters.

How to handle historical transactions

Before going live, another important step is ascertaining which data flows need to set up.

Where you are with each system and the modules employed will determine if Campaigns or Recurring Donations need to be created.

At this time, Engaging Networks only transfers transactions made after the ‘Transaction Sync’ is enabled. Historic transactions will need to be manually transferred to Salesforce if your organization wishes to represent the data.

Two prime examples of this are ‘active’ campaigns and existing recurring donations.

Active Campaigns

If you are wanting to mark petition (PET) takers as CampaignMembers, then the corresponding Campaign needs to exist in Salesforce. Furthermore, you will need to link the page in Engaging Networks to the Campaign by utilizing the ‘Campaign Linking’ feature.

When a page is ‘linked’ to a campaign, staging objects will have both SFDC Contact Id and SFDC Campaign Id populated. With these two values pre-populated, the transaction engine can attach the petition as a CampaignMember.

Recurring Donations

It is useful to keep in mind that Engaging Networks handles recurring donations as follows:

  • The initial signup – which is both a commitment and an initial transaction – comes in as an FCR transaction, with no parent identifier in the staging record (Transaction Data 11 = blank)

  • With this initial FCR, the Gateway identifier (Transaction Data 2) is the “parent identifier” for all subsequent transactions

  • Subsequent transactions (automated charges the next month) come in as FCR transactions, with Transaction Data 11 pointing back to the “parent identifier” provided with the initial transaction

If your implementation has the concept of a “parent commitment” vs “individual/subsequent transactions”, then you will need to load parent identifiers for your ongoing recurring donors into Salesforce, so their ongoing (e.g. month-to-month) donations can process properly.

If you are using the default NPSP mappings, this looks as follows:

  • Recurring Donations are represented within Salesforce using the NPSP Recurring Donations object. Each transaction (the month-to-month credit card charges) are represented as individual “child” Opportunities under one “parent” Recurring Donation object.

  • You need to load the Parent Transaction Id from Engaging Networks into your ongoing, active Recurring Donations in Salesforce, so the ongoing recurring payments can be processed.

If you are new to Engaging Networks: The process is easy. During your Engaging Networks onboarding, the Client Support team will load your credit card tokens into Engaging Networks. When this happens, it will generate “initial” FCR transactions, which the Salesforce connector will pick up (provided it is active) and create fresh Recurring Donation objects for you. No further action is needed.

If you are an existing Engaging Networks user, new to the Salesforce Connector: The process requires loading the Parent Gateway Id from Engaging Networks into the “EN Parent Transaction Id” field (engaging_npsp__EN_Parent_Transaction_Id__c) on your existing Recurring Donations. You can retrieve the Parent Gateway Ids through the Export tool in Engaging Networks:

  1. Data & Reports > Export > New Query

  2. Under “Build your Universe”, select the fundraising icon, then add “All Donation Pages”

  3. Select Payment Type = recurring

  4. Run the query, and export in Transactional Format

When you download the file:

  1. If using Excel, be sure to ‘Import CSV’ and mark all fields as Text. This will prevent excel automatically altering date and numbers into different formats, than the original file.

  2. Delete all rows where Transaction Data 11 is populated (you want just the rows representing initial sign up, where Data 11 is blank)

  3. You may wish to do further data work to identify only your active recurring donations – this export will contain your full recurring history since onboarding to Engaging Networks. This can be done through a ‘Profile’. Reach out to a supporter representative for further information.

  4. From these remaining rows, load Transaction Data 2 into “EN Parent Transaction Id” on your existing Recurring Donations in Salesforce. (If you do not yet have Recurring Donations in Salesforce – e.g. you are new to Salesforce or haven’t used the RD object before – then you’ll be generating new Recurring Donation objects instead of loading into existing data. When you create a new RD, ensure likewise that Transaction Data 2 is loaded into the “EN Parent Transaction Id” field.)

Manually Importing Transactions from the Export API

To recover transactions that failed to push from Engaging Networks to Salesforce during the nightly sync, you will need to export the transactional data from Engaging Networks and populate this data into the Engaging Network Staging Records in Salesforce.

Fortunately, Engaging Networks provides a variation of the export file (type = sfdc) that is formatted for easy mapping into Salesforce

  1. Open the Export data service for your data centre:

    1. U.S. Data centre: https://us.engagingnetworks.app/index.html#login

    2. Canada Data centre: https://ca.engagingnetworks.app/index.html#login

  2. Enter the following parameters:

    1. Your API token (look this up in Engaging Networks > Account Settings > Tokens) *your API token provides full access to Engaging Networks supporter data and should never be communicated by email or exposed to other users in your organization

    2. Start Date & End Date for missing transactions (note, if there was a failure on Dec 7, it’s the prior’s day data (Dec 6) that will be missing in Salesforce)

    3. Type = sfdc

  3. Submit Form

  4. Save the exported CSV file somewhere secure

The next step is to load this data into Salesforce using your favorite importer. The export file works particularly well with Salesforce Workbench or Jitterbit – you will not need to map each column manually because the column names already contain the necessary Salesforce API names.

For workbench:

  1. Open https://workbench.developerforce.com/login.php

  2. Authenticate using your Salesforce username & password

  3. Go to Data > Insert

  4. Select Object Type: engaging__Engaging_Networks_Staging_Record__c

  5. Upload your file & click Next

  6. On the next screen, the field mappings should already pre populate based on the column names in the CSV file. Click Next.

  7. Confirm the import

You should see success for all imported records.

Occasionally Workbench may report an error importing the User Agent field due to uniqueness constraints. If you see this, repeat the steps above, but at the field mapping stage (step 6), simply unmap the User Agent field.

Once all missing data has been imported to Engaging Networks Staging Records, it will be processed the next time your Mapping Rules run overnight. If you wish to expedite processing, you can manually run each of your mapping rules, in sequence, from the Mapping Rules tab in Salesforce.

Considerations

Existing Engaging Networks clients

As an existing Engaging Networks client, you will have been creating pages, sending emails and taking single and recurring donations etc. from supporters.

Upon wanting to integrate with Salesforce, you will need to decide which pages are currently active and utilize the ‘Campaign Linking’ function so that transactions can roll up to Campaigns.

Transactions that occurred prior to turning the sync on, will need to be manually uploaded.

As an integrator, work with key stakeholders to decide how to represent historical data inside Salesforce.