Send data to Salesforce Marketing Cloud

Salesforce Marketing Cloud is a provider of digital marketing automation and analytics software and services.

This topic describes the steps that are required to send CSV files to Salesforce Marketing Cloud from Amperity:

  1. Get details

  2. Add destination

  3. Add data template

How this destination works

Amperity can send CSV files with contact data to business units in Salesforce Marketing Cloud. The CSV files are uploaded to Salesforce Marketing Cloud using SFTP, after which the Marketing Cloud SOAP API is used to manage data extensions and to move contacts data from the CSV files into the data extensions.

Send contact data from Amperity to Salesforce Marketing Cloud.

A Salesforce Marketing Cloud destination works like this:

Step one.

Optional. Configure a data extension in Salesforce Marketing Cloud.

What is a data extension?

A data extension is a table that stores data about your contacts. The fields that are available from your data extension match the columns and/or attributes that are sent from Amperity.

Within Salesforce Marketing Cloud, use the data in the data extension as a data source. Run queries, pull a subset of contacts from the data extension, and then send offers to that subset of contacts.

This step is optional because Amperity will manage the data extension as part of its workflow. If the data extension does not exist, Amperity will add it. If the data extension does exist, Amperity will update the contact data in that data extension.

Step two.

Configure permissions for the installed package to allow business units to read from and write to the data extension.

When does Amperity use an API?

Amperity uses the Marketing Cloud SOAP API to manage the installed package and manage the import definition process, which gets the contact data from the CSV files that were sent from Amperity and then either adds a data extension or updates an existing data extension.

Note

You may configure Amperity to send CSV files to Salesforce Marketing Cloud using only SFTP. This will place the CSV files in the configured SFTP location, but will require configuring the data extension and import definition and any process that moves that data from the SFTP location to the data extension.

Step three.

Use a query or segment to build a list of contacts.

The fields that are sent from Amperity must match the fields that are defined in the schema for the data extension in Salesforce Marketing Cloud.

Step four.

Configure the Salesforce Marketing Cloud destination in Amperity.

Why does Amperity use SFTP?

Amperity uses SFTP to transfer data to Salesforce Marketing Cloud.

Salesforce Marketing Cloud has strict rate limits when using their APIs to manage contact data. These rate limits generally exceed the number of contacts that are in the lists that you will want to send to Salesforce Marketing Cloud.

Amperity uses SFTP to ensure that your contact lists can be successfully updated in Salesforce Marketing Cloud, after which Amperity uses the Marketing Cloud SOAP API to make that list of contacts available to the configured data extension.

Step five.

Send a test from Amperity.

Important

Be sure to send all fields from Amperity that will be required by the data extension in Salesforce Marketing Cloud.

Step six.

From within Salesforce Marketing Cloud verify the data that has been loaded to the data extension is correct and that you can run a query against it.

Get details

Salesforce Marketing Cloud requires the following configuration details:

Detail one.

For the installed package: the API client ID, API client secret, and the SOAP base URI for the authentication subdomain .

What is the authentication subdomain for the SOAP base URI?

Your authentication subdomain is represented by a 28-character string that starts with the letters “mc”, such as “mcabc123…”. The subdomain is part of the SOAP base URI for Salesforce Marketing Cloud.

Detail two.

Within Salesforce Marketing Cloud, configure the installed package to allow business units:

  1. Apply Read and Write permissions to the data extension.

  2. Apply Read, Write, and Execute permissions for Automations.

Important

Each installed package is configured to have access to one business unit or multiple business units, depending on the desired workflow.

Configure a data template for each busines unit to which you want to send data. When a single installed package has permissions to multiple business units, you must configure a data template for each business unit.

Amperity cannot send data to a shared business unit in Salesforce Marketing Cloud.

Detail three.

For SFTP configuation: the hostname, username, and passphrase.

Note

The username is not the same as the email address that is associated with the user.

What is the SFTP hostname?

Your SFTP hostname is represented by the same 28-character string that starts with the letters “mc”, such as “mcabc123…”. This is the same 28-character string that represents the subdomain, which is part of the SOAP base URI for Salesforce Marketing Cloud.

Detail four.

For each business unit to which data will be sent: the account ID for the business unit, the import location, and selecting the field to use as the primary key.

Note

The account ID is also referred to as the member ID within Salesforce Marketing Cloud.

Important

Review the Marketing Cloud File Location Guide to configure a File Transfer Location with Location Type “Marketing Cloud Enhanced FTP Site Import Directory”.

Detail five.

The subscriber key for Salesforce Marketing Cloud. (The use of the subscriber key is recommended.)

Important

A subscriber key is configured as the “primary key” for the destination. There are two options: using the Salesforce Marketing Cloud subscriber key or using email. One of these options must be specified before the destination can send data to Salesforce Marketing Cloud.

