# Salesforce Marketing Cloud V2 Export Integration

Treasure Data can publish user segments into [Salesforce Marketing Cloud](https://www.salesforce.com/products/marketing-cloud/overview/) (ExactTarget), and enable you to send personalized emails to your customers. You can run data-driven email campaigns by using your first-party data from Web, Mobile, CRM, and other data sources.

For sample workflows of this, view [Treasure Boxes](https://github.com/treasure-data/treasure-boxes/tree/master/td/salesforce_marketing_cloud_exacttarget).

Treasure Data provides two methods to write job results to Salesforce Marketing Cloud (SFMC), our SFTP and SFMC plugins.

This SFMC plugin can be used for small and medium data sets. We recommend you use SFTP for large data sets.

## Synchronous or Asynchronous API

This integration supports two kinds of APIs to put records into SFMC: Synchronous APIs and Asynchronous APIs.

As a best practice, if you are trying to put a result set with less than 100,000 records into SFMC, Synchronous APIs is a great fit. However, if you are planning to send a million+ data set, then consider using Asynchronous APIs because it provides higher availability and reliability in comparison with Synchronous APIs.

In order to use the Asynchronous APIs, ensure that your SFMC account is enabled as a Data Extensions Async REST API from Salesforce Marketing Cloud. You can also create a [support case in Salesforce Marketing Cloud](https://help.salesforce.com/articleView?id=workcom_contact_support.htm&type=5) to have them enable it.

## Replace or Upsert Existing Audience Data in a Data Extension

This integration also supports Upsert and Replace.

### Upsert Audience Data

**Upsert** updates existing dataand inserts any new additional data in the data extension. Both the update and insert operation use the data extension primary key to determine if a record existed or not to perform the update or insert. All the existing data in the target data extension remains.

### Replace Audience Data

**Replace** which means before updating data, we will clear all existing data in the target data extension. This mode useful if you need only the newest data in the data extension each time in order to send email for targeted customers every time.

When replace is selected for this integration:

- If there is a data error (NULL value, wrong data type, invalid primary key) in the exported results, all the records in the Data Extension are cleared and not recoverable, but the invalid data is not exported.
- If there is a schema error (missing primary_key) in the exported results, the existing records in the data extension are not cleared.


When you use replace, the deleted data is unrecoverable. The connector clears all the data before pushing new data. Therefore, whether your job succeeds or fails, the data is cleared.  As a best practice, use replace with data that is temporary and when data history is not important.

To use replace, your account must be an Enterprise 2.0 account and the installed package must have admin privileges. Contact your Customer Success representative to find out more.

## Prerequisites

- Basic knowledge of Treasure Data
- Basic knowledge of Salesforce Marketing Cloud
- TD account


This connector also requires that the Data Extension have a primary key that uniquely identifies each record. In addition, the Data Extension needs to have 2 fields or more if you use Synchronous API. If you specify 'Create Data Extension' in order to create a new Data Extension, only 1 column as primary key is supported. Specify the multiple columns will cause an error.

## Create an Installed App in Salesforce Marketing Cloud

Treasure Data supports both **Legacy** and **Enhanced Package** in Salesforce Marketing Cloud.

We highly recommend you create an Enhanced Package.

### Create Enhanced Functionality Package

1. Log on to your Salesforce Marketing Cloud account.
2. On the Welcome Page, select your name on top right corner. Select **Setup**.


![](/assets/image-20191203-230537.e0bcdfcb7e2561762c7696348017cbdacc5ba65f7f802d2418ee8b77d769242c.3816ae6c.png)
3. On the left side menu of new screen, navigate to **App** > **Installed Packages.**

![](/assets/image-20191203-230529.3bd5b94dddc4591cf914ae0be5d747aebc089a800d9012bc4f065f79b0894c19.3816ae6c.png)
4. On the Installed Packages screen. Select **New**.

![](/assets/image-20191203-230520.b3ce22d3ac6c14b71d3179db2c83b6ad2bc76ea6cde6cc92354f9319c93303bf.3816ae6c.png)
5. Type the **Name** and **Description.**
6. Select **Save.**

![](/assets/image-20191203-230511.fddfd1f6154dbd1b6c8f68a9931c82a18b1f6fe4ef53361e70cea3047d394444.3816ae6c.png)
7. Select Add Component.
![](/assets/screen-shot-2022-05-27-16.27.17.5a0de3a6391853630496b0d42cec3bf348a24ea62175a17c782c91fbf2ca92de.3816ae6c.png)
8. Select **API Integration.**
9. Select **Next.**

![](/assets/image-20191203-230502.05e97edb5fa71052662c94ce53a805e48bd67c8fba685461aceaf8391d51cb1a.3816ae6c.png)
10. Select **Server-to-Server**.
11. Select **Next**.

![](/assets/image-20191203-230452.0549f71d5447c3b0504df60cb7a574569956b725c55e2721b191571026934996.3816ae6c.png)

1. Locate Contacts > Audiences and to Contacts > List and Subscribers.
2. Select **Read** and **Write** under both to use Replace Audience feature.
3. Locate Data > Data Extensions.
4. Select **Read** and **Write**.
You need these permissions to write data to Salesforce Marketing Cloud.
5. Select **Save**.


![](/assets/screen-shot-2020-10-12-at-2.14.38-pm.ad0de0f5fc63fb8be9fe49f09040292c266999232b96ec7178da216cba3d6e53.3816ae6c.png)

1. Locate the Components panel.
2. Make note of the **Client Id**, **Client Secret** and **Authentication Base URI**.
You use the information to write the data from Treasure Data to Salesforce Marketing Cloud.


![](/assets/image-20191203-230426.f3112d86f090248d0a16b48d4348f0b17af66704232fb6144437b0d50b20fdb5.3816ae6c.png)

## Using TD Console

Complete the following steps to export TD query results to a Salesforce Marketing Cloud Data Extension:

### Create a New Data Connection

When you configure a data connection, you provide authentication to access the integration. In Treasure Data, you configure the authentication and then specify the source information.

1. Open TD Console.
2. Navigate to **Integrations Hub** > **Catalog.**
3. Search for and select **Salesforce Marketing Cloud Version 2**.


![](/assets/screen-shot-2022-05-27-16.37.54.e0fe3afa61c9868ee653ee5f3d1eec68d1d5a070f65e969290ace5795a33d42a.3816ae6c.png)
4. Select Enhanced Package Integration.

![](/assets/image-20201106-212315.3d4c4002e0f5b268fde845df49e0e80b070a572437ab589713bf7de1efd42e36.3816ae6c.png)

1. Select **Enhanced Functionality Package,** then enter the **Client Id**, **Client Secret** and **Authentication Base URI** (which you obtained when you created the enhanced package in SFMC). Optionally, you could specify:


- **Account identifier or MID** to access multiple BUs.
- **Scope** to limit the token's scope (more detail in [API scopes](https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/rest-permissions-and-scopes.htm)).


1. Select **Continue.**


![](/assets/image-20191203-230335.b828546b61ec5347e9550a24f61988f734754170ed0a8c717dffdac7cb10ad08.3816ae6c.png)

### Name the Connection

1. Type a name for your connection.
2. Select **Done**.


### Configure Export Results

In this step, you create or reuse a query. In the query, you configure the data connection.

Sometimes you need to define the column mapping in the query.

1. Open TD Console.
2. Navigate to **Data Workbench** > **Queries** > **New Query.**


![](/assets/image-20191203-230303.3c9be3f4b5261f47f8b8c475e4dee14e88168a433534524a562b9844ffd74f5c.3816ae6c.png)

1. Type your query in the query editor. For example:



```sql
SELECT
 name as customer_name,
 email as primary_key
FROM
 data_extension
limit 10
```

The primary key can be a text field.

1. Select **Export Results** located at top of your query editor.


![](/assets/image-20191203-230256.b3ecea9c19a2d4da4820f97082e0948c1c029522059012a707eb669f9d61f338.3816ae6c.png)

1. Select an existing connection.
2. Specify a **Data Extension Name**. Optionally, if your Data Extension does not exist, select Create Data Extension to create a brand new data extension.


![](/assets/image2023-6-14_19-57-36.0d6bd7d3b408493b79a8f4468a04811777248fbbc13fcb44ebc60cf5bce31673.3816ae6c.png)

1. Specify a **Folder Path.** Optionally, if any Folder in **Folder Path** does not exist, select **Create New Folder if not Exists**to create folder.


![](/assets/image2023-6-14_20-9-56.fc96db7249b3cf13ac911c2ce953470790922f1e0af13a02191631482fcaac9b.3816ae6c.png)

1. If using an existing Data Extension Name and you want to use Asynchronous API**,** select **Using Async API**. To use the Synchronous API,leave the box unchecked.
2. If creating a new data extension, select **Create Data Extension**. With the newly created data extension, input your Data Extension Nameand name the Primary Column in your new data extension.


![](/assets/image2023-6-14_20-11-38.b30279552900b2ec6897e605db9e618510e96aaf0c62dda085ee49e6ded37944.3816ae6c.png)

1. **Long** & **Text** are two supported data types for **Primary** **Column**. If **Text** is **Primary Column**, you can specify **Text length for Primary Key** to optimize data extension performance by not unnecessarily allocating unused space.
2. Select the **Is Sendable** option, if your data extension is sendable.
3. Set your **Sendable Rule** by **Subscriber Key** or **Email Address**.
4. Select your **Sendable Column** as a sendable property in your data extension.


![](/assets/image2023-6-14_20-14-29.4dc0a84892acb9cf2428cfd3a90f45363f6105deaed3a5a52a2eeda38496d449.3816ae6c.png)

1. Select **Data Operation** for your data extension


- **Upsert** to add when there are new records or update when records are duplicated.
- **Replace** to delete records and completely replace them for each new export.
Replaced data **will not be recoverable**.


![](/assets/image-20201020-225208.d972f688937823fbf90b1820df508fa72706de321f6ecec604383779d48513ed.3816ae6c.png)
15. Select **Done.**

### Run the Query

1. Select **Run** to run the query.
2. Check the query results are written to the configured data extension.


![](/assets/image-20191203-230222.284b5bd59b85b34532412c3aee9c28c9e81788d270d8c33c4132e0a9227bd79f.3816ae6c.png)

As there is no time zone setting for the Salesforce Marketing Cloud V2 Export integration, the integration uses the time zone setting of your SFMC account.

## Activate a Segment in Audience Studio

You can also send segment data to the target platform by creating an activation in the Audience Studio.

1. Navigate to **Audience Studio**.
2. Select a parent segment.
3. Open the target segment, right-mouse click, and then select **Create Activation.**
4. In the **Details** panel, enter an Activation name and configure the activation according to the previous section on Configuration Parameters.
5. Customize the activation output in the **Output Mapping** panel.


![](/assets/ouput.b2c7f1d909c4f98ed10f5300df858a4b19f71a3b0834df952f5fb24018a5ea78.8ebdf569.png)

- Attribute Columns
  - Select **Export All Columns** to export all columns without making any changes.
  - Select **+ Add Columns** to add specific columns for the export. The Output Column Name pre-populates with the same Source column name. You can update the Output Column Name. Continue to select **+ Add Columns**to add new columns for your activation output.
- String Builder
  - **+ Add string** to create strings for export. Select from the following values:
    - String: Choose any value; use text to create a custom value.
    - Timestamp: The date and time of the export.
    - Segment Id: The segment ID number.
    - Segment Name: The segment name.
    - Audience Id: The parent segment number.


1. Set a **Schedule**.


![](/assets/snippet-output-connector-on-audience-studio-2024-08-28.a99525173709da1eb537f839019fa7876ffae95045154c8f2941b030022f792c.8ebdf569.png)

- Select the values to define your schedule and optionally include email notifications.


1. Select **Create**.


If you need to create an activation for a batch journey, review [Creating a Batch Journey Activation](/products/customer-data-platform/journey-orchestration/batch/creating-a-batch-journey-activation).

## Plugin Configuration and Options

### Available Configurations

| Configuration name | Description | Type | Sample value |
|  --- | --- | --- | --- |
| `client_id` | Installed package client key | string | `Th1s1s4n3x4mpl3Cl13nt1ds` |
| `client_secret` | Installed package client secret | string | `Th1s1s4F4k3dCl13ntS3cr3t` |
| `auth_type` | Authenticate type | string | `v1` (for legacy package)  `v2` (for enhanced package) |
| `auth_uri` | Authenticate URI (required if auth_type=v2) | string | `https://th1s1sf4k3d1nst4nc3h0st.auth.marketingcloudapis.com/` |
| folder_path | Folder Path to export Data Extension  Folder Path must satisfy these requirements:- Start with a slash - Have maximum 8 level of folder - Have NO multiple consecutive slashes - Folder name in Folder Path could not exceed 128 characters in length | string | `/Data Extensions/FolderPath2/FolderPath3/FolderPath3` |
| create_folder_if_not_exists | Flag to indicate created new folder in folder_path or not  Only effect if folder_path is provided (and not empty) | boolean  default is false | `true` (Any and all directories specified in path are created, unless they already exist or unless some part of path is invalid)  `false` (do not create new Folder if doesn’t exist) |
| `de_name` | Data Extension name | string | `data_extension_name` |
| `create_new_de` | Flag to indicate create new data extension if it is not existed | boolean  default is false | `true` (create new DE if it doesn’t exist)  `false` (do not create new DE if doesn’t exist) |
| primary_column | Name of primary column (required of create_new_de=true)  Only 1 column can be specified. | string |  |
| primary_text_length | `Length of text field when it is selected as primary column` | integer | `max: 4000, min: 10 (default: 4000)` |
| `is_sendable` | Flag to indicate created DE is sendable or not | boolean  default is false | `true`  `false` |
| `sendable_rule` | Your account’s configured sendable business rule (required if is_sendable=true) | string | `Subscriber Key` (if the business rule is Subscriber Key)  `Email Address` (if the business rule is Email Address) |
| `sendable_column` | Column name to use as sendable property (required if is_sendable=true | string | `my_sendable_column` |
| data_operation | Determine whether clear data in DE before inserting | string  default is upsert | `upsert`, `replace` |
| `async` | Flag to indicate using asynchronous or synchronous API from SFMC | boolean  default is false | `true` (using Async API)  `false` (using Synchronous API) |
| `continue_on_failure` | Flag to indicate continue running if there is an insertion error (applied only for synchronous API) (Jobs will only continue when they encounter SFMC server side errors, if an error occurs on the Treasure Data side e.g. wrong credentials, record invalid format ...).  the job will fail with error |  |  |
| records_per_batch | Number of records that will be sent in one API call. (This option is only applied to asynchronous APIs.) | integer | max: 32000 (default), min: 100 |


### Example Configurations

Example configuration for using **Synchronous API**s to upsert data extension using **Enhanced package.**


```yaml
out:
 type: salesforce_marketing_cloud_v2
 client_id: Th1s1s4n3x4mpl3Cl13nt1ds
 client_secret: Th1s1s4F4k3dCl13ntS3cr3t
 auth_type: v2
 auth_uri: https://th1s1sf4k3d1nst4nc3h0st.auth.marketingcloudapis.com/
 de_name: data_extension_name
 continue_on_failure: false
```

Example configuration for **Asynchronous APIs** to upsert data extension using **Enhanced package.**


```yaml
out:
 type: salesforce_marketing_cloud_v2
 client_id: Th1s1s4n3x4mpl3Cl13nt1ds
 client_secret: Th1s1s4F4k3dCl13ntS3cr3t
 auth_type: v2
 auth_uri: https://th1s1sf4k3d1nst4nc3h0st.auth.marketingcloudapis.com/
 de_name: data_extension_name
 async: true
```

Example configuration for **Asynchronous APIs** to upsert data extension using **Enhanced package** and create new **Sendable data Extension** if not existed.


```yaml
out:
 type: salesforce_marketing_cloud_v2
 client_id: Th1s1s4n3x4mpl3Cl13nt1ds
 client_secret: Th1s1s4F4k3dCl13ntS3cr3t
 auth_type: v2
 auth_uri: https://th1s1sf4k3d1nst4nc3h0st.auth.marketingcloudapis.com/
 de_name: data_extension_name
 create_new_de: true
 primary_column: primary_key
 primary_text_length: 32
 is_sendable: true
 sendable_column: mytext
 sendable_rule: Subscriber Key
 async: true
 records_per_batch: 32000
```

Example configuration for **Export data extension to a specific folder**


```yml
out:
 type: salesforce_marketing_cloud_v2
 client_id: xxxxxxxxxxxxxxxxxxxxxxxxx
 client_secret: xxxxxxxxxxxxxxxxxxxxxxxxx  
 auth_type: v2
 auth_uri: https://th1s1sf4k3d1nst4nc3h0st.auth.marketingcloudapis.com/
 folder_path: /Data Extensions/FolderPath2/FolderPath3/FolderPath3
 create_folder_if_not_exists: true
 de_name: data_extension_name
 create_new_de: true
 primary_column: primary_key
 primary_text_length: 32
 is_sendable: true
 sendable_column: mytext
 sendable_rule: Subscriber Key
 async: true
 records_per_batch: 32000
```

## Appendix

- The connector communicates with the SFMC v2 server/instance endpoint via HTTPS.
- The HTTPS and SSL/TLS encryption are enforced by SFMC v2 servers and are checked by our connector before processing.