Documentation Experience Platform Destinations Guide

(API) Salesforce Marketing Cloud connection

Last update: Mon Jan 22 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Topics:
Destinations

CREATED FOR:

Developer
User
Admin
Leader

Overview overview

(API) Salesforce Marketing Cloud (formerly known as ExactTarget) is a digital marketing suite that allows you to build and customize journeys for visitors and customers to personalize their experience.

IMPORTANT

Note the difference between this connection and the other Salesforce Marketing Cloud connection that exists within the Email marketing catalog section. The other Salesforce Marketing Cloud connection allows you to export files to a specified storage location, whereas this is an API-based streaming connection.

Compared to Salesforce Marketing Cloud Account Engagement which is more oriented towards B2B marketing, the (API) Salesforce Marketing Cloud destination is ideal for B2C use cases with shorter transactional decision-making cycles. You can consolidate larger datasets representing your target audience’s behavior to adjust and improve marketing campaigns by prioritizing and segmenting contacts, especially from datasets outside Salesforce. Note, Experience Platform also has a connection for the Salesforce Marketing Cloud Account Engagement.

This Adobe Experience Platform destination uses the Salesforce Marketing Cloud update contacts API, which allows you to add contacts and update contact data for your business needs after activating them within a new Salesforce Marketing Cloud segment.

Salesforce Marketing Cloud uses OAuth 2 with Client Credentials as the authentication mechanism to communicate with the Salesforce Marketing Cloud API. Instructions to authenticate to your Salesforce Marketing Cloud instance are further below, in the Authenticate to destination section.

Use cases use-cases

To help you better understand how and when you should use the (API) Salesforce Marketing Cloud destination, here is a sample use case that Adobe Experience Platform customers can solve by using this destination.

Send emails to contacts for marketing campaigns use-case-send-emails

The sales department of a home rental platform wants to broadcast a marketing email to a targeted customer audience. The platform’s marketing team can add new contacts / update existing contacts (and their email addresses) through Adobe Experience Platform, build audiences from their own offline data, and send these audiences to Salesforce Marketing Cloud, which can then be used to send the marketing campaign email.

Prerequisites prerequisites

Prerequisites in Experience Platform prerequisites-in-experience-platform

Before activating data to the (API) Salesforce Marketing Cloud destination, you must have a schema, a dataset, and segments created in Experience Platform.

Prerequisites in (API) Salesforce Marketing Cloud prerequisites-destination

Note the following prerequisites in order to export data from Platform to your Salesforce Marketing Cloud account:

You need to have a Salesforce Marketing Cloud account prerequisites-account

A Salesforce Marketing Cloud account with a subscription to the Marketing Cloud Engagement product is mandatory to proceed.

Reach out to Salesforce Support if you do not have a Salesforce Marketing Cloud account or your account is missing the Marketing Cloud Engagement product subscription.

Create attributes within Salesforce Marketing Cloud prerequisites-attribute

When activating audiences to the (API) Salesforce Marketing Cloud destination, you must input a value in the Mapping ID field for each activated audience, in the Audience schedule step.

Salesforce requires this value to correctly read and interpret audiences coming in from Experience Platform and to update their audience status within Salesforce Marketing Cloud. Refer to the Experience Platform documentation for Audience Membership Details schema field group if you need guidance on audience statuses.

For each audience that you activate from Platform to Salesforce, you must have an attribute of type Text linked to the Email Demographics data extension within Salesforce Marketing Cloud. Use the Salesforce Marketing Cloud Contact Builder to create attributes. Refer to the Salesforce Marketing Cloud documentation to create attributes if you need guidance on creating attributes.

The attribute field names are used for the (API) Salesforce Marketing Cloud target field during the Mapping step. You can define the field character with a maximum of 4000 characters, according to your business requirement. See the Salesforce Marketing Cloud Data Extensions Data Types documentation page for additional information on attribute types.

