Search documentation...

K
ChangelogBook a demoSign up

Salesforce Marketing Cloud

Personalize campaigns in Salesforce Marketing Cloud with rich customer data from your data warehouse

Salesforce Marketing Cloud is a premium destination and is only available on Business tier plans.

Supported syncing

Sync TypeDescriptionSupported Sync ModesAPI Reference
Marketing Cloud ObjectsSync records to Marketing Cloud contactsUpsertAPI Object docs
JourneyTrigger API events to enter and exit contacts from journeys as they're added to and removed from your query resultsAdd, RemoveContact entry docs and exit docs
Data extensionsSync records to new or existing data extensions, using the SOAP API and optionally FTPUpsert, MirrorData extension docs

Salesforce Marketing Cloud setup

Before you can connect Hightouch to Salesforce Marketing Cloud (SFMC), you need to create a package in SFMC on behalf of Hightouch. If you plan on syncing records to data extensions using either mirror mode or upsert mode with FTP, you also need to create an FTP user.

Create server-to-server package

  1. Login to your SFMC instance. Go to Setup.

Opening Setup in SFMC

  1. In the left sidebar, go to Apps > Installed Packages and click New.

Package creation in SFMC

  1. Name your package, for example, "Hightouch Integration." Optionally provide a description, and click Save.

Package creation in SFMC

  1. Click Add Component and select API Integration as the component type. Click Next.

Package configuration in SFMC

  1. Select Server-to-Server as the integration type and click Next.

Package configuration in SFMC

  1. Grant the following scopes:
  • Automation > Journeys: Read, Write, Execute, Activate/Stop/Pause/Resume/Send/Schedule
  • Contacts > List and subscribers: Read, Write
  • Data > Data Extensions: Read, Write
  • Provisioning > Accounts: Read

Package configuration in SFMC

These are the minimum scopes. If you plan on syncing data extension objects using mirror mode or upsert mode with FTP protocol, grant these additional permissions:

  • Data > File Locations: Read, Write
  • Automation > Automations: Read, Write, Execute

If you would like to grant a custom subset of scopes for just the SFMC features you want to use, see the section on custom scopes.

Once you save your permissions, you should see a new API Integration component in your package. Check it has the correct permissions listed under Scope by comparing it to lists above or screenshot below.

Package configuration in SFMC

With the API Integration created, copy the Client Id, Client Secret, and subdomain to enter into Hightouch. The subdomain is the part of the Authentication base URI after https:// and before .auth.marketingcloudapis.com/

Package configuration in SFMC

Create FTP user

You only need to create an FTP user if you plan on syncing data extension objects via FTP. FTP mode can optimize sync performance, especially on high volume syncs (> 1 million records). Learn more about how FTP mode works and its tradeoffs in the FTP section.

If your SFMC instance has parent-child Business Units and you want to sync to a child Business Unit using FTP, you must create the FTP user in the child Business Unit.

  1. In your SFMC instance, go to Setup > Administration > Data Management > FTP Accounts and click Create User.

FTP User creation in SFMC

  1. By default, the FTP Username is your Marketing Cloud Member ID (MID), including the current parent account or child business unit. You can keep the default value.
  2. Enter an Email Address for the new FTP user. This can be the email account you use to login to SFMC or another one. You won't need this address to connect to Hightouch.
  3. Enter a Password for the user. Password complexity requirements combine Marketing Cloud password policy and server-side FTP password requirements. These policies require a minimum of 12 characters and no reuse of the five most recent passwords. Reenter the password in Repeat Password.
  4. Provide the user Full user permissions.

FTP User creation in SFMC

  1. Allowlisting IP addresses is optional. For additional security, you can enter Hightouch's IP addresses. Click Next.
  2. The next screen prompts you to choose your authentication method.
    • If you want to use a password, keep this selection.

FTP User creation in SFMC

  • If you want to authenticate Hightouch to SFMC using an SSH key, select SSH Key. Follow SFMC's instructions for how to add a key. Enter the public key into the SFMC and keep the private key for when you connect to Hightouch.

FTP User creation in SFMC

  1. Copy your FTP Username and either password or SSH private key for entry into Hightouch. Click Save.

Connect to SFMC

You can now connect SFMC to Hightouch. Go to the Destinations overview page and click the Add destination button. Select Salesforce Marketing Cloud and click Continue. You can then authenticate Hightouch to SFMC by entering the Client Id, Client Secret, and Subdomain you copied during package creation. The subdomain is the part of the Authentication base URI after https:// and before .auth.marketingcloudapis.com/.

