Here you can find all the information you need to set up and work with the Emarsys for Salesforce CRM integration.
This guide assumes that you already have a working Salesforce CRM instance.
Summary of the integration
The Emarsys for Salesforce CRM integration enables Contact and Lead data synchronization between Salesforce and your Emarsys account, and harnesses the functionality available in the Emarsys Marketing Platform for your Salesforce CRM data.
Salesforce differentiates between Contacts and Leads, but refers to them both as objects. When a contact or lead is added to a campaign they are described as members. This integration manual follows the same convention.
This integration assumes that Salesforce CRM is your primary database for contact and lead data. With the exception of opt-in and campaign responses, data is synced from Salesforce to Emarsys only and in the case of different values, the Salesforce value will always overwrite the Emarsys value.
Matching leads and customers in Salesforce to contacts in Emarsys
The Emarsys for Salesforce CRM integration is based on the long Salesforce ID that is the primary matching key. If this key is not available in Emarsys, then the email address is used as a fallback.
The logic behind matching contacts
The system checks whether the following condition is fulfilled or not:
Does the contact in Emarsys match the long Salesforce ID of a customer or lead?
- If this answer is yes, then the matched contact will be updated.
- If this answer is no, then the system checks whether the following condition is fulfilled or not:
Is there a contact in Emarsys who matches the email address of a customer or lead in Salesforce and who does not have any long Salesforce ID in Emarsys?
- If the answer is yes, then the matched contact will be updated.
- If the answer is no, then a new contact will be created.
Features enabled by the Emarsys for Salesforce CRM integration
The following features are enabled by this integration, and are listed in Salesforce as Solutions:
- Add Campaign Member-Trigger External Event - Every time a new member is added to the Salesforce campaign, their complete record is sent in a JSON package to Emarsys with the respective external event ID. From there they are processed according to whatever campaign(s) the event is linked to.
- Add/Remove Campaign Member-Contact List Member - For email campaigns, as members are added to/removed from the Salesforce campaign, they are also added to/removed from the corresponding Emarsys launch list.
- Campaign Response Summary - Syncs back the campaign-level reporting to the Salesforce campaign (ad hoc and event-driven email campaigns).
- Contact Email Responses - Syncs back the object-level reporting to the Salesforce campaign.
- Contact Synchronization - Syncs all the Salesforce Contacts which fulfill the filter criteria to Emarsys.
- Emarsys OptIn Change to Salesforce - Syncs changes to the Emarsys Opt-in field (e.g. via campaign unsubscribe links) to the Salesforce EmailOptOut field.
- Initial Sync Campaign Members - Syncs the Salesforce campaign members to the launch list of the linked Emarsys email campaign.
- Initial Sync Trigger External Event - Passes the Salesforce campaign members to Emarsys in a JSON package with the linked Emarsys external event ID. From there they are processed according to whatever campaign(s) the event is linked to.
- Lead Synchronization - Syncs all the Salesforce Leads which fulfill the filter criteria to Emarsys.
- Salesforce Contact OptOut Changes to Emarsys - Keeps the opt-in value of Contacts in sync between Salesforce and Emarsys regardless of whether the change occurred in Emarsys or Salesforce.
- Salesforce Lead OptOut Changes to Emarsys - Keeps the opt-in value of Leads in sync between Salesforce and Emarsys regardless of whether the change occurred in Emarsys or Salesforce.
1. Salesforce CRM requirements
From Salesforce CRM you will need:
- A Salesforce CRM integration user account (separate from your system admin or standard application users) with access to all standard fields on Accounts, Contacts, Leads, Campaigns and Campaign Members objects. You will need this user’s credentials during App Registration.
- The security token for this integration user. For details on how to fetch this from Salesforce, see here.
- All users who use Emarsys App (including the integration user) should be marked as Marketing user. This is not the case by default. To do this, search for the user in your Salesforce account, open the user record and make sure the Marketing user checkbox is selected.
- The Email Opt Out field should have Editable visibility on Contact and Lead objects for all users of the App (including the integration user). This is typically not the case with new Salesforce accounts. You must do this for both Contacts and Leads:
- Open the properties page for each object and click Fields.
- Find the Email Opt Out field and open it.
- Click View Field Accessibility.
- Select the required user profiles and set Editable access for the field.
- All the Salesforce campaigns that you want to sync to Emarsys messages must:
- Have Active checked.
- Have a unique name.
- Have an End Date in the future (>= today).
- Have at least one Campaign Member added.
- The custom page layout used for the Salesforce campaigns must be assigned to all the App users (otherwise the Emarsys button will not be displayed).
2. Emarsys requirements
From Emarsys you will need:
- A fully set up and working Emarsys Marketing Platform account.
- The URL for the plugin, available from Emarsys Support.
- Your Emarsys API credentials.
- An external event and campaign for each one of your mapped Salesforce campaigns (see below).
- All the custom data fields that you need to map to Salesforce fields.
- A custom field, the type of which should be alphanumeric (default) and the name of the custom field must be salesforce_id. This field will contain the long Salesforce ID string that identifies each of your customer and lead in Salesforce.
Installing the integration
To install the integration, enter the URL you have been provided by Emarsys Support. There are two URLs available:
- For installation on a live Salesforce CRM account:
- For installation on a Salesforce sandbox:
These URLs will ask you to sign in to your Salesforce account. When you have done so, you must enter your Emarsys API credentials (not your Emarsys account credentials).
When installation is finished, you will see a new menu entry: Emarsys.
Mapping data fields
You will need to map the data fields between Salesforce CRM and Emarsys. These fields can be used for any available Emarsys functionality, from personalization to segmentation and customer lifecycle scoring.
To map the data fields, open the Mapping tab. On the left you will see all your Salesforce data fields, and on the right those from your Emarsys account.
You must map fields separately for Contacts and Leads, by clicking the appropriate button.
1. The default field mapping
Every time an app user is created they automatically have a default mapping for the data fields.
You can reset your integration to this default schema at any time by clicking Reset.
2. Searching for data fields
You can filter the list of data fields by entering keywords in the dynamic search field on the left.
You can also filter the list by field type, using the drop-down on the right.
3. Rules for mapping fields
- You can map the same Salesforce CRM field to multiple Emarsys fields. The integration does not check for this. The link icon will tell you whether a field already has a mapping.
- You can only map one Emarsys field to a Salesforce CRM field. If the Emarsys field already has a field mapped to it, the new mapping will overwrite the old. The link icon will tell you whether a field already has a mapping.
- The integration does not check to see if you have mapped fields of different types.
Make sure that you map Emarsys fields of the same type, even if they are both text fields. If the field type is not appropriate for the data, you will run into problems when creating segments in Emarsys based on these fields.
4. Mapping and unmapping fields
When you have found a Salesforce field and the Emarsys field you want to map it to, simply drag the Salesforce field over the Emarsys field and release the mouse button.
To unmap a field, click the link icon with the plus sign on the right.
- If you click this icon next to the Salesforce field, this will be unlinked from all Emarsys fields mapped to it.
- If you click this icon next to the Emarsys field, this will be unlinked from its Salesforce field.
When you have mapped your fields, click Save to push the mapping to the middleware platform.
Filtering which objects to sync
You define which Contacts and Leads are synced to Emarsys via a filter. There is only one filter, and this determines which Salesforce objects are processed by all the integration solutions. If you change the filter, the new criteria will apply as soon as you save them. To set up your filter, open the Filters tab.
You must filter Contacts and Leads separately, by clicking the appropriate button.
Define as many filter criteria as you like, based on your Salesforce data fields. Filter criteria are always linked by the AND operator.
After you save your settings, only Salesforce objects who meet the filter criteria will be synchronized to Emarsys.
This filter is only used to determine which Contacts and Leads are synced to Emarsys. You should use the many segmentation options in Emarsys to fine-tune your campaign launch lists or for content personalization.
Making the initial data sync
When you have mapped your data fields and filtered your Salesforce CRM database so that the right objects are synced to Emarsys, open the Sync tab to make the initial manual data sync.
You can either turn Live Sync on or off. If live sync is turned on, then updates will immediately trigger an API call whenever a record is added or modified in Salesforce.
You must also sync Contacts and Leads separately. First click Contacts and then click Sync Options to open the Full Sync Settings dialog.
Choose from the following Sync Options according to your requirements:
- Overwrite Emarsys data (all mapped fields will be overwritten in Emarsys)
- Keep Emarsys data (Email Opt Out for all matched contacts will be overwritten in Salesforce)
If you have a new data field and you would like to populate it for your contacts in Emarsys, then choose the Overwrite Emarsys data (all mapped fields will be overwritten in Emarsys) option.
When are ready, click Start Sync Now to make a manual sync of all the Salesforce Contacts returned by your filter (and their complete records) to Emarsys.
When the sync is finished, repeat this for Leads.
Monitoring your integration
On the Monitoring tab you can check the status of past sync events.
- Select the Process that you want to monitor.
- Filter the list by Status.
- Select a Date Range if you want.
You can then browse the list for any solutions which failed or returned an error. A list of the errors, their reasons and suggested solutions is provided in the Troubleshooting, below.
Processes that were executed successfully are not listed on the Monitoring tab.
On the Permissions verification tab, you can check whether your user's Salesforce permissions are sufficient to run the application by clicking Check permissions.