An example of the data designer screen in Salesforce Marketing Cloud, into which you will add the attribute is shown below:
Salesforce Marketing Cloud UI data designer.

A view of a Salesforce Marketing Cloud Email Data attribute group with attributes corresponding to the audience status within the Email Demographics data extension is shown below:
Salesforce Marketing Cloud UI email data attribute group.

The (API) Salesforce Marketing Cloud destination uses the Salesforce Marketing Cloud Search Attribute-Set Definitions REST API to dynamically retrieve the data extensions and their linked attributes’ defined within Salesforce Marketing Cloud.

These are displayed in the Target field selection window when you set up the mapping in the workflow to activate audiences to the destination.

IMPORTANT

Within Salesforce Marketing Cloud, you must create attributes with a FIELD NAME that exactly matches the value specified within Mapping ID for each activated Platform segment. For example, the screenshot below shows an attribute named salesforce_mc_segment_1. When activating an audience to this destination, add salesforce_mc_segment_1 as Mapping ID to populate audience audiences from Experience Platform into this attribute.

An example of attribute creation in Salesforce Marketing Cloud, is shown below:
Salesforce Marketing Cloud UI screenshot showing an attribute.

TIP

When creating the attribute, do not include whitespace characters in the field name. Instead, use the underscore (_) character as a separator.
To distinguish between attributes used for Platform audiences and other attributes within Salesforce Marketing Cloud, you could include a recognizable prefix or suffix for the attributes used for Adobe segments. For example, instead of test_segment, use Adobe_test_segment or test_segment_Adobe.
If you already have other attributes created in Salesforce Marketing Cloud, you can use the same name as the Platform segment, to easily identify the audience in Salesforce Marketing Cloud.

Assign user roles and permissions within Salesforce Marketing Cloud prerequisites-roles-permissions

As Salesforce Marketing Cloud supports custom roles depending on your use-case, your user should be assigned the relevant roles to update your attributes within Salesforce Marketing Cloud. An example of roles assigned to a user is shown below:
Salesforce Marketing Cloud UI for a selected user which shows their assigned roles.

Depending on which roles your Salesforce Marketing Cloud user has been assigned, you would also need to assign permissions to the Salesforce Marketing Cloud data extension which are linked to the fields you are looking to update.

As this destination requires access to the data extension, you need to allow them. For Example for the Email data extension you need to allow as shown below:

Salesforce Marketing Cloud UI showing the email data extension with allowed permissions.

To restrict the level of access, you can also override individual access by using granular privileges.
Salesforce Marketing Cloud UI showing the email data extension with granular permissions.

Refer to the Marketing Cloud Roles and Marketing Cloud Roles and Permissions pages for detailed guidance.

Gather Salesforce Marketing Cloud credentials gather-credentials

Note down the items below before you authenticate to the (API) Salesforce Marketing Cloud destination.

Credential

Description

Example

Subdomain

See Salesforce Marketing Cloud domain prefix to learn how to obtain this value from the Salesforce Marketing Cloud interface.

If your Salesforce Marketing Cloud domain is
mcq4jrssqdlyc4lph19nnqgzzs84.login.exacttarget.com,
you need to provide mcq4jrssqdlyc4lph19nnqgzzs84 as the value.

Client ID

See the Salesforce Marketing Cloud documentation to learn how to obtain this value from the Salesforce Marketing Cloud interface.

r23kxxxxxxxx0z05xxxxxx

Client Secret

See the Salesforce Marketing Cloud documentation to learn how to obtain this value from the Salesforce Marketing Cloud interface.

ipxxxxxxxxxxT4xxxxxxxxxx

Guardrails guardrails

