Salesforce Marketing Cloud

Send your event data from RudderStack to Salesforce Marketing Cloud.

Salesforce Marketing Cloud is a digital marketing automation and analytics tool. It lets you design personalized digital marketing campaigns to engage with users throughout their product journey.

Find the open source transformer code for this destination in the GitHub repository.

Prerequisites

Before configuring SFMC as a destination in RudderStack, make sure to:

Create data extensions

It is highly recommended to create a data extension to store the identify and track calls coming from RudderStack. You must also create the required attributes in your data extension for each trait (identify events) or properties (track events) before sending them to SFMC.

warning
SFMC ignores any traits/properties that are not mapped to the data extension attributes.

For example, if you send an event property like "phone": "+1-202-555-0146" but there is no matching phone column in your SFMC data extension, the property is ignored.

info

Create all the attributes in the data extension in title case regardless of the casing used for the trait/property names in your RudderStack identify/track events.

RudderStack automatically formats the field names into title case before sending the events to SFMC.

When creating data extensions, make sure to check the Is Sendable option if you want to send emails or push notifications based on your events.

The primary key for the Identify data extension is called as the contact key or subscriber key. You must add a primary key called Contact Key for your data extension before sending data to SFMC. RudderStack populates this field with the userId or email (if userId is absent) traits in the identify event.

For track calls, you can set up different primary keys for various events. If you do not set any primary key, RudderStack sets the default primary key to Contact Key. You can specify multiple comma-separated primary keys if you have defined multiple primary keys in your data extension. See the following sections for more information:

Generate credentials to send data

  1. In your SFMC dashboard, go to Apps > Installed Packages.
SFMC installed packages
  1. Create a new package. Then, go to the package and click Add Component.
Add new component in SFMC package
  1. Choose API Integration as the component type and click Next.
API Integration component type
  1. Select the integration type as Server-to-Server and click Next.
S2S Integration type
  1. Note the client ID and secret for this package (listed under API Integration). Specify these credentials in the connection settings while setting up the SFMC destination in RudderStack.

Get started

RudderStack supports sending event data to Salesforce Marketing Cloud via the following connection modes:

Connection ModeWebMobileServer
Device mode---
Cloud modeSupportedSupportedSupported

Once you have confirmed that the source platform supports sending events to Salesforce Marketing Cloud, follow these steps:

  1. From your RudderStack dashboard, add the source. Then, from the list of destinations, select Salesforce Marketing Cloud.
  2. Assign a name to the destination and click Continue.

Connection settings

To successfully configure Salesforce Marketing Cloud as a destination, you need to configure the following settings:

  • Client ID: Enter the client ID associated with your SFMC package.
  • Client Secret: Enter the client secret for the package.
info
To retrieve the client ID and secret associated with your SFMC package, go to your SFMC dashboard, click your name on the top right followed by Setup > Apps > Installed Packages, and select your installed package. The Client ID and Client Secret are listed under the API Integration section.
  • Subdomain: Enter the subdomain associated with your SFMC account. The subdomain is a 28-character string starting with the letters mc. For example, if your Authentication Base URI is https://mcxt4zx444ppr71jd9rp300hdc8y.auth.marketingcloudapis.com/, then the subdomain is mcxt4zx444ppr71jd9rp300hdc8y.

Identify call settings

  • Do not create or update contacts: Enable this setting to disable creating or updating contacts in SFMC via an identify call.
  • Identify data external key: Enter the external key of the SFMC data extension to which to you want to send data from the identify events. You can find the external key for your data extension in the SFMC dashboard by going to Contact Builder > Data Extensions.

Track call settings

  • Map events to external key: Use this setting to map your track events to an SFMC data extension. For more information on this setting, see Map events to external key.
warning
If you do not map an event to an external key and send the event to SFMC, you will receive an "Event not mapped for this track call" error.
  • Map events to Primary Key: Use this setting to map your own primary key for a track event. For more information on this setting, see Map events to primary key.
  • Map events to event definition key: Use this setting to map your RudderStack event to a specific SFMC event definition key. For more information on this setting, see Map events to primary key.
  • Event Name to UUID: Use this setting to assign a UUID as the primary key for a specified event. For more information on this setting, see Set UUID as primary key.
  • OneTrust cookie categories: Use this setting to associate OneTrust cookie consent groups to SFMC.

