About the connector

From EN Salesforce Integration
Revision as of 10:49, 24 October 2017 by Danatengaging (Talk | contribs) (Assumptions)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

How it works

The connector, using the APEX scheduler, calls the Engaging Networks’ Export web service to receive a full snapshot of ‘yesterdays’ data, in a CSV format.

This transactional data snapshot includes all the advocacy, fundraising, email, questions activity etc. that supporters have taken part in, during the time period.

Once the data is retrieved from the API and the CSV file processed via the connector; transactions are stored in a ‘staging table’ of unprocessed ‘Engaging Networks Import Records’ objects.

This list of objects is held in the table, awaiting processing, and is what the ‘Engaging Networks Mapping tool’ uses to decide what information to process.

The mapping tool (Engaging Networks Mapping) is key to assigning the information to objects in Salesforce. By setting ‘pull filters’ to assert which data in the Engaging Networks Import Records table holds, Contacts / Opportunities etc. you can decide the rule set to which order and what objects are created.


The connector is built to leverage the Engaging Networks data API and Salesforce’s object model. In this, it is a flexible tool that is designed to hopefully solve most installations and process flows.

The tool also leverages Salesforce's native 'de-duplication' mechanisms, to handle updates.

Installation and configuration does require a high level of Salesforce knowledge. Understanding that information must be mapped to objects and how those objects interact in Salesforce, is at the core of the connector.

As both Salesforce and Engaging Networks are flexible in setup, knowing how each is currently tailored for the organizations needs is crucial syncing the data between them.

Currently Engaging Networks is supporting two data export formats, 'version 1' and 'version 2'. Version 2 must be used, so please check with support that the organisation's account has it is applied.


Engaging Networks recommend either using one of our experienced partners, a knowledgeable freelancer or an internal Salesforce administrator to take charge of setup and maintenance.


- Please use EN_Connector_supporter_email__c as the field that holds the Email Address.

- Salesforce’s workflows are obviously powerful tools to help process the data. These can be used on the Engaging Networks Import Record object itself (to copy / change data on the fields) and/or once Contact / Opportunities are created etc.

- Engaging Networks is responsible for processing recurring donations. The transaction record (type FCR) seen in the export is either the first submission or subsequent ‘receipt’ that it has been processed again for that month. It is probably more useful to flag this in an Opportunity, instead of using NPSP Recurring Donation object.

- Using a Salesforce developer account to test the mapping process is recommended

Non profit success pack

- The Non Profit success pack can offer additional options of junction objects between Contacts Roles and Opportunities. (If installed, check that the latest version is used)

NGO Connect

- Target the rC_Connect__Batch_Upload__c object


This document serves as only a guide. Depending on the packages used and which objects, the Salesforce setup could be different.

It is recommend that testing is done prior to launching and processes related to your organization analyzed for correctness.

General setup process

In general, the setup of the connector would follow this process.

1. Map out the business rules for data coming through to Salesforce, with a respective plan of which data will be mapped to Salesforce objects.

a. Confirm if it is a one way or two way sync

2. Create a Salesforce user for the connector

3. Create an Engaging Networks user and it’s private token *

a. Confirm which constituent fields in the Engaging Networks account are required to come through to Salesforce. (See Default Supporter Record and also Export Groups)

b. Create an appropriate ‘Export Group’ for this Salesforce sync.

* Requires ‘Super Admin’ access in Engaging Networks.

4. Use [[1]] to download an example file, using the respective private token and ‘export group’. (Make sure to specify type as CSV)

This file will hopefully contain transactions and show which headers are present. If the file is blank however, then check with the account users about what data is in the account and if test records can be created.

5. Install the EN Connector package

6. In Salesforce, head to Setup > Develop > Custom Settings and update:

a. The ‘Engaging Networks Settings’ object with the appropriate token and settings for the Salesforce connector.

b. Add which Salesforce objects the connector will be using, in the ‘Engaging Networks Mapping’ object. (Contact / / Lead / Opportunity / SomeCustomObject__c etc.)

c. Have a look at the ‘Engaging Networks Import Field Mapping’ object and keep in mind that you have to map unknown* constituent columns, in the CSV file, to fields on the Engaging Networks Import Record.

* If not a default field created in the Engaging Networks Import Record.

7. Use the ‘Engaging Networks Manual Pull’ tool to verify that the token is correct and that all ‘constituent’ headers are mapped.

a. If any errors are found, whilst connecting to the API, the tool will send a message to the email address set in the Engaging Networks Settings object.

For example, if there is a ‘yet to be mapped’ field called ‘Import Tag’ in the CSV file, the email would contain the following:
Unmapped column: Import Tag

This would require either removing the constituent header from the Export Group in Engaging Networks or adding a rule to the ‘Engaging Networks Import Field Mapping’ in Salesforce. (See ‘Key bojects > Engaging Networks Import Field Mapping’)

8. Head to Engaging Networks Mappings and start creating the relevant ‘rules’ for mapping the data in Engaging Networks Import Records to Salesforce objects.

This is where most of the ‘heavy lifting’ will be done to make sure the correct fields get updated.
If a two-way synch is required, create a ‘Push to EN’ mapping rule and generate a ‘test file’. Manually import this test file into Engaging Networks and create a ‘Saved Format’.

9. Run a test phases to confirm mappings are working correctly

11. Sync historic data, between systems.

a. Import all Contacts from Salesforce to Engaging Networks. This will make sure that before going live, EN has the latest SFDC Contact IDs.

b. Import all history 'transactional' information from Engaging Networks.

Depending on how far back you have been with EN, this could be a lot of data.

12. Schedule connector to start pulling data, daily

13. Schedule connector to start processing data, daily

Go live!