If you plan on syncing records to data extensions using mirror mode or upsert mode with FTP, enter your FTP user credentials:

  • FTP Username: typically a numeric Marketing Cloud MID
  • Password or private key
    • To use a private key, you must have uploaded the corresponding public key in SFMC
    • If using a private key, you must enter the complete private key, starting with -----BEGIN...PRIVATE KEY-----.
    • If your private key requires a passphrase, enter it as well

File Location

Hightouch will upload files to ExactTarget Enhanced FTP. If you have chosen a different External Key for this location, enter the key to ensure Hightouch is able to access the uploaded files.

File Location External Key

Custom scopes

By default, Hightouch requests permission for Journeys, Contacts, and Data Extensions. If you want to use a subset of these features, you can grant a custom subset of scopes in your SFMC package. After you do this, enter a space-separated list of scopes in the Custom Scopes (advanced) field in the Hightouch destination configuration.

For example, if you want to sync to Data Extensions via the SOAP API, you can grant the following scopes in your SFMC package:

  • Data > Data Extensions: Read, Write
  • Provisioning > Accounts: Read

Then, enter the following scopes in the Hightouch destination configuration:

accounts_read data_extensions_read data_extensions_write

Custom scopes in the Hightouch UI

See the SFMC docs for a full list of scopes.

Note that the scopes listed in Hightouch can't exceed the scopes granted in your SFMC package.

Allowed Business Units

By default, Hightouch can access all Business Units in your SFMC instance that have the installed package enabled. If you want to restrict access to a subset of Business Units, you can enter a space-separated list of Business Unit IDs in the Allowed Business Unit IDs (advanced) field in the Hightouch destination configuration.

You can find the Business Unit ID, or MID, by click on the account dropdown at the top of the SFMC console.

Sync configuration

Once you've set up your Salesforce Marketing Cloud destination and have a model to pull data from, you can set up your sync configuration to begin syncing data. Go to the Syncs overview page and click the Add sync button to begin. Then, select the relevant model and the Salesforce Marketing Cloud destination you want to sync to.

Syncing contacts

This integration supports upserting contacts into Marketing Cloud. In upsert mode, Hightouch inserts new users into SFMC and updates mapped user attributes on existing contacts.

Record matching

Hightouch matches rows from your model to Marketing Cloud contacts by Contact Key. Select the model column that contains these values.

SFMC Contact sync configuration in the Hightouch UI

Contact Keys are different from Contact IDs and email addresses. Check out Salesforce's article to learn more.

Field mapping

You can sync any model columns to Marketing Cloud's contact attributes.

SFMC Contact sync configuration in the Hightouch UI

Ensure all the required fields in each attribute set is completed. For example, to add an email address, be sure to map both Email Addresses.Email Address and Email Addresses.HTML Enabled fields. Refer to the usage section of SFMC's Creating Contacts documentation for a list of attribute sets.

Managing user journeys

Hightouch can manage the entry and exit of contacts in Marketing Cloud journeys based on your model's query results.

  • When a record enters your results set, Hightouch adds a contact to the journey via the contact's Contact Key.
  • When a record leaves your results set, Hightouch removes the contact from the journey via the contact's Contact Key.

Journey selection

Here is an example journey that you could manage with Hightouch:

SFMC Journey example

Note that it's:

  • A multi-step journey
  • Triggered by an entry event with an associated data extension and event definition key

Hightouch automatically looks for the event definition key if you select a journey that fits the preceding requirements.

Journey selection in the Hightouch UI

User identifers

Hightouch enters and exits contacts from the journey via Contact Key. Select the model column that contains these values.

SFMC Contact sync configuration in the Hightouch UI

Contact Keys are different from Contact IDs and email addresses. Check out Salesforce's article to learn more.

Field mapping

You can use field mapping to map any other columns in your query results to the data extension containing your journey's data.

Journey configuration in the Hightouch UI

The data extension requires the email_address field—be sure to map a model column to that attribute. You can do this in Hightouch by typing "email_address" as a Field from Salesforce Marketing Cloud in the mappings section and then selecting the appropriate model column.

Journey configuration in the Hightouch UI

Syncing data extension objects

Hightouch supports syncing objects to existing data extensions and creating new ones. You can select either Upsert or Mirror mode.

  • In Upsert mode, you can choose whether to use the SOAP API or FTP. Hightouch inserts new objects into the data extension and keeps all mapped object attributes up-to-date.
  • In Mirror mode, you can't select between SOAP API or FTP. Hightouch always uses FTP, SOAP, and an Overwrite import automation in SFMC to overwrite the entire data extension with your model's query results.

