Salesforce Marketing Cloud

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

Overview

Salesforce Marketing Cloud (SFMC) is a digital marketing platform that enables businesses to create personalized customer journeys across email, mobile, social, web, and more. This integration allows you to sync your data from Hightouch to SFMC to power personalized marketing campaigns, manage contact data, automate customer journeys, and trigger communications.

With the Hightouch SFMC integration, you can:

• Sync data to SFMC Data Extensions for segmentation and personalization
• Update contact information for better targeting
• Manage entry and exit from customer journeys based on your data
• Trigger email and SMS messages based on customer behaviors

This documentation will guide you through setting up the connection, configuring syncs, and troubleshooting common issues.

Supported syncing

Salesforce Marketing Cloud setup

Before you connect Hightouch to Salesforce Marketing Cloud (SFMC), you need to create an installed package in SFMC for Hightouch to use.

If you want to sync records to Data Extensions using either mirror mode or upsert mode with file uploads, you also need to create an FTP user.

Create installed package in SFMC

1. Log in to your SFMC instance. Go to Setup.

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

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

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

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

Permissions

These are the minimum scopes for syncing to Contacts, Journeys, and Data Extensions.

• 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

If you want to sync to Data Extensions using mirror mode or upsert mode with file uploads, grant these additional permissions:

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

If you want to trigger sends, grant these additional permissions:

• Channels > Email: Read
• Channels > SMS: Read

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.

With the API Integration created, copy the Client ID, Client Secret, and subdomain to enter into Hightouch.

Create FTP user

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

2. 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.

3. Enter an Email Address for the new FTP user. This can be the email account you use to log in to SFMC or another one. You won't need this address to connect to Hightouch.

4. 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.

5. The next screen prompts you to choose your authentication method.

   • If you want to use a password, keep this selection.

     

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

     

6. On the next screen, select permissions for your FTP user. At a minimum, provide the user Upload access to the Import directory.

7. Allowlisting IP addresses is optional. For additional security, you can enter Hightouch's IP addresses. Click Next.
8. Select a Home Folder. We recommend setting the home folder to the root directory. If you choose to specify a restricted scope, ensure that this FTP user has access to the Import directory.

9. Make sure to 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.

Authentication

You can authenticate Hightouch to SFMC by entering the Client ID, Client Secret, and Subdomain you copied during package creation.

FTP credentials

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 supports the following file location types:

• ExactTarget Enhanced FTP Import Directory (default)
• Relative Location under FTP Site
• Google Cloud Storage
• Amazon S3

ExactTarget Enhanced FTP Import Directory

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

Relative Location under FTP Site

For Relative Location under FTP Site, enter the Relative Folder Path and the External Key to ensure Hightouch is able to access the uploaded files.

Google Cloud Storage

To use the Google Cloud Storage file location in SFMC you will need:

• Google Cloud Storage bucket
• Google Service Account with read access to your bucket. This will be used by SFMC to read from your bucket.
• Google Service Account with write access to your bucket. This will be used by Hightouch to upload files.

If you do not have a Google Service Account, you can follow the setup instructions in our Google Cloud Platform (GCP) documentation.

To set up a Google Cloud Storage file location in SFMC:

1. Go to Setup > Data Management > File Locations and create a new file location.
2. Configure your file location's name and external key.
3. Choose Google Cloud Storage for Location Type.
4. Enter your GCS bucket name.
5. If you would like for files to be uploaded to a specific path in your bucket, enter the path as the Relative Location in your file location.
6. Upload your Google Service Account credentials. Ensure that at a minimum this role has read access to your bucket.

In Hightouch, select the Cloud Credentials you'd like to use to write to your bucket. Ensure this account has write access to your bucket. Enter your file location External Key, GCP project ID, bucket name, and relative path.

Test your connection to ensure you've successfully connected to SFMC's API, FTP, and your GCS bucket.

Amazon S3

To use the Amazon S3 file location in SFMC you will need:

