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.
Contents:
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.
This integration uses a middleware platform called Scribe Online, which handles the data synchronization between the two systems. This middleware is monitored and maintained by Emarsys.
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.
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 (ad hoc email campaigns only).
- 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 - Syncs Contact unsubscribes from Salesforce to Emarsys.
- Salesforce Lead OptOut Changes to Emarsys - Syncs Lead unsubscribes from Salesforce to Emarsys.
Prerequisites
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.
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:
https://login.salesforce.com/packaging/installPackage.apexp?p0=04t41000002iZq3 - For installation on a Salesforce sandbox:
https://test.salesforce.com/packaging/installPackage.apexp?p0=04t41000002iZq3
These URLs will ask you to sign in to your Salesforce account. When you have done so, you will see the first step of the installation wizard when you must enter your Emarsys API credentials (not your Emarsys account credentials).
In the second step, enter the credentials for the Salesforce integration user that you created as part of the Salesforce CRM requirements.
Click Link User to install the integration package. This process will take several minutes and your Salesforce account will refresh when finished. There is not need to log out and in again.
When installation is finished, you will see a new menu entry: Emarsys.
On the Welcome tab you will see the details of the two users you entered in the last step of the wizard, as well as a list of the solutions and their statuses.
If you see anything other than a green tick next to a solution, first check the Monitoring tab for more information and then see if this is something that you can fix by referring to the Troubleshooting section. Otherwise contact Emarsys Support.
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.
5. Mapping field values
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 must also sync Contacts and Leads separately. First click Contact and then click Sync Options to open the Sync Schedule Settings dialog.
Select On Demand and then 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.
Synchronization settings
After your initial data load has been made, you should set up the regular scheduled sync of new objects, and updates to existing object records.
The scheduled sync first checks for all Contacts and Leads returned by your filter, and then syncs only new objects or those whose records have been modified since the last sync (the delta).
Click Scheduled, then Recurring and define the frequency of your automated sync. You can also choose to schedule a Once-only sync. This will make a single sync (of the delta) at the specified time.
When you have saved them, your sync settings are shown above the Sync History table. All your previous sync events will later be listed here as well.
Linking Salesforce campaigns to Emarsys email campaigns
You can link Salesforce campaigns to Emarsys email campaigns so that all members who join the campaign in Salesforce (and that are returned by your filter) are passed to Emarsys and added to the corresponding email launch list.
The Emarsys email campaign will return a campaign-level response summary for all email campaign types, and will also return object-level responses for ad hoc email campaigns.
The integration adds two new elements to the campaigns in Salesforce:
- An Emarsys button at the top, to open the Campaign Configuration dialog.
- An Emarsys section at the bottom, to display the current configuration (if any).
If the Emarsys button is not visible, check that the custom page layout used for the Salesforce campaigns is assigned to all the App users.
To link a campaign, open any Salesforce campaign and click the Emarsys button.
When you link a Salesforce campaign to an Emarsys campaign, this will not affect the current campaign members. Once you have saved your configuration, only the new members who are added to the Salesforce campaign will be passed to Emarsys and added to that campaign's launch list.
Linking Salesforce campaigns to Emarsys external events
Monitoring your integration
On the Monitoring tab you can check the status of past sync events.
- Select the Solution 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.