- 1 Confirm Data Center
- 2 Confirm 'Version 2' of the Export API is being used
- 3 Add 'SFDC Contact ID' to Engaging Networks' supporter record
- 4 Setting up connectivity to Engaging Networks
- 5 Setting up a 'Create Contacts' mapping
- 6 Process Opportunity or other objects
- 7 Setup a 'Push mapping' to Engaging Networks
- 8 Scheduling
Confirm Data Center
Engaging Networks currently has two data centers, where clients may be hosted.
For clients hosted in Toronto, Canada - the URL used is https://e-activist.com.
For clients hosted in Dallas, Texas - the URL used is https://us.e-activist.com.
In the examples below, the Toronto URL is used but please use the appropriate URL for where the account is hosted. Additionally, support for the Dallas Data Center is found in package version 1.6.1 or later.
Confirm 'Version 2' of the Export API is being used
Engaging Networks currently supports two versions of the Export API. For implementations, 'Version 2' is required.
Even though upgrading to 'Version 2' is recommended, it is worth letting your team know. This update does increase the outputted columns and moves to a 'three code' type for Transactional Data.
Please note that on changing from Version 1 to 2, there is a day's delay for the system to respond.
Add 'SFDC Contact ID' to Engaging Networks' supporter record
To sync supporters to and from Salesforce, it is useful to also store the SFDC Contact ID on the Engaging Networks supporter's record.
The logic would be that 'new' supporters would not have this field populated and existing would. The latter also means that the mapping step of 'creating new supporters' can be skipped, due to an existing SFDC Contact ID.
To add this field, login to Engaging Networks and head to the Default Supporter Record.
Add a new field, naming it SFDC Contact ID and setting the tag to Not tagged.
It is recommend here to also unselect the 'Available to Forms' option. As a supporter is never going to fill this in manually, via a form, it can be seen as a 'background' field.
Save the field.
If you want to re-order fields (I.E, have SFDC Contact ID at the top), use the Field Order button.
Setting up connectivity to Engaging Networks
This section will show how to configure the connection to the Engaging Networks API.
The example used below focuses around a Non Profit Success Pack installation, with a view of Contacts being where supporter records are stored, using a Bucket Account model.
To allow house holding instead, it is as simple as not declaring anything for the 'Account ID' field mapping. NPSP will automatically create the Account Household, once the Contact is created.
First, Navigate to Setup > Develop > Custom Settings and click the Manage button for Engaging Network Settings object.
Click new to create an item and enter the following in the available fields.
Name*: Integration settings
Note that this name needs to match exactly and is case sensitive.
Engaging Networks Token : Populate with your Engaging Networks account's Private token
Time zone : -5
The EN servers are based in Toronto, Canada. So the default timezone must be set to -5. It is important to note that pulling a days worth of data, is a day in EDT time.
Email : An email address that will receive notifications of any pull issues
Export Group :
Optional, but recommended. See Export Groups under the Default Supporter Record in Engaging Networks.
Export Type : CSV
Do not use anything else
Use [CLEAR] For Blank Fields : Related to pushing constituents back to Engaging Networks. Set to true, any Salesforce object’s field that is empty; will also be cleared in Engaging Networks upon ‘push’.
Note that ‘Decode values’ can also be used in conjunction with the ‘Engaging Networks Mapping’ tool, in order to ‘clear’ select fields. This is useful if only a specific field is requiring this process flow. It is also recommended that values that are pushed back to Opt In questions be decoded to either a Y or N, depending on the supporter subscription to that Opt In list.
Click Save to save your changes
The following fields are used to store error notifications and can be left blank Last Failure Reason Request Fail Counter The following fields are legacy settings and should be ignored. Pull Frequency (in Minutes) Request TimeOffset
Add sObjects to Mapping options
In order to set up which Salesforce objects the connector will use, 'Engaging Networks Mappings' must be configured to list each sObject.
Navigate to Set Up > Develop > Custom Settings and select Manage, next to Engaging Network Mappings.
Select New and populate as follows:
Name: object name or description
sObject Name: the sObject name of the standard or custom object to map to, e.g., Contact
Adding additional objects
Repeat the above step for any Salesforce object you would like to synch data to and from. The following are the most typical ones to use. Be sure to specify the correct API name for any additional custom objects you would like to synch to or from.
Some other example sObject names, that could be used :
rC_Connect__Batch_Upload__c (NGOC Batch Upload object)
Lead (if mapping to leads instead of account and contacts)
For custom objects, please check that the field set Engaging Networks Mapping has been created. This is how the EN Connector knows which fields to render, on the Engaging Networks Mapping tool.
Populating Engaging Networks Import Records
In order to create mappings and test the connector's setup, staging data (Engaging Networks Import Records) is needed.
There are two ways for this.
Either import with example test data (CSV found here)
use the Engaging Networks Manual Pull tool to extract data from the respective Engaging Networks account. (Recommended if the account has data)
This step is also useful to confirm that all headers, from the CSV file, are mapped to the respective fields on the Engaging Networks Import Record. ( See Engaging Networks Import Field Mapping)
MailingStreet, Address 1 and Address 2?
Engaging Networks' offers the following fields to allow a supporter's address to be captured
Address 3 (rarely used on forms)
As Salesforce uses MailingStreet to indicate multiple lines of the address, a decision must be made on how your integration should handle supporter addresses.
Clients have gone two routes :
- Only use Address 1 on the front facing pages
- Use Workflows/triggers to handle the separation and combining of Address 1 and 2 to MailingStreet.
Find example here on handling MailingStreet, for reference, for the Engaging Networks Import Record and Contact sObjects.
A 'known bug' with City and County
An issue has been reported by some clients NPSP, where data populated in the EN_Connector__city__c and EN_Connector__country__c fields are not being passed to Contact > City and Contact > Country respectively; when the mapping processes.
The current workaround/recommendation is to create two new fields on the Engaging Networks Import Record for City and Country. Then have either a workflow copy of the values over or use the Import Field Mapping to re-direct the CSV values to these new fields.
On the Engaging Networks Mapping's Contact rule, use these new fields instead.
Setting up a 'Create Contacts' mapping
Head to Tabs and open up the Engaging Networks Mapping tool.
First select the object to sync to (Contact.) Once selected, make sure New is chosen and then click Load. This will create a new mapping for the Contact sObject.
Name the mapping. As we are dealing with Contacts, perhaps 01. Create new contacts.
Select the Sync Way to Pull from EN.
Set the process to be Create or Update
The Update process leverages Salesforces own Duplication Management tools. It is fairly flexible on how it's set, so further reading can be found here.
Set Auto Update Field to Id -> EN_Connector_sfdc_contact_id__c ( Once a new Contact is created, write it's Id back the the original Engaging Networks Import Record's EN_Connector_sfdc_contact_id__c field )
Uncheck Apply Rule to Avoid Duplicate Records to disabled (Using Supporter Email on the Engaging Networks Import Record, check if a Contact exists against 'Email' ) This is a legacy item and should not be used when leveraging Salesforce's own Duplication Management tools.
For more information on the settings for this tool, see Engaging Networks Mapping.
As this step is dealing with Contacts, the logic is that we want to create new supporters but first check if they exist in SF already ( either by SFDC Contact ID or Email ).
Setting up the pull query filters
Now it's time to set the mapping tool to look into the Engaging Networks Import Record staging table and find the objects that need processing. To do this, the tool uses the 'Pull Query Filter' as the search parameters. ( This becomes even more important when dealing with different types of data and sObjects ).
As the very first mapping to run to run every morning is to create contacts, set the Pull Query filters to be :
EN_Connector_sfdc_contact_id__c = "" (only deal with records that have no prior SFDC Contact ID populated. As the have come from EN, theoretically only new records don't have this field populated)
EN_Connector_last_name__c != "" (Salesforce expects at-least some value to be populated with a Contact. This filter prevents the mapping tool even trying to create a Contact)
Mapping the data to the Contact sObject
Since the Pull Query Filter finds the objects that need processing, how do you now set which data from the Engaging Networks Import Record goes into the Contact sObject? This is where the final set comes in and it is defining which Engaging Networks Import Record fields should map their values to the Contact object.
Decide which Contact fields require population. Obviously, the fields selected here also need data - so make sure that the fields being used are a) correct and b) will have data in them due to setting up the header mappings.
As this example is dealing with a 'bucket account' implementation, note that Account Id is set to always use the value '0011a000004o9jw', with the 'Override with Default' directive. (Please use the Account ID specific to your account)
Note that the Engaging Networks Mapping Field Set is how the tool knows which fields it should make available to the tool.
Do some initial testing
Use the Manually Process Mapping button to trigger the mapping to run. (Outside of scheduling the mappings to run every day, this is the way to manually trigger the mapping)
By adding a 'Pull Query Filter' for EN_Connector_Supporter_Email__c = email@example.com (for example) you could set a test to process specific records.
Depending on the amount of records to be processed, the APEX job will generated batches to run. This can be seen in the APEX > Jobs Monitor.
Process Opportunity or other objects
Once Contacts have been created or updated, next is attaching the relevant transactions to the Contact's record.
This example will focus on creating an Opportunity mapping to map donations, from the Engaging Network Import Record.
Remember that each transaction type is represented from Engaging Networks through the Transactional Data format. Depending on what transaction types an organisation handles and what is wished to be recorded in Salesforce, is how many mappings will be needed.
Handling FCS ( Fundraising Credit Single) transactions
1. Select and add Opportunity as the object mapping
2. Set Synch way to Pull From EN
3. Leave the Auto Update Field parameter blank. This will ensure the record is now marked as processed so the account/contact/action will not be pulled again.
4. Use the type__c filter to map the specific donation type. Create a unique mapping for each donation type as needed (e.g., FCS = single donation).
5. Map the data from the Engaging Networks Import Record to the Opportunity object
Recommended information to use
|SFDC Contact ID||Id of the Contact|
|ID||name of donation page in EN|
|Data 1||unique EN donation id|
|Data 2||unique gateway transaction id|
|Data 6||card type (visa/mastercard etc)|
|Data 13||card Expiry Date|
|Data 34||URL tracking parameter|
|Data 14||gift aid/tax deduction status ( Y or N )|
|Data 34||URL tracking parameter|
|SFDC Campaign ID|
|SFDC Campaign Member ID|
Handling FCR ( Fundraising Credit Recurring ) transactions
Recurring donations (FCR) should be seen differently from the FCS mapping rule. ( Obviously, denoting that they are a recurring gift is the first place to start )
Either using an Opportunity object and setting an additional 'Is Recurring' flag, is one option or using NPSP Recurring Donations. (https://powerofus.force.com/articles/Resource/NPSP-Recurring-Donations-Overview-and-Setup)
It's important to note that Engaging Networks handles the recurring processing and the FCR seen is a 'receipt' of this occurrence. If using NPSP Recurring Donations, it is likely that 'Disabling Scheduling of Nightly Job' is needed.
Setup a 'Push mapping' to Engaging Networks
Setting up a ‘Push to EN’ is similar in setup, in that it will using the same ‘Engaging Networks Mapping’ interface.
The key difference is that the ‘Push to EN’ option should be specified and the respective sObject be declared. This sObject’s data will be what is available to be pushed back to Engaging Networks.
Importantly, there is also a ‘Format Name’ setting which must match the generated CSV file’s header columns to the fields in Engaging Networks. For an overview, see Engaging Networks Mapping + Push to EN.
The most common use case for organizations using the connector is pushing updated Contact information, to Engaging Networks.
A summary of this setup process would be:
- Create a ‘new’ mapping and then specify the Contact object
- Select ‘Push to EN’
- Set the ‘Format Name’ *
- Set the ‘Push mappings’ rules
- Set which fields from the Contact object, are required to be pushed to Engaging Networks.
- Click ‘Create Csv’ – this will generate a downloadable CSV file. This downloadable file then is located under the Mapping Templates interface.
- Download the file and then head to Engaging Networks, Supporter Data > Import Supporters
- Map the imported files headers to the appropriate fields in Engaging Networks. *
- Just before importing, use the 'Saved Format' feature to tie the file to the 'File Format' specified on the mapping.
- Import file
* On first create, this file must be used to import into Engaging Networks in order to create a ‘Saved Format’. This Saved Format will be re-used on each push and tells Engaging Networks which columns in the CSV file, map to which fields in Engaging Networks. As you now have saved the 'File Format', on the next Import Engaging Networks now knows how to map the headers to which fields.
Scheduling the connector is done using native Salesforce Apex scheduling tools. These typically require Administrator level access.
There are two jobs to schedule:
This job sets a pull of a full set of the prior days data from the Engaging Networks Export Service. For example, the job will run today and will pull 'yesterdays' data in its entirety.
This job allows you to run mappings in a specific sequence, daily.
Schedule the daily pull of data from Engaging Networks
To schedule a daily sync, head to Set Up > Develop > Apex Classes and click the button Schedule Apex. For the Apex Class, find and select SchedulePullFromEn.
Set frequency to Weekly and select every day of the week. Select a start time and date in the future as desired. Set a preferred start time.
The Engaging Networks servers run in EDT time. It is thus recommended to set the 'pull' start time to be after 1am EDT. This will allow the connector to pull yesterday's data, based on that it's the current day in EDT. If you have an account in a different timezone, adjust according to make sure the pull time is using the recommended EDT time period.
This job will, by default, pull all prior day records (TODAY - 1) from the EN export service into the staging table. This is controlled in Apex Class RemoteSiteConnection.
Schedule the daily processing of mappings
Set the order the mappings will run
To ensure records are imported and exported in the correct order, create a job order for each mapping created.
Head to Set Up > Develop > Custom Settings and then select Manage for custom setting Engaging Network Jobs.
The following is a example of a run order for first syncing contacts, then opportunities and activities (actions, email opens, etc.)
|2||Process FCS donations|
|3||Process FCR donations (recurring)|
|||[any other transactional record syncs]|
|5||or last Push contacts to EN|
Setup the apex job
To schedule a daily synch, go to Set Up > Develop > Apex Classes and click button Schedule Apex. For Apex Class find and select ScheduleObjectPullAndPush. Set frequency to Weekly and select every day of the week. Select a start time and date in the future as desired. Set the preferred start time a few hours after the prior job to ensure the staging table is fully populated before the current job starts.
Save and your job will run daily in the sequence provided in the Engaging Networks Jobs custom setting.
Use native Salesforce Apex scheduled job-monitoring tool to monitor job progress.