Optional configurations

You can optionally choose which Business Unit and which Data Folder you would you like to sync data to. If you leave these configuration empty, Hightouch uses the defaults configured in SFMC.

Data extension configuration in the Hightouch UI

Automatic data extension creation

You can optionally choose whether Hightouch should automatically create a data extension. If you enable automatic creation, Hightouch creates a data extension the first time the sync runs. It doesn't create new data extensions on subsequent runs.

Data extension configuration in the Hightouch UI

When creating a new extension, you can optionally specify the data extension's name. If you leave the name blank, Hightouch uses the model name. The name also becomes the data extension's customer key.

You can include timestamp variables in the data extension name, surrounding each with {}. Hightouch supports these timestamp variables:

  • YYYY: Represents the full year in four digits.
  • YY: The last two digits of the year.
  • MM: Two-digit month format (01-12).
  • DD: Two-digit day format (01-31).
  • HH: Two-digit hour format in 24-hour clock (00-23).
  • mm: Two-digit minute format (00-59).
  • ss: Two-digit second format (00-59).
  • ms: Three-digit millisecond format.
  • X: Unix timestamp in seconds.
  • x: Unix timestamp in milliseconds.

All dates and times are UTC.

You can also use other variable values to include sync metadata in the data extension name:

  • {model.id}
  • {model.name}
  • {sync.id}
  • {sync.run.id}

To change the name or customer key, you need to create a new sync. Hightouch doesn't modify the data extension's name or customer key after the first run.

You can also optionally enter a file path when creating a data extension, such as path/to/dataExtension. If you choose a file path that includes folders, Hightouch will only create new folders if they do not already exist, relative to the selected folder in the Data Folder option.

Automatic file import via FTP

By default, Hightouch uses the SOAP API to sync data extension options in upsert mode. If you select to use FTP, Hightouch uploads records via file transfer to SFMC, which may lead to better sync performance. While FTP mode is generally faster, it provides less visibility into individual records' sync successes and failures.

To use FTP mode, ensure:

When using FTP mode, Hightouch creates and runs an import definition to load the data into the data extension. By default, Hightouch includes 100,000 rows in each file. You can configure this batch size in the Hightouch UI—the maximum value is 10 million rows per file. After each batch, Hightouch processes the SFMC results file to determine row errors.

SFMC provides more detailed error responses when using the SOAP API. If you need to debug errors and the error messages from FTP mode aren't helpful, we recommend trying the SOAP API.

If you enable deletion in upsert mode, Hightouch removes deleted rows in the data extension using the SOAP API, since SFMC doesn't support deletions using FTP directly. If you want to completely overwrite the data extension with the results of your sync, use Mirror mode.

Record matching

You can match objects from your source to your data extension on your data extension's primary key. Select the model column that contains these values.

Editing the data extension field used for record matching is only possible before triggering the first sync run. Otherwise, making this change results in an error. If you want to use a different field once the sync has already run, you need to create a new sync.

Field mapping

You can map any model column to any field in your data extension. Make sure that you map all non-nullable fields when syncing new objects to the data extension. A non-nullable field is a field that is required to be populated with a value. When creating or editing a record in SFMC, if a non-nullable field is left empty, the system won't allow the record to be saved and will return an error message.

You can check which fields are non-nullable fields in SFMC by inspecting your data extensions:

  1. Open the Email Studio in your SFMC account.

Inspecting Data Extensions in SFMC

  1. Select the data extension you want to check.

Inspecting Data Extensions in SFMC

  1. Inspect the Fields section in the data extension to see a list of all fields.

Inspecting Data Extensions in SFMC

  1. Look for the Nullable column in the list. This column includes a checkbox for each field.

  2. If a field doesn't have a check in the Nullable column, it means that the field is non-nullable and must have a value in it when a record is created or updated. Make sure you map all non-nullable fields.

In the example screenshot below, since email is the only field without a check in the Nullable column, it is the only non-nullable field.

In Upsert mode, you can sync records that don't include all non-nullable fields, but only if the object already exists in the data extension.

SFMC requires a minimum of one field mapping when sending data using SOAP-mode. This can be a placeholder field.

Field creation

When creating a new data extension with Hightouch, you can create new fields and select their types while field mapping. First enter a field name, then select its type.

Data extension configuration in the Hightouch UI

Text and Decimal field types allow for additional configuration.

Data extension configuration in the Hightouch UI

Hightouch adds new fields to the data extension on each run but doesn't remove fields that leave the model's query results.