Detail six.

Review the Marketing Cloud SFTP Guide to answer questions about configuring and managing Salesforce Marketing Cloud.

Tip

Configuration details for Salesforce Marketing Cloud are available from within Salesforce.

  1. For the installed package, click Setup > Platform tools > Aps > Installed packages.

  2. For SFTP, click Setup > Administration > Data management > FTP accounts.

Subscriber key

The subscriber key is an identifier in Salesforce Marketing Cloud. All data that is sent to Salesforce Marketing Cloud must be associated to a subscriber key. Use the primary key field while configuring Salesforce Marketing Cloud to specify the subscriber key to use for this destination.

The use of the subscriber key within Amperity will vary, depending on if the subscriber key is made available to Amperity as field provided by a Salesforce Marketing Cloud data source:

Detail one.

When a subscriber key is available, ensure that it is made available to the Customer 360, Queries, and Segments pages and that it may be included in queries and segments that will be sent to Salesforce Marketing Cloud.

Use a customer key semantic tag (e.g. “fk-salesforce-subscriber key”) to identify the subscriber key in your data sources.

Tip

Use an email address as the subscriber key if the subscriber key identifier is unavailable.

Detail three.

The primary key field must be set to subscriber_key or email as part of the configuration of the data template that is used for this destination.

Caution

A mismatch between the primary key in Amperity and the subscriber key in Salesforce Marketing Cloud will cause duplicate records to be created.

SFTP password expiration

The SFTP password for Salesforce Marketing Cloud may be set to periodically expire. The default for SFTP passwords is 3 months. The SFTP password is configured in Salesforce Marketing Cloud at Setup > Settings > Security > Security Settings > Password Policies > Exclude FTP Users From Password Expiration.

Add destination

Configure Amperity to send CSV files directly to Salesforce Marketing Cloud.

To add a destination

Step 1.

Open the Destinations tab to configure a destination for Salesforce Marketing Cloud. Click the Add Destination button to open the Destination dialog box.

Name, description, choose plugin.

Enter a name for the destination and provide a description. For example: “Salesforce Marketing Cloud” and “This sends CSV files to Salesforce Marketing Cloud”.

From the Plugin drop-down, start typing “sales” to filter the list, and then select Salesforce Marketing Cloud.

Step 2.

Credentials allow Amperity to connect to Salesforce Marketing Cloud.

The credential type is set automatically. You may use an existing credential or you may add a new one.

Choose an existing credential or add credential.

Select an existing credential from the Credential drop-down.

– or –

Select Create a new credential from the Credential drop-down. This opens the Credential dialog box.

Choose an existing credential or add credential.

Enter the name for the credential, and then add a description.

Salesforce Marketing Cloud has two groups of configuration settings: one for your Salesforce Marketing Cloud SFTP site and the other for the Marketing Cloud SOAP API.

Amperity sends data to your Salesforce Marketing Cloud SFTP site. Configure the following values for the SFTP site:

  • Hostname

  • Username

  • Passphrase

The Marketing Cloud SOAP API picks up data from your Salesforce Marketing Cloud SFTP site, and then loads that data to a data extension. Configure the following values for the Marketing Cloud SOAP API:

  • Client ID

  • Client secret

  • Authentication subdomain

When finished, click Save.

Step 3.

Each destination has settings that define how Amperity will deliver data to Salesforce Marketing Cloud. These settings are listed under the Settings section of the Destination dialog box.

Settings for Salesforce Marketing Cloud.

The following settings are specific to Salesforce Marketing Cloud:

Setting

Description

Account ID

The account ID for the business unit in Salesforce Marketing Cloud.

Import location

The directory within the Salesforce Marketing Cloud SFTP server into which data should be added. This is also the location from which the Marketing Cloud SOAP API will get the CSV files.

Folder name

The directory within the Salesforce Marketing Cloud SFTP site from which the Marketing Cloud SOAP API will get CSV files.

Primary key

Set to one of the following: subscriber_key or email.

Use subscriber_key when a field can be mapped directly to the subscriber key in Salesforce Marketing Cloud, or else choose email.

Important

Settings that are not configured as part of the destination will be required by the data template.

Step 4.

Business users are assigned to the Amp360 User and/or AmpIQ User policies. (Amp360 User allows access to queries and orchestrations and AmpIQ User allows access to segments and campaigns.) A business user cannot select a destination that is not visible to them.

Business users – including users assigned to the DataGrid Operator policy – may have restricted access to PII.

What is restricted access to PII?

Restricted PII access is enabled when the Restrict PII access policy option that prevents users who are assigned to that option from viewing data that is marked as PII anywhere in Amperity and from sending that data to any downstream workflow.

You can make this destination visible to orchestrations and allow users with restricted access to PII to use this destination by enabling one (or both) of the following options:

