Nav
You are viewing an older version of this section. Click here to navigate to the latest version.

Salesforce Marketing Cloud Connector

Demos and Technical Reference: See Anypoint Exchange

The Anypoint Connector for Salesforce Marketing Cloud lets you connect to the ExactTarget web services (a.k.a Salesforce Marketing Cloud). The connector exposes convenient methods for exploiting the capabilities of Salesforce Marketing Cloud.

Read this document to understand how to set up and configure a basic flow using the connector. Read through the Technical Reference to understand how the connector operations interact with Salesforce. You also find demo applications that illustrate how to use the connector operations. Release Notes are a good way to track feature additions, compatibility limitations and API version updates with each release of the connector version.

MuleSoft maintains this connector under the Select support policy.

Prerequisites

This document assumes that you are familiar with Mule, the Anypoint Studio interfaceGlobal Elements, DataSense, and batch processing in Mule. Further, it assumes you are familiar with Salesforce Marketing Cloud.

Requirements

To use the Salesforce Marketing Cloud connector, you need:

To use a Salesforce Marketing Cloud connector in your Mule application, be sure to include the namespace and schema location.

Compatibility

Application/Service Version

Mule Runtime

3.5.2 and higher

Exact Target API

v145.3

Dependencies

Configuring Maven Dependencies

After you download and install the connector, use the following steps to make the Salesforce Marketing Cloud connector available to inside a Mule application for use and packaging.

  1. Add the repository information to your project’s pom.xml file:

    
                
             
    1
    2
    3
    4
    5
    6
    7
    
    <repositories>
        <repository>
            <id>mule-ee-releases</id>
            <name>MuleEE Releases Repository</name>
            <url>https://repository-master.mulesoft.org/nexus/content/repositories/releases-ee/</url>
        </repository>
    </repositories>
  2. Add the module as a dependency to your project using the release version:

    
                
             
    1
    2
    3
    4
    5
    
    <dependency>
        <groupId>org.mule.modules</groupId>
            <artifactId>mule-module-sfdc-marketing-cloud-connector</artifactId>
        <version>RELEASE</version>
    </dependency>

    Or for the latest:

    
                
             
    1
    2
    3
    4
    5
    
    <dependency>
        <groupId>org.mule.modules</groupId>
            <artifactId>mule-module-sfdc-marketing-cloud-connector</artifactId>
        <version>LATEST</version>
    </dependency>
  3. If you plan to use this module inside a Mule application, you need to add it to the packaging process. That way the final zip file which contains your flows and Java code also contains this module and its dependencies. Add a special inclusion to the configuration of the Mule Maven plugin for this module as follows:

    
                
             
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    
    <plugin>
        <groupId>org.mule.tools</groupId>
        <artifactId>maven-mule-plugin</artifactId>
        <extensions>true</extensions>
        <configuration>
            <excludeMuleDependencies>false</excludeMuleDependencies>
            <inclusions>
                <inclusion>
                    <groupId>org.mule.modules</groupId>
                    <artifactId>mule-module-sfdc-marketing-cloud-connector</artifactId>
                </inclusion>
            </inclusions>
        </configuration>
    </plugin>

Installing and Configuring

Installing the Connector

You can install a connector in Anypoint Studio using the instructions in Installing a Connector from Anypoint Exchange.

Configuring the Salesforce Marketing Cloud Global Element

To use the Salesforce Marketing Cloud connector in your Mule application, you must configure a global Salesforce Marketing Cloud connector element that can be used by all the Salesforce Marketing Cloud connectors in the application (read more about global elements).

Adding the Salesforce Marketing Cloud Connector to a Flow

To use the Salesforce Marketing Cloud connector in a Mule application project, create a new project.

Create a New Project

  1. From Anypoint Studio click File > New > Mule Project.

  2. Studio opens the New Mule Project wizard. Fill in the Name field with a desired project name.

    new-mule-project

  3. If you plan to use Git, select "Create a default .gitignore file" for the project with default ignores for Studio Projects, and then click Next.

  4. Click Finish to create the project.

  5. Drag the Salesforce Marketing Cloud connector onto the canvas, then select it to open the properties editor.

  6. Configure the connector’s parameters:

    Salesforce Marketing Cloud operation config

    Field Description

    Display Name

    Enter a unique label for the connector in your application.

    Connector Configuration

    Select a global Salesforce Marketing Cloud connector element from the drop-down.

    Operation

    Select an operation for the connector to perform.

  7. Save your configurations.