Salesforce imposes certain rate limits.
- Refer to the Salesforce Marketing Cloud documentation to address any probable limits that you might encounter and reduce errors during execution.
- Refer to the Salesforce Marketing Cloud Engagement Pricing page to Download the Full Edition Comparison Chart as a pdf which details the limits imposed by your plan.
- The API overview page details additional limits.
- Refer here for a page which collates these details.
The count of custom fields allowed per object varies according to your Salesforce Edition.
- Refer to the Salesforce documentation for additional guidance.
- If you have reached the limit defined for custom fields allowed per object within Salesforce Marketing Cloud you will need to
  - Remove older attributes before adding new attributes in Salesforce Marketing Cloud.
  - Update or remove any activated audiences in Platform destinations which use these older attribute names as the value provided for Mapping ID during the audience scheduling step.

Supported identities supported-identities

(API) Salesforce Marketing Cloud supports the activation of identities described in the table below. Learn more about identities.

Target Identity

Description

Considerations

contactKey

Salesforce Marketing Cloud Contact Key. Refer to the Salesforce Marketing Cloud documentation if you need additional guidance.

Mandatory

Supported audiences supported-audiences

This section describes which types of audiences you can export to this destination.

Audience origin

Supported

Description

Segmentation Service

✓

Audiences generated through the Experience Platform Segmentation Service.

Custom uploads

Audiences imported into Experience Platform from CSV files.

Export type and frequency export-type-frequency

Refer to the table below for information about the destination export type and frequency.

Item

Type

Notes

Export type

Profile-based

You are exporting all members of a segment, together with the desired schema fields (for example: email address, phone number, last name), according to your field mapping.
Each segment status in Salesforce Marketing Cloud gets updated with the corresponding audience status from Platform, based on the Mapping ID value provided during the audience scheduling step.

Export frequency

Streaming

Streaming destinations are “always on” API-based connections. As soon as a profile is updated in Experience Platform based on audience evaluation, the connector sends the update downstream to the destination platform. Read more about streaming destinations.

Connect to the destination connect

IMPORTANT

To connect to the destination, you need the Manage Destinations access control permission. Read the access control overview or contact your product administrator to obtain the required permissions.

To connect to this destination, follow the steps described in the destination configuration tutorial. In the configure destination workflow, fill in the fields listed in the two sections below.

Within Destinations > Catalog, search for (API) Salesforce Marketing Cloud. Alternatively you can locate it under the Email marketing category.

Authenticate to destination authenticate

To authenticate to the destination, fill in the required fields below and select Connect to destination. Refer to the Gather Salesforce Marketing Cloud credentials section for any guidance.

(API) Salesforce Marketing Cloud destination

Salesforce Marketing Cloud

Subdomain

Your Salesforce Marketing Cloud domain prefix.
For example if your domain is
mcq4jrssqdlyc4lph19nnqgzzs84.login.exacttarget.com,
you need to provide mcq4jrssqdlyc4lph19nnqgzzs84 as the value.

Client ID

Your Salesforce Marketing Cloud Client ID.

Client Secret

Your Salesforce Marketing Cloud Client Secret.

Platform UI screenshot showing how to authenticate to Salesforce Marketing Cloud.

If the details provided are valid, the UI displays a Connected status with a green check mark, you can then proceed to the next step.

Fill in destination details destination-details

To configure details for the destination, fill in the required and optional fields below. An asterisk next to a field in the UI indicates that the field is required.
Platform UI screenshot showing the destination details.

Name: A name by which you will recognize this destination in the future.
Description: A description that will help you identify this destination in the future.

Enable alerts enable-alerts

You can enable alerts to receive notifications on the status of the dataflow to your destination. Select an alert from the list to subscribe to receive notifications on the status of your dataflow. For more information on alerts, see the guide on subscribing to destinations alerts using the UI.

When you are finished providing details for your destination connection, select Next.

Activate audiences to this destination activate

IMPORTANT

To activate data, you need the View Destinations, Activate Destinations, View Profiles, and View Segments access control permissions. Read the access control overview or contact your product administrator to obtain the required permissions.

To export identities, you need the View Identity Graph access control permission.