• Amazon S3 bucket
• AWS Credentials with read access to your bucket. This will be used by SFMC to read from your bucket.
• AWS Credentials with write access to your bucket. This will be used by Hightouch to upload files.

If you do not have AWS Credentials, you can follow the setup instructions in our AWS documentation.

To set up an AWS S3 file location in SFMC:

1. Go to Setup > Data Management > File Locations and create a new file location.
2. Configure your file location's name and external key.
3. Choose Amazon Simple Storage Service for Location Type.
4. Choose whether you'd like to authenticate with an Access Key or Access Key with IAM role and enter your AWS credentials. Ensure that at a minimum this account has read access to your bucket.
5. Enter your S3 bucket name.
6. If you would like for files to be uploaded to a specific path in your bucket, enter the path as the AWS Relative Location in your file location.

In Hightouch, select the Cloud Credentials you'd like to use to write to your bucket. Ensure this account has write access to your bucket. Enter your file location External Key, AWS region, bucket name, and relative path.

Test your connection to ensure you've successfully connected to SFMC's API, FTP, and your S3 bucket.

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

See the SFMC docs for a full list of scopes.

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 clicking 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.

The following sections outline the different types of syncs you can configure with SFMC:

Syncing Data Extensions

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 file uploads. 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 file uploads. Hightouch always uses file uploads, 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.

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. If you add columns to the sync config, Hightouch automatically adds them to the Data Extension.

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.

Automatic file import via file uploads

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

Generally, blob storage file locations (such as Google Cloud Storage and Amazon S3) are more performant file servers than SFMC's default option of ExactTarget Enhanced FTP server.

To use File Upload mode, ensure:

• your SFMC package has the appropriate scopes
• you've created an FTP user in SFMC
• you've authenticated the FTP user in your destination configuration

Additionally, if you are using a blob storage file location, ensure:

• your SFMC file location has read access to your bucket
• the credentials you've provided Hightouch has write access to your bucket.

When using File Upload 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.

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.

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.

2. Select the Data Extension you want to check.

3. Inspect the Fields section in the Data Extension to see a list of all fields.

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

5. 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.

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.

Text and Decimal field types allow for additional configuration.

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.

You can only set a Data Extension to be testable once you select it to be sendable.

Data Retention Policy

You can set a data retention policy on your Data Extension through Hightouch. Hightouch will not edit existing data policies unless explicitly enabled.

You can choose what data should be deleted in your policy:

You can choose the data retention period in days depending on how long you'd like to store your Data Extension and records. If you choose to reset the retention policy upon each successful sync run, the data retention period will restart whenever data is successfully imported into your Data Extension.

Delete behavior

You can choose how to handle Data Extension when the corresponding rows are deleted in your source.

Concurrency

When syncing to SFMC in File Upload 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.

Concurrency options are not available for blob storage file locations.

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 SFMC FTP server in Advanced options. Files on the SFMC FTP server will automatically be deleted by SFMC after 21 days.

Files are not automatically deleted from your blob storage file locations. We recommend setting a retention policy on your bucket to avoid storing stale CSV files.

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.

Triggering automations

In Mirror mode, if you would like to trigger an automation after the completion of your Data Extension sync run, you can select Yes or No and enter either an External key or an Automation ID. If Yes, an automation will run even if there are failed rows in the sync. If the automation itself fails, the entire sync run is marked as failed.

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.

Field mapping

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

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:

Note that it's:

• A multistep 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.

User identifiers

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

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.

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.

Triggered Sends

Hightouch can trigger emails to individual subscribers via the Marketing Cloud API. This is useful for sending personalized messages to specific users based on their behavior or attributes.

Select an existing Triggered Send definition, then map the model columns to the Triggered Send's attributes, including email addresses and custom attributes. Hightouch matches rows from your model to Marketing Cloud contacts by Subscriber Key.

Tips and troubleshooting

Common errors

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

Failed to create Data Extension

When syncing Data Extensions, 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 Extensions 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.