Salesforce Marketing Cloud

Supercharge what your teams can do in Salesforce Marketing Cloud with rich customer data from your data warehouse

Supported syncing

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.

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

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

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

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

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

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.

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/

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 login 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. Provide the user Full user permissions.

6. Allowlisting IP addresses is optional. For additional security, you can enter Hightouch's IP addresses. Click Next.
7. 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.

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

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.

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.

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

User identifers

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.

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.

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.

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

• 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

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.

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.

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.

Delete behavior

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

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