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:
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.
A Salesforce Marketing Cloud destination works like this:
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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:
|
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. |
|
|
Within Salesforce Marketing Cloud, configure the installed package to allow business units:
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. |
|
|
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. |
|
|
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”. |
|
|
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. |
|
|
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.
|
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:
|
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. |
|
|
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
|
|
Open the Destinations tab to configure a destination for Salesforce Marketing Cloud. Click the Add Destination button to open the Destination dialog box. 
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. |
||||||||||
|
|
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. 
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. 
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:
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:
When finished, click Save. |
||||||||||
|
|
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. 
The following settings are specific to Salesforce Marketing Cloud:
Important Settings that are not configured as part of the destination will be required by the data template. |
||||||||||
|
|
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: 
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. |
||||||||||
|
|
Review all settings, and then click Save. 
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
|
|
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. 
Enter the name of the data template and a description. For example: “Salesforce Marketing Cloud” and “Send audiences to Salesforce Marketing Cloud.”. |
|
|
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. 
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. |
|
|
Verify all configuration settings. 
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. |
|
|
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 
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 
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: ! @ # $ % ^ * ( ) = { } [ ] . < > / “ : ? | , & |
|
|
Review all settings, and then click Save.
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.
|
|
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. 
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. |
|
|
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. 
|
|
|
A list of individual workflow actions are shown. Review the list to identify which action you should take. 
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: |
|
|
Select a workflow action from the list of actions, and then review the steps for resolving that error. 
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”.
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.
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.
Verify import location within Salesforce Marketing Cloud.
Verify import location as it is configured for the destination within Amperity. Make any necessary changes.
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.
Open the Salesforce Marketing Cloud management console, and then delete or rename the data extension.
Open the data template that is associated with this workflow.
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
Select Audience Builder, and then choose Contact Builder.
Open Data Extensions.
Search for the data extension for which this error is associated, and then rename the data extension or delete the data extension.
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.
Verify the folder name within Salesforce Marketing Cloud.
Verify the folder name as it is configured for the destination within Amperity. Make any necessary changes.
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.
Open the Credentials page.
Review the details for the credentials used with this workflow. Update the credentials for Salesforce Marketing Cloud if required.
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.
Open the Amperity Credentials page in a new tab.
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.
Return to the workflow action, and then click Resolve to retry this workflow.