Identify

You can use the identify event to create or update contacts in Salesforce Marketing Cloud.

warning
RudderStack will not create or update contacts if you enable the Do not create or update contacts dashboard setting.

The following snippet demonstrates a sample identify call in RudderStack:

rudderanalytics.identify("1hKOmRA4GRlm", {
  name: "Alex Keener",
  title: "CEO",
  email: "alex@example.com",
  company: "Alex's Company",
  phone: "+1-202-555-0146",
  state: "Texas",
  city: "Houston",
  postalCode: "12345",
  country: "USA",
  street: "6649 N Blue Gum Street",
  state: "TX",
  createdAt: new Date().toJSON().slice(0, 10).replace(/-/g, "/")
})
warning

Note the following:

  • You must include the userId or email trait in every identify call. Otherwise, the event will fail.
  • Salesforce Marketing Cloud does not permit colons (:) in its Contact Key field. Hence, you must remove any colons in your userId before sending the events.
  • Make sure you do not include nested objects in your events as SFMC cannot handle them.
  • SFMC accepts dates only in the ISO 8601 format and rejects any other datetime format.

Track

You can use the track call to capture user events along with the properties associated with them.

A sample track call is shown below:

rudderanalytics.track("Product Purchased", {
  product_id: "ASIN3556",
  currency: "USD",
  revenue: 77
})

Map events to external key

RudderStack lets you send specific track events to your SFMC data extension to send events or push notifications using the Map events to external key dashboard setting. Enter the track event name and the external key for the corresponding SFMC data extension where you want to send the data. You can add mappings for multiple track events by clicking the Add More button.

info
You can find the external key for your data extension in the SFMC dashboard by going to Contact Builder > Data Extensions.

Map events to primary key

A primary key is required for all track events going to an SFMC data extension. Use the Map events to primary key dashboard setting to map a track event to your own primary key. You can add multiple primary keys by comma separating them.

warning

Note that:

  • The primary key specified in the dashboard setting must match the primary key set in your SFMC data extension.
  • If you do not specify a primary key for a track event, RudderStack creates a primary key called Contact Key by default and maps it to the event’s userId. If userId is absent, RudderStack maps it to email instead.
  • The key specified in the dashboard settings should be present in your event properties.

Map events to event definition key

Use the Map events to event definition key dashboard setting to map a track event to a specific event defintion key. RudderStack uses this setting to send the interaction events to SFMC by leveraging their /events endpoint.

You can find the event definition key in Event Administration section after you create and save the event in your SFMC dashboard.

info
Make sure to include id and email in your track properties as these are mandatory Salesforce fields for the feature to work correctly.

Set UUID as primary key

RudderStack lets you set an automatically-generated UUID as the primary key value for a track event. To do so, enter the event in the Event Name field under Track Call Settings and enable the UUID setting.

info
To add multiple events, click the Add more button and enable the corresponding UUID toggle.

RudderStack automatically generates a UUID and passes it to SFMC as the value for a primary key called Uuid for those events.

warning
You must set Uuid as a primary key in your data extension before using this feature.
warning
The UUID will override the primary key defined for the event in the Map events to primary key setting.

Contextual field mappings

RudderStack automatically collects the contextual properties and passes them to SFMC as data extension attributes. To use these fields, you must set the attributes in the SFMC data extensions with specific naming conventions.

The below table lists the mappings between the RudderStack contextual fields and the SFMC data extension attributes:

info
RudderStack automatically formats the attributes/properties in camel case or snake case to title case.
RudderStack contextual fieldsSFMC attribute name
app.nameApp Name
app.versionApp Version
app.buildApp Build
campaign.nameUTM Campaign
campaign.sourceUTM Source
campaign.mediumUTM Medium
campaign.termUTM Term
campaign.contentUTM Content
localeLocale
userAgentUser Agent
ipIP Address
device.adTrackingEnabledAd Tracking Enabled
device.manufacturerDevice Manufacturer
device.modelDevice-model
device.nameDevice Name
device.typeDevice Type
network.bluetoothBluetooth Enabled
network.carrierNetwork Carrier
network.cellularCellular Enabled
network.wifiWifi Enabled
screen.densityScreen Density
screen.heightScreen Height
screen.widthScreen Width

Questions? Contact us by email or on Slack