Salesforce Marketing Cloud Connector Authentication

To access the data in a Salesforce instance, authenticate using "Basic authentication".

All you need to do in order to use "Basic Authentication" is to provide your credentials in a global configuration element, then reference the global configuration in any Salesforce Marketing Cloud connector in your application. If you notice that you are getting connection timeouts or read timeouts, you can modify the Connection Timeout and Read Timeout from the General Category, to increase those values.

  1. Required parameters for Basic authentication:

    Basic-Authentication

    1. Username: Enter the username.

    2. Password:  Enter the password. 

    3. Endpoint: Enter the address of the endpoint responsible for handling login requests

    4. Read Timeout: Specifies the amount of time, in milliseconds, that the consumer will wait for a response before it times out. Default value is 0 which means the value used by Fuel SDK will be taken

    5. Connection Timeout: Specifies the amount of time, in milliseconds, that the consumer will attempt to establish a connection before it times out. Default value is 0 which means the value used by Fuel SDK will be taken

Using the Connector

The Salesforce Marketing Cloud connector functions within a Mule application as a secure entrance through which you can access – and act upon – your organization’s information in Salesforce Marketing Cloud.

Using the connector, your application can perform several operations that Salesforce Marketing Cloud exposes via web services. When building an application that connects with Salesforce Marketing Cloud, for example, an application to create new Subscribers into a List, you don’t have to go through the effort of custom-coding (and securing!) a connection. Rather, you can just drop a connector into your flow, configure a few connection details, then begin transferring data. 

The real value of the Salesforce Marketing Cloud connector is in the way you use it at design-time in conjunction with other functionality available in Mule.

  • DataSense: When enabled, DataSense extracts metadata for Salesforce Marketing Cloud standard objects (APIObjects) to automatically determine the data type and format that your application must deliver to, or can expect from, Salesforce Marketing Cloud. By enabling this functionality (in the Global Salesforce Marketing Cloud connector element), Mule does the heavy lifting of discovering the type of data you must send to, or be prepared to receive from Salesforce Marketing Cloud.

  • Transform Message: When this component is used in conjunction with a DataSense-enabled Salesforce Marketing Cloud connector, DataWeave can automatically extract APIObject metadata that you can use to visually map and/or transform to a different data format or structure. For example, if you configure a Salesforce Marketing Cloud connector in your application, then drop a Transform Message component after it, DataWeave uses the information that DataSense extracted to pre-populate the input values for mapping. In other words, DataSense makes sure that DataWeave knows the data format and structure with which it must work so you don’t have to figure it out manually. Moreover, DataWeave has a scripting language that let’s you control the mapping between data types.

  • Batch Processing: A batch job is a block of code that splits messages into individual records, performs actions upon each record, then reports on the results and potentially pushes the processed output to other systems or queues. This functionality is particularly useful when working with streaming input or when engineering "near real-time" data integration with SaaS providers such as Salesforce Marketing Cloud.

At the time of release of version 1.0.0 of the Salesforce Marketing Cloud connector, it can only be used as an outbound connector.

Use it as an outbound connector in your flow to push data into Salesforce Marketing Cloud by simply placing the connector in your flow at any point after an inbound endpoint (see image below, top). Note that you can also use a Salesforce Marketing Cloud connector in a batch process to push data to Salesforce Marketing Cloud in batches (see image below, bottom).

sfdc-mktng-outbound.png

sfdc-mktng-example_batch_output1

Known Issues and Limitations

The Salesforce Marketing Cloud connector comes with a few caveats. If you are working with subclasses inside complex fields, trying to retrieve fields from a hierarchy or attempting to return an "Automation" object, read on.

Workaround to Provide a Subclass Type to a Complex Field

Some objects in Salesforce Marketing Cloud have complex fields belonging to a base class (for example, a Recurrence field) In this particular case, DataSense is only able to bring up fields specific to a base class, but you might want to use additional fields that belong to a subclass of that base class.

You can achieve this behavior by manually adding the desired fields inside the Transform Message component. Also, in order for Salesforce Marketing Cloud to know that you want to work with a subclass and recognize the fields you added, you must also add an extra field called "concreteClassType" of type String whose value is the name of the subclass.

