Difference between revisions of "Configuration"

From EN Salesforce Integration
Jump to: navigation, search
(MailingStreet, Address 1 and Address 2?)
(A 'known bug' with City and County)
Line 201: Line 201:
  
 
Find example here on [[Handling MailingStreet|handling MailingStreet]], for reference, for the Engaging Networks Import Record and Contact sObjects.
 
Find example here on [[Handling MailingStreet|handling MailingStreet]], for reference, for the Engaging Networks Import Record and Contact sObjects.
 +
  
 
===== A 'known bug' with City and County =====
 
===== A 'known bug' with City and County =====

Revision as of 12:13, 14 February 2019


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.


Navigate to the Data Api settings through Data & Reports > API Options


Confirm that 'Version 2' is being used.

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.


Adding sfdc contact id to dsr.png


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.


Configuration settings

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.

This holds the base configurations for the connector.


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.


Adding Contact


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


Click Save



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.


Adding a custom object


Some other example sObject names, that could be used :

rC_Connect__Batch_Upload__c (NGOC Batch Upload object)

CampaignMember

Contact

EN_Activities__c

Lead (if mapping to leads instead of account and contacts)

Opportunity

Task

Your_Own_Custom_thing__c


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)

or

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 addresses to be captured

Address 1 Address 2 Address 3 (rarely used on forms) City Region Postcode Country

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.

Workaround for City and Country

Setting up a 'Create Contacts' mapping

Head to Tabs and open up the Engaging Networks Mapping tool.


Tabs engaging networks mapping.png


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.


Add a contact sobject to mapping.png


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.


Top settingsfor contact mapping example.png
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)


Pull query filter contact example.png


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.


Setting the fields to populate 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 = your@email.com (for example) you could set a test to process specific records.


Hitting Manually Process Mapping will manually trigger an APEX job for the mapping


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.


Apex mapping job example pullfromsfdb.png

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).


Set Pull filters for the FCS type


5. Map the data from the Engaging Networks Import Record to the Opportunity object

Set which data fields to map to the Opportunity object
Engaging Networks Import Record : Example an FCS transaction


Recommended information to use

SFDC Contact ID Id of the Contact
ID name of donation page in EN
Date of transaction
Time of transaction
Data 1 unique EN donation id
Data 2 unique gateway transaction id
Data 4 amount
Data 5 currency
Data 6 card type (visa/mastercard etc)
Data 13 card Expiry Date
Data 34 URL tracking parameter


Additional options

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:

  1. Create a ‘new’ mapping and then specify the Contact object
  2. Select ‘Push to EN’
  3. Set the ‘Format Name’ *
  4. Set the ‘Push mappings’ rules
  5. Set which fields from the Contact object, are required to be pushed to Engaging Networks.
  6. Click ‘Create Csv’ – this will generate a downloadable CSV file. This downloadable file then is located under the Mapping Templates interface.
  7. Download the file and then head to Engaging Networks, Supporter Data > Import Supporters
  8. Map the imported files headers to the appropriate fields in Engaging Networks. *
  9. Just before importing, use the 'Saved Format' feature to tie the file to the 'File Format' specified on the mapping.
  10. 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

Scheduling the connector is done using native Salesforce Apex scheduling tools. These typically require Administrator level access.

There are two jobs to schedule:

SchedulePullFromEn

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.

ScheduleObjectPullAndPush

This job allows you to run mappings in a specific sequence, daily.


Schedule the daily pull of data from Engaging Networks

Schedule apex.png

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.

Save

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.)

Order Name
1 Create contacts
2 Process FCS donations
3 Process FCR donations (recurring)
[] [any other transactional record syncs]
5 or last Push contacts to EN


Schedule order of mappings.png

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.


Monitor progress

Use native Salesforce Apex scheduled job-monitoring tool to monitor job progress.


Scheduled jobs.png