In this section:

This feature is currently on Pilot release for a limited number of clients only. If you are interested in participating in the Pilot phase, please speak to your Success Manager.

Salesforce CRM Integration Manual

Updated:

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.

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.

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.
  • 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:

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.

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.

The field will show up on the Emarsys list with a link icon , and the Salesforce field shown in the Source column.r

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

If you are mapping single- or multi-choice fields, you must also map their values. Click the icon next to the field and then map the values in the pop-up.

Here you can also Add new values to the Salesforce field, and the mapped values will be synchronized to the mapped Emarsys field automatically.

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.

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 Process that you want to monitor.
  • Filter the list by Status.
  • Select a Date Range if you want.
Click the refresh icon to update the table with the desired sync events.

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.

Permissions verification

On the Permissions verification tab, you can check whether your user's Salesforce permissions are sufficient to run the application by clicking Check permissions.

Troubleshooting

Emarsys Loyalty

Improve customer lifetime value along the entire journey with more personalized experiences and fewer discounts.

You may also be interested in:

Related articles