Please go to the Providing a Subclass as a Type to a Complex Field subsection, for an example detailing how to achieve this.

Retrieving Fields From a Hierarchy is Not Possible

The Retrieve operation allows you to retrieve records in a SQL query-like fashion.

The ExactTarget API has a limitation preventing retrieval of fields that are part of a hierarchy.

To better illustrate this issue, we will go through an example. The Subscriber object has a complex structure:

subscriber structure

The API only allows us to query fields on the first level, like EmailAddress or SubscriberKey but not fields like Attributes.Name

Server Results Containing an Automation Object Cause Exception to be Thrown

When performing an operation on an Automation object (like Create or Delete), the returned result will also contain the structure of the Automation object you acted upon.

The problem is that the server also returns an additional field in the Automation called "isPlatformObject" that is not recognized by the WSDL.

In order to bypass this issue, make all operations that directly use an Automation object asynchronous. If the operation is asynchronous, the immediate response of the operation will be something like "Operation Queued".

Please see the Asynchronous Operations subsection for further explanation on how to make operations asynchronous.

Common Use Cases

The following are the common use cases for the Salesforce Marketing Cloud connector:

  1. Configure Create - Use this operation for calling the "Configure" command with "Create" as the action attribute when connected to the ExactTarget SOAP web service. For more information see: Configure

  2. Configure Delete - Use this operation for calling the "Configure" command with "Delete" as the action attribute when connected to the ExactTarget SOAP web service. For more information see: Configure

  3. Configure Update - Use this operation for calling the "Configure" command with "Update" as the action attribute when connected to the ExactTarget SOAP web service. For more information see: Configure

  4. Create - Use this operation for creating a new object on the ExactTarget web server. For more information see: Create

  5. Delete - Use this operation for deleting an existing object on the ExactTarget web server. For more information see: Delete

  6. Update - Use this operation for updating an existing object on the ExactTarget web server. For more information see: Update

  7. Upsert - Use this operation to create an object if the object does not already exist, or delete an existing object on the ExactTarget web server. This operation is achieved by using "Create" method of the ExactTarget SOAP API. For more information on that see: Create

  8. Perform get max count - Use this operation for calling the "Perform" command with "GetMaxCount" as the action attribute when connected to the ExactTarget SOAP web service. For more information see: Perform

  9. Perform start - Use this operation for sending "Perform" command having "Start" as an action attribute when connected to the ExactTarget SOAP web service. For more information see: Perform

  10. Perform stop - This operation provides a convenient method for sending "Perform" command having "Stop" as an action attribute when connected to the ExactTarget SOAP Web service. For more information on "Perform" see: Perform

  11. Retrieve - Use this operation for retrieving objects from the ExactTarget web server in a SQL query-like fashion. For more information see: Retrieve

  12. Schedule start - Use this operation for calling the "Schedule" command with "Start" as the action attribute when connected to the ExactTarget SOAP web service. For more information see: Schedule

Providing a Subclass as a Type to a Complex Field

Let’s say we want to schedule an existing Automation to send emails to a list of subscribers once per minute.

In order to do this, we would input a Schedule Reference into the connector through a flow variable for example, to provide details about the schedule.

Schedule Start interface

Details such as how much time should pass between emails sent should go into a field called Recurrence. The field Recurrence found in ScheduleDefinition, for example, is a complex field that has no structure: Recurrence DataWeave

In order to specify that we want to work with a MinutelyRecurrence, and not a Recurrence, we must manually add the fields belonging to the MinutelyRecurrence class, and add an extra field called concreteClassType of type String whose value is the name of the subclass.

Here is how the mapping for the ScheduleDefinition would look in the flowVars for our example: Schedule Definition

Notice that the recurrence map has a field called minuteInterval that actually belongs to a subclass of Recurrence, called MinutelyRecurrence.

In order for the connector to know that it is dealing with a MinutelyRecurrence object, we must also add the extra concreteClassType field with MinutelyRecurrence as the value.

Asynchronous Operations

Most operations are synchronous by default, meaning that the connector waits for the result of the operation. For more details regarding the operations from ExactTarget access the Salesforce Marketing Cloud Methods documentation.