img-md
w-100 modal-image

Read Activate profiles and audiences to streaming audience export destinations for instructions on activating audiences to this destination.

Mapping considerations and example mapping-considerations-example

To correctly send your audience data from Adobe Experience Platform to the (API) Salesforce Marketing Cloud destination, you need to go through the field mapping step. Mapping consists of creating a link between your Experience Data Model (XDM) schema fields in your Platform account and their corresponding equivalents from the target destination.

To correctly map your XDM fields to the (API) Salesforce Marketing Cloud destination fields, follow the steps below.

IMPORTANT

Although your attribute names would be as per your Salesforce Marketing Cloud account, the mappings for both contactKey and personalEmail.address are mandatory.
The integration with the Salesforce Marketing Cloud API is subject to a pagination limit of how many attributes Experience Platform can retrieve from Salesforce. This means during the Mapping step, the target field schema can display a maximum of 2000 attributes from your Salesforce account.

In the Mapping step, select Add new mapping. You will see a new mapping row on the screen.
In the Select source field window, choose the Select attributes category and select the XDM attribute or choose the Select identity namespace and select an identity.

In the Select target field window, choose the Select identity namespace and select an identity or choose Select attributes category and select an attribute from the data extensions displayed as needed. The (API) Salesforce Marketing Cloud destination uses the Salesforce Marketing Cloud Search Attribute-Set Definitions REST API to dynamically retrieve the data extensions and their linked attributes’ defined within Salesforce Marketing Cloud. These are displayed in the Target field popup when you set up the mapping in the activate audiences workflow.

Repeat these steps to add the following mappings between your XDM profile schema and (API) Salesforce Marketing Cloud:

table 0-row-3 1-row-3 2-row-3 3-row-3
Source Field	Target Field	Mandatory
`IdentityMap: contactKey`	`Identity: salesforceContactKey`	`Mandatory`
`xdm: personalEmail.address`	`Attribute: Email Address` from the Salesforce Marketing Cloud Email Addresses data extension.	`Mandatory`, when adding new contacts.
`xdm: person.name.firstName`	`Attribute: First Name` from the desired Salesforce Marketing Cloud data extension.	-

An example using these mappings is shown below:

When you have finished providing the mappings for your destination connection, select Next.

Schedule audience export and example schedule-segment-export-example

When performing the Schedule audience export step, you must manually map Platform audiences to the attributes in Salesforce Marketing Cloud.

To do this, select each segment, then enter name of the attribute from Salesforce Marketing Cloud in the (API) Salesforce Marketing Cloud Mapping ID field. Refer to the Create attribute within Salesforce Marketing Cloud section for guidance and best practices on creating attributes in Salesforce Marketing Cloud.

For example, if your Salesforce Marketing Cloud attribute is salesforce_mc_segment_1, specify this value in the (API) Salesforce Marketing Cloud Mapping ID to populate audience audiences from Experience Platform into this attribute.

An example attribute from Salesforce Marketing Cloud is shown below:
Salesforce Marketing Cloud UI screenshot showing an attribute.

An example indicating the location of the (API) Salesforce Marketing Cloud Mapping ID is shown below:
Platform UI screenshot example showing Schedule audience export.

As shown the (API) Salesforce Marketing Cloud Mapping ID should exactly match the value specified within Salesforce Marketing Cloud FIELD NAME.

Repeat this section for each activated Platform segment.

A typical example based on the image shown above could be.

(API) Salesforce Marketing Cloud segment name

Salesforce Marketing Cloud FIELD NAME

(API) Salesforce Marketing Cloud Mapping ID

salesforce mc audience 1

salesforce_mc_segment_1

salesforce mc audience 2

salesforce_mc_segment_2

Validate data export exported-data

To validate that you have correctly set up the destination, follow the steps below:

Select Destinations > Browse to navigate to the list of destinations.
Select the destination and validate that the status is enabled.
Switch to the Activation data tab, then select an audience name.
Monitor the audience summary and ensure that the count of profiles corresponds to the count created within the segment.
Log in to the Salesforce Marketing Cloud website. Then navigate to the Audience Builder > Contact Builder > All contacts > Email page and check if the profiles from the audience have been added.
To check if any profiles have been updated, navigate to the Email page and verify if the attribute values for the profile from the audience have been updated. If successful, you can see that each audience status in Salesforce Marketing Cloud was updated with the corresponding audience status from Platform, based on the Mapping ID value provided in the audience scheduling step.

Data usage and governance data-usage-governance

All Adobe Experience Platform destinations are compliant with data usage policies when handling your data. For detailed information on how Adobe Experience Platform enforces data governance, see the Data Governance overview.

Errors and troubleshooting errors-and-troubleshooting

Unknown errors encountered while pushing events to Salesforce Marketing Cloud unknown-errors

When checking a dataflow run, you might encounter the following error message: Unknown errors encountered while pushing events to the destination. Please contact the administrator and try again.
- To fix this error, verify that the Mapping ID that you provided in the activation workflow to the (API) Salesforce Marketing Cloud destination exactly matches the name of the attribute you created in Salesforce Marketing Cloud. Refer to the Create attribute within Salesforce Marketing Cloud section for guidance.
When activating a segment, you might obtain an error message: The client's IP address is unauthorized for this account. Allowlist the client's IP address...
- To fix this error, contact your Salesforce Marketing Cloud account administrator to add Experience Platform IP addresses to your Salesforce Marketing Cloud accounts’ trusted IP ranges. Refer to the Salesforce Marketing Cloud IP Addresses for Inclusion on Allowlists in Marketing Cloud documentation if you need additional guidance.

Additional resources additional-resources

Salesforce Marketing Cloud API
Salesforce Marketing Cloud documentation explaining how contacts are updated with the specified information.

Changelog changelog

This section captures the functionality and significant documentation updates made to this destination connector.

View changelog

table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 6-row-3 layout-auto
Release month	Update type	Description
October 2023	Documentation update	We updated the Prerequisites in (API) Salesforce Marketing Cloud section and in general removed unnecessary references to attribute groups across the document. Updated documentation to indicate that attributes for the audiences statuses should be created within Salesforce Marketing Cloud inside the Email Demographics data extension only. We updated the mapping table within the Mapping considerations and example section, the mapping for `Email Address` attribute within the `Email Addresses` data extension is marked mandatory, this requirement was mentioned in the callout marked IMPORTANT but was omitted from the table.
April 2023	Documentation update	We corrected a statement and reference link in the Prerequisites in (API) Salesforce Marketing Cloud section to call out that Salesforce Marketing Cloud Engagement is a mandatory subscription to use this destination. The section previously called out erroneously that users need a subscription to the Marketing Cloud Account Engagement to proceed. We added a section under prerequisites for roles and permissions to be assigned to the Salesforce user for this destination to work. (PLATIR-26299)
February 2023	Documentation update	We updated the Prerequisites in (API) Salesforce Marketing Cloud section to include a reference link calling out that Salesforce Marketing Cloud Engagement is a mandatory subscription to use this destination.
February 2023	Functionality update	We fixed an issue where an incorrect configuration in the destination was causing a malformed JSON to be sent to Salesforce. This resulted in some users seeing high numbers of identities failed on activation. (PLATIR-26299)
January 2023	Documentation update	We updated the Prerequisites in Salesforce section to call out that attributes need to be created on the Salesforce side. This section now includes detailed instructions on how to do that and best practices around naming the attributes in Salesforce. (PLATIR-25602) We added clear instructions on how to use the Mapping ID for each activated audience in the audience scheduling step. (PLATIR-25602)
October 2022	Initial release	Initial destination release and documentation publish.

recommendation-more-help

7f4d1967-bf93-4dba-9789-bb6b505339d6