Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Add limitation to Prerequisites.

...

Table of Contents
maxLevel2


Synchronous or Asynchronous API

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

...

In order to use the Asynchronous APIs, you must 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 to have them enable it.

Replace or Upsert Existing Audience Data in a Data Extension

This data connector 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.

...

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

Info

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 more than 2 fields 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.

  3. On the left side menu of new screen, navigate to App > Installed Packages.


  4. On the Installed Packages screen. Select New.


  5. Type the Name and Description.

  6. Select Create with enhanced functionality (recommended).

  7. Select Save.


  8. Select API Integration.

  9. Select Next.


  10. Select Server-to-Server.

  11. Select Next.


  12. Locate Contacts > Audiences and to Contacts > List and Subscribers.

  13. Select Read and Write under both to use Replace Audience feature.

  14. Locate Data > Data Extensions.

  15. Select Read and Write.
    You need these permissions to write data to Salesforce Marketing Cloud.

  16. Select Save.


  17. Locate the Components panel.

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


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

  3. Search for and select Salesforce Marketing Cloud.


  4. Select Enhanced Package Integration.


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

  6. Select Continue.


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.

...

  1. Open the TD Console.

  2. Navigate to Data Workbench > Queries > New Query.


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

    Code Block
    languagesql
    firstline1
    SELECT name as customer_name, email as primary_key 
    FROM data_extension limit 10

    The primary key can be a text field.


  4. Select Export Results located at top of your query editor. 


  5. Select an existing connection.

  6. Specify a Data Extension Name. Optionally, if your Data Extension does not exist, select Create Data Extension to create a brand new data extension.


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

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

  9. Long & Text are 2 supported data type 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.
  10. Select the Is Sendable option, if your data extension is sendable.

  11. Set your Sendable Rule by Subscriber Key or Email Address.

  12. Select your Sendable Column as a sendable property in your data extension.


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

  14. Select Done.

Run the Query

  1. Select Run to run the query.

  2. Check the query results are written to the configured data extension.


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/

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

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)

boolean

default is true

true

false

Example Configurations

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

...