To specify that you want an operation to behave asynchronously, you must use the Options parameter from the operation. We show in an example how this behavior can be achieved for the Create operation. This can also be done in a similar fashion for the other operations.

In this example we create a list of Automation objects to provide in the payload. Because Automation objects present an issue where the result of any operation that directly works with this type of object throws an exception caused by the presence of an unknown field, we make the operation asynchronous; this allows us to bypass this issue.

The CreateOptions parameter is responsible with making the call asynchronous. In our example, the CreateOptions is provided in a flowVars. Create Automation

This is how the mapping for CreateOptions looks in the flowVars. The field requestType determines the type of call (SYNCHRONOUS or ASYNCHORONOUS). The conversationID field assigns an unique identifier to the asynchronous call.

Asynchronous calls can be grouped together using the conversationID, callsInConversation and sequenceCode fields (for example, if we want to make 5 asynchronous calls to the server, but we want them to execute together and we want to specify in which order to execute, we put the same conversationID to all of them, we put to callsInConversation the value 5, meaning that our group will have 5 calls, and sequenceCode is the order of the call in the group).

For this example, because we have a single call, we pass a value of 1 to callsInConversation and sequenceCode.

CreateOptions

The Options parameter has more functionality that shown in this example. For further studying the capabilities of this parameter, visit the Salesforce Marketing Cloud Objects and look for the Option objects( ex. CreateOptions or DeleteOptions).

Example Use Case - Creating an Object

Unconfigured All In One flow

Create a new Mule Project by clicking on File > New > Mule Project. In the new project dialog box, the only thing you are required to enter is the name of the project. Click on Finish.

Now let’s create the flow. Navigate through the project’s structure and double-click on src/main/app/project-name.xml and follow the steps below:

  1. Search for the File element in the palette.

  2. Drag the File element onto the canvas.

  3. Search for Transform Message and drag it after File.

  4. Search for Salesforce Marketing Cloud and drag it after Transform Message.

  5. Add a Logger after Salesforce Marketing Cloud.

  6. Let’s start configuring each element. Double-click on the File element.

    File component

  7. Click on …​ next to the Path field.

  8. Choose a folder with the .csv file that you want to upload. You can download our example file and save it onto your local system.

  9. Click on the File component and navigate to Metadata on the File component’s menu on the left-hand side, then click on the Add metadata button. File component’s metadata

    1. Then click the "Edit" icon beside the newly created dropdown which shows "Output: Payload" as the value. pic of edit icon

    2. Now you should see something similar to this:

      Define new metadata for Subscriber

    3. Fill in the fields specified in the image above starting by selecting the "Create new type" radio button.

    4. For "Type Id" enter "DemoMetadata".

    5. From the dropdown under "Type Id" choose "Example".

    6. Next to the above-mentioned dropdown browse to the test .json file you downloaded.

  10. Double-click on Salesforce Marketing Cloud connector.

  11. Click on the plus sign next to the Connector Configuration dropdown.

  12. The global element properties pop-up prompts you for information required for basic authentication. For more info see the Installing and Configuring section.

  13. In the Connection section enter the username and password credentials used to access the Salesforce Marketing Cloud instance or reference them using the "placeholders" you may have set in a properties file.

  14. Click OK to return to the Salesforce Marketing Cloud tab.

  15. From the Operation dropdown in the Basic Settings section choose Create.

  16. From the Object Type dropdown in the General section choose <Object Type to Create> (e.g. Subscriber if you use the test file provided above).

    1. For this example create an object of type Subscriber. Your connector’s configuration should be complete. sfdc-mktng-props

  17. Double-click on the Transform Message element.

  18. Link "EmailAddress" field from input to the "EmailAddress" field from output.

  19. Link "SubscriberKey" field from input to the "SubscriberKey" field from output.

    Subscriber Transformer message

  20. Double-click on the Logger component.

  21. In the "Message" field enter the text "Creation done." Now the application can be deployed.

  22. Run the application in Anypoint Studio (Right-click on the project name > Run As > Mule Application). Monitor the Studio console for the "Creation done." message and ensure the new objects were created in the Salesforce Marketing Cloud.

For other entities you can use a similar flow but you have to change the "Object Type" in the "Salesforce Marketing Cloud" to the name of the object that you are going to create, and re-map fields on the Transform Message component as needed. "Upload" and "Delete" could be configured in exactly the same way.

Following the below steps, you should end up with the same functioning application as illustrated in the Studio Visual Editor tab. Reference the full XML configuration for this app by skipping to the Complete Flow XML.

  1. Add a context:property-placeholder element to your project, then configure its attributes as follows:

    
           
                   
                
    1
    
    &lt;context:property-placeholder location="mule-app.properties"/&gt;
  2. Add a sfdc-marketing-cloud:config element to your project, then configure its attributes as follows:

    
           
                   
                
    1
    
    &lt;sfdc-marketing-cloud:config name="Salesforce_Marketing_Cloud__Basic_Authentication" username="${config.username}" password="${config.password}" endpoint="${config.endpoint}" doc:name="Salesforce Marketing Cloud: Basic Authentication"/&gt;
  3. Add a Flow element to your project, then configure its attributes as follows:

    
           
                   
                
    1
    2
    
    &lt;flow name="usecase1Flow"&gt;
    &lt;/flow&gt;
  4. Inside the flow tag add a file:inbound-endpoint element to your project, then configure its attributes as follows:

    
           
                   
                
    1
    
    &lt;file:inbound-endpoint responseTimeout="10000" doc:name="File" moveToDirectory="src/main/resources/processed" path="src/main/resources/input"/&gt;
  5. Inside the flow tag add a dw:transform-message element to your project, then configure its attributes as follows:

    
           
                   
                
    1
    2
    3
    4
    5
    6
    7
    
    &lt;dw:transform-message doc:name="Transform Message"&gt;
                &lt;dw:set-payload&gt;&lt;![CDATA[%dw 1.0
    %output application/java
    ---
    {
    }]]&gt;&lt;/dw:set-payload&gt;
    &lt;/dw:transform-message&gt;
  6. Inside the flow tag add a sfdc-marketing-cloud:create element to your project, then configure its attributes as follows:

    
           
                   
                
    1
    
    &lt;sfdc-marketing-cloud:create config-ref="Salesforce_Marketing_Cloud__Basic_Authentication" objectType="Subscriber" doc:name="Salesforce Marketing Cloud"/&gt;
  7. Inside the flow tag add a sfdc-marketing-cloud:create element to your project, then configure its attributes as follows:

    
           
                   
                
    1
    
    &lt;logger level="INFO" doc:name="Logger" message="Creation done."/&gt;

Complete Flow XML

You may check your code against the complete application’s XML representation, shown below.


          
       
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:context="http://www.springframework.org/schema/context" xmlns:file="http://www.mulesoft.org/schema/mule/file" xmlns:dw="http://www.mulesoft.org/schema/mule/ee/dw" xmlns:sfdc-marketing-cloud="http://www.mulesoft.org/schema/mule/sfdc-marketing-cloud" xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
        xmlns:spring="http://www.springframework.org/schema/beans"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-current.xsd
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/sfdc-marketing-cloud http://www.mulesoft.org/schema/mule/sfdc-marketing-cloud/current/mule-sfdc-marketing-cloud.xsd
http://www.mulesoft.org/schema/mule/file http://www.mulesoft.org/schema/mule/file/current/mule-file.xsd
http://www.mulesoft.org/schema/mule/ee/dw http://www.mulesoft.org/schema/mule/ee/dw/current/dw.xsd">
        <context:property-placeholder location="mule-app.properties"/>
    <sfdc-marketing-cloud:config name="Salesforce_Marketing_Cloud__Basic_Authentication" username="${config.username}" password="${config.password}" endpoint="${config.endpoint}" doc:name="Salesforce Marketing Cloud: Basic Authentication"/>
    <flow name="usecase1Flow">
        <file:inbound-endpoint responseTimeout="10000" doc:name="File" moveToDirectory="src/main/resources/processed" path="src/main/resources/input"/>
        <dw:transform-message doc:name="Transform Message">
            <dw:set-payload><![CDATA[%dw 1.0
%output application/java
---
{
}]]></dw:set-payload>
        </dw:transform-message>
        <sfdc-marketing-cloud:create config-ref="Salesforce_Marketing_Cloud__Basic_Authentication" objectType="Subscriber" doc:name="Salesforce Marketing Cloud"/>
        <logger level="INFO" doc:name="Logger"/>
    </flow>
</mule>

See Also