Sendable and testable data extensions

For auto-created data extensions, you can select whether the data extension is sendable and testable.

A sendable data extension is a type of data extension that can be used to send email messages or other types of communications to subscribers. Sendable data extensions are designed to contain subscriber data that can be used in email marketing campaigns, triggered sends, or other types of communications.

A testable data extension is used to send test emails or other test communications to a small group of recipients, usually internal stakeholders or quality assurance testers. Testable data extensions are designed to mimic the structure of a sendable data extension, but with a smaller set of test data.

To be designated as sendable, a data extension must meet certain requirements, including:

  • It must contain an email address or mobile number field that is marked as the primary sendable field.
  • It must contain at least one additional field that is used as a personalization field in the email message.
  • It must be mapped to a profile attribute group, which is used to store additional subscriber data that is not included in the sendable data extension.

To make the data extension you are syncing via Hightouch sendable, select the field to use as the primary sendable field and the field to map to a subscriber field. The options available for the sendable field are the fields you mapped.

The length of the field chosen in send relationships is limited to 254 characters. Choose the Text - 254 characters field type when creating a sendable field in Hightouch to enforce this limit.

Data extension configuration in the Hightouch UI

You can only set a data extension to be testable once you select it to be sendable.

Delete behavior

You can choose how to handle data extension objects when the corresponding rows are deleted in your source.

BehaviorDescription
Do nothingKeep the object in SFMC
Delete the recordRemove the SFMC record completely

Concurrency

When syncing to SFMC in FTP mode, you can configure the concurrency used in the FTP upload to SFMC in Advanced options. Enter a value between 1 and 10. Higher concurrency values will increase upload speeds, but can cause disruptions when simultaneously running multiple Hightouch syncs to SFMC. For this reason, the default concurrency is 1.

File Retention

By default, Hightouch will delete the CSV files used to populate a Data Extension and the results file from the Import Definition automation from your SFMC FTP server. You can choose to keep files on your FTP server in Advanced options. Files on the FTP server will automatically be deleted by SFMC after 21 days.

Notifications

If you would like to receive an email notification when an Import Definition to your Data Extension succeeds, you can enter an email address in Advanced options. In Mirror mode, one email will be sent for each sync run. In Upsert mode, one email will be sent for each batch completion. Depending on your batch size, this could be multiple emails per sync run.

Tips and troubleshooting

Common errors

If you encounter an error or question not listed below and need assistance, don't hesitate to . We're here to help.

Failed to create data extension

When syncing data extension objects, an incomplete sync configuration can result in the Failed to create data extension error. To resolve it, make sure to enter the field names and select the field types when creating new fields.

Server was unable to read request. ---> There is an error in the XML document. ---> Instance validation error: 'DATA TYPE VALUE' is not a valid value for DataExtensionFieldType.

If you configure your sync to create a new data extension with the same name as a data extension that already exists, this error may occur. To resolve it, change the name of the data extension that you would like to create and select field types for each mapped column in the sync configuration.

The event data contains duplicate values for an existing primary key

The full error message looks something like this:

400 - {"message":"The event data contains duplicate value for an existing primary key. Please correct the event data and try again.","errorcode":30000,"documentation":""}

In this error message, the "primary key" refers to the primary/subscriber key of the related data extension. To avoid this error, ensure the column you selected doesn't contain duplicate values. You can read more about syncing data extension objects in the dedicated sync configuration section.

The Custom Object field selected must have a type of Number or Long Number

If you choose to make the data extension sendable and set the subscriber relationship using the Subscriber ID, the field that you map to the Subscriber ID must be a number per SFMC's documentation, otherwise map this field to the Subscriber Key.

Live debugger

Hightouch provides complete visibility into the API calls made during each of your sync runs. We recommend reading our article on debugging tips and tricks to learn more.

Sync alerts

Hightouch can alert you of sync issues via Slack, PagerDuty, SMS, or email. For details, please visit our article on alerting.

Ready to get started?

Jump right in or a book a demo. Your first destination is always free.

Book a demoSign upBook a demo

Need help?

Our team is relentlessly focused on your success. Don't hesitate to reach out!

Feature requests?

We'd love to hear your suggestions for integrations and other features.

Last updated: Aug 5, 2024

On this page

Supported syncingSalesforce Marketing Cloud setupCreate server-to-server packageCreate FTP userConnect to SFMCCustom scopesAllowed Business UnitsSync configurationSyncing contactsManaging user journeysSyncing data extension objectsTips and troubleshootingCommon errorsLive debuggerSync alerts

Was this page helpful?