Allow business users access to this destination.

Note

To allow business users to use this destination with campaigns, you must enable the Available to campaigns option within the data template. This allows users to send campaign results from Amperity to Salesforce Marketing Cloud.

The other two settings may be configured within the data template instead of the destination.

Step 5.

Review all settings, and then click Save.

Save the destination.

Important

You must configure a data template for this destination before you can send data to Salesforce Marketing Cloud.

Add data template

A data template defines how columns in Amperity data structures are sent to downstream workflows. A data template is part of the configuration for sending query and segment results from Amperity to an external location.

To add a data template

Step 1.

From the Destinations tab, open the menu for a destination that is configured for Salesforce Marketing Cloud, and then select Add data template.

This opens the Add Data Template dialog box.

Name and description of data template.

Enter the name of the data template and a description. For example: “Salesforce Marketing Cloud” and “Send audiences to Salesforce Marketing Cloud.”.

Step 2.

Verify business user access to queries and orchestrations and access to segments and campaigns.

A business user may also have restricted access to PII, which prevents them from viewing and sending customer profile data.

Allow access to orchestrations and campaigns and to send customer profile data.

If business user access was not configured as part of the destination, you may configure access from the data template.

Important

To allow business users to use this destination with campaigns, you must enable the Available to campaigns option. This allows users to send campaign results from Amperity to Salesforce Marketing Cloud.

If you enable this option, the data extension settings require using campaign name and group name template variables to associate the name of the data extension to your campaign.

Step 3.

Verify all configuration settings.

Verify settings for the data template.

Note

When the account ID, import location, folder name, and primary key settings were are not configured as part of the destination, you must configure them as part of the data template before making this destination available to campaigns.

Step 4.

Configure how Amperity will send data to the data extension in Salesforce Marketing Cloud.

Amperity will overwrite the data in the data extension by default. Enable the Append Data option to append data instead of overwriting it.

Set the name of the data extension you want to create or update. This data extension will be in the business unit within Salesforce Marketing Cloud that is associated with the credentials you provided.

For campaigns

Configure data extension settings.

Use the {campaign_name} and {group_name} campaign template variables to assign campaign and treatment group names to your data extension.

Important

The name of a data extension must be unique within Salesforce Marketing Cloud.

For orchestrations

Configure data extension settings.

Assign a name to the data extension that will be added (or updated) by Amperity.

Important

The name of a data extension must be unique within Salesforce Marketing Cloud, should use underscores ( _ ) instead of spaces, and may not contain any of the following characters: ! @ # $ % ^ * ( ) = { } [ ] . < > / “ : ? | , &

Step 5.

Review all settings, and then click Save.

Save the data template.

After you have saved the data template, and depending on how you configured it, business users can send query results and/or send campaigns to Salesforce Marketing Cloud.

Workflow actions

A workflow will occasionally show an error that describes what prevented a workflow from completing successfully. These first appear as alerts in the notifications pane. The alert describes the error, and then links to the Workflows tab.

Open the Workflows page to review a list of workflow actions, choose an action to resolve the workflow error, and then follow the steps that are shown.

Step one.

You may receive a notifications error for a configured Salesforce Marketing Cloud destination. This appears as an alert in the notifications pane on the Destinations tab.

Review a notifications error.

If you receive a notification error, review the details, and then click the View Workflow link to open this notification error in the Workflows page.

Step two.

On the Workflows page, review the individual steps to determine which step(s) have errors that require your attention, and then click Show Resolutions to review the list of workflow actions that were generated for this error.

The workflow tab, showing a workflow with errors.
Step three.

A list of individual workflow actions are shown. Review the list to identify which action you should take.

Choose a workflow action from the list of actions.

Some workflow actions are common across workflows and will often be available, such as retrying a specific task within a workflow or restarting a workflow. These types of actions can often resolve an error.

In certain cases, actions are specific and are shown when certain conditions exist in your tenant. These types of actions typically must be resolved and may require steps that must be done upstream or downstream from your Amperity workflow.

Amperity provides a series of workflow actions that can help resolve specific issues that may arise with Salesforce Marketing Cloud, including:

Step four.

Select a workflow action from the list of actions, and then review the steps for resolving that error.

Choose a workflow action from the list of actions.

After you have completed the steps in the workflow action, click Continue to rerun the workflow.

Import location has wrong type

The import location within the Salesforce Marketing Cloud SFTP site must be set to “Enhanced FTP Site Import Directory”, which is the standard location type for file imports within Salesforce Marketing Cloud. If this location is not set to the standard location type for file imports, Amperity will be unable to send data.

To resolve this error, you must verify that the import directory within Salesforce Marketing Cloud is set to “Enhanced FTP Site Import Directory”.

  1. Open the Salesforce Marketing Cloud management console , find the file location , and then verify that it is configured for the “Enhanced FTP Site Import Directory” location type.

  2. Return to the workflow action, and then click Resolve to retry this workflow.

Import location not found

The name of the directory into which Amperity will add data must be discoverable to Amperity. If Amperity cannot find that directory, CSV files will not be uploaded to the Salesforce Marketing Cloud SFTP site.

To resolve this error, you must ensure that the import location within the Salesforce Marketing Cloud SFTP site matches the import location that is configured in Amperity.

  1. Verify import location within Salesforce Marketing Cloud.

  2. Verify import location as it is configured for the destination within Amperity. Make any necessary changes.

  3. Return to the workflow action, and then click Resolve to retry this workflow.

Incorrect data extension name

The name of a data extension must be unique within Salesforce Marketing Cloud, should use underscores ( _ ) instead of spaces, and may not contain any of the following characters:

! @ # $ % ^ * ( ) = { } [ ] \ . < > / " : ? | , &

The name of a data extension in Salesforce Marketing Cloud must be globally unique across folders in Salesforce Marketing Cloud and also must match the primary key of that data extension, as it is configured in Amperity.

Important

You cannot change the primary key that is associated with a data extension from within Salesforce Marketing Cloud.

To resolve this error, you must delete or rename the data extension in Salesforce Marketing Cloud, and then re-apply the primary key by resending the workflow from Amperity.

  1. Open the Salesforce Marketing Cloud management console , and then delete or rename the data extension .

  2. Open the data template that is associated with this workflow.

  3. Edit the data extension name in the data template so that its name is globally unique within Salesforce Marketing Cloud, and then save the data template.

    Tip

    The name of the data extension may require updating in Salesforce Marketing Cloud.

    To update the data extension in Salesforce Marketing Cloud

    1. Open the Salesforce Marketing Cloud management console .

    2. Select Audience Builder, and then choose Contact Builder.

    3. Open Data Extensions.

    4. Search for the data extension for which this error is associated, and then rename the data extension or delete the data extension.

  4. Return to the workflow action, and then click Resolve to retry this workflow.

Incorrect folder

The name of the directory within the Salesforce Marketing Cloud SFTP site must match the folder name that is configured in Amperity. When the folder name does not match, the Marketing Cloud SOAP API will unable to get CSV files from that directory and the data extension will not be updated.

To resolve this error, you must ensure that the name of the folder name within the Salesforce Marketing Cloud SFTP site matches the folder name that is configured in Amperity.

  1. Verify the folder name within Salesforce Marketing Cloud.

  2. Verify the folder name as it is configured for the destination within Amperity. Make any necessary changes.

  3. Return to the workflow action, and then click Resolve to retry this workflow.

Invalid credentials

The credentials that are defined in Amperity are invalid.

To resolve this error, verify that the credentials required by this workflow are valid.

  1. Open the Credentials page.

  2. Review the details for the credentials used with this workflow. Update the credentials for Salesforce Marketing Cloud if required.

  3. Return to the workflow action, and then click Resolve to retry this workflow.

Note

In some situations the user account that is associated with the Amperity workflow will require a new password and security token. When a new password and security token are created in Salesforce Marketing Cloud, be sure to update the credentials for this workflow in Amperity.

Missing primary key

The primary_key field is typically used to specify the subscriber key that is used with this destination.

There are two options: using the Salesforce Marketing Cloud subscriber key or using email addresses. One of these options must be specified before Amperity can send data to Salesforce Marketing Cloud.

To resolve this error, you must configure the primary key.

  1. Open the Amperity Credentials page in a new tab.

  2. For a query, open the Queries page, and then update the query to return the field – subscriber_key or email – that matches the Primary Key setting in the data template. Validate, and then activate the query.

    For a campaign, open the Campaigns page, and then update the campaign and ensure the primary key is in the list of attributes that are sent to Salesforce Marketing Cloud. Activate the campaign.

  3. Return to the workflow action, and then click Resolve to retry this workflow.

SFTP unavailable

Amperity must be able to connect to the SFTP site that is used with Salesforce Marketing Cloud.

Note

An SFTP site may be unavailable even when Amperity is configured correctly. For example, the SFTP site is down or there is not enough free space available within the SFTP site. Amperity cannot send data to an SFTP site that is unavailable.

To resolve this error, you must verify the configuration settings for SFTP.

  1. Open the Amperity Credentials page in a new tab.

  2. Find the credentials for the SFTP site that is associated with Salesforce Marketing Cloud, and then verify the configuration for the hostname, username, and passphrase. Make any necessary changes.

    Note

    If the SFTP site is unavailable due to external reasons, such as not enough free space or the SFTP site is down, you must resolve those issues before Amperity will be able to send data to that SFTP site.

  3. Return to the workflow action, and then click Resolve to retry this workflow.