Contact Us 1-800-596-4880

Salesforce Marketing Cloud Connector

Select

Demos and Technical Reference: See Anypoint Exchange

The Anypoint Connector for Salesforce Marketing Cloud lets you connect to the 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.

Before You Begin

This document assumes that you are familiar with Salesforce Marketing Cloud, Mule, Anypoint connectors, and Anypoint Studio.

Requirements

To use the Salesforce Marketing Cloud connector, you need:

  • Maven dependencies - If you don’t use Anypoint Studio for development, follow the instructions to install Salesforce Marketing Cloud Maven dependencies from your pom.xml file.

  • Salesforce Marketing Cloud developer account - Sign up for one in the Salesforce Marketing Cloud.

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

Marketing Cloud 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:

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

    <dependency>
        <groupId>org.mule.modules</groupId>
            <artifactId>mule-module-sfdc-marketing-cloud-connector</artifactId>
        <version>x.x.x</version>
    </dependency>

    Replace x.x.x with the version that corresponds to the connector you are using.

  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:

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

To Install this Connector

  1. In Anypoint Studio, click the Exchange icon in the Studio taskbar.

  2. Click Login in Anypoint Exchange.

  3. Search for the connector and click Install.

  4. Follow the prompts to install the connector.

When Studio has an update, a message displays in the lower right corner, which you can click to install the update.

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.

  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
    • Username: Enter the username.

    • Password: Enter the password.

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

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

    • 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-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 Marketing Cloud 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:

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:

  • Configure Create - Calls the "Configure" command with "Create" as the action attribute when connected to the Marketing Cloud SOAP web service.

  • Configure Delete - Calls the "Configure" command with "Delete" as the action attribute when connected to the Marketing Cloud API SOAP web service.

  • Configure Update - Calls the "Configure" command with "Update" as the action attribute when connected to the Marketing Cloud API SOAP web service.

  • Create - Creates a new object on the Marketing Cloud API web server.

  • Delete - Deletes an existing object on the Marketing Cloud API web server.

  • Perform get max count - Calls the "Perform" command with "GetMaxCount" as the action attribute when connected to the Marketing Cloud API SOAP web service.

  • Perform start - Sends a "Perform" command having "Start" as an action attribute when connected to the Marketing Cloud API SOAP web service.

  • Perform stop - Sends a "Perform" command having "Stop" as an action attribute when connected to the Marketing Cloud API SOAP Web service.

  • Retrieve - Retrieves objects from the Marketing Cloud API web server in a SQL query-like fashion.

  • Schedule start - Calls the "Schedule" command with "Start" as the action attribute when connected to the Marketing Cloud API SOAP web service.

  • Update - Updates an existing object on the Marketing Cloud API web server.

  • Upsert - Creates an object if the object does not already exist, or delete an existing object on the Marketing Cloud API web server. This operation is achieved by using "Create" method of the Marketing Cloud API SOAP API.

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

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.

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.

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

Example Use Case - Creating an Object - Studio Visual Editor

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 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 the File element.

    File component
  7. Click …​ 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 the File component and navigate to Metadata on the File component’s menu on the left-hand side, then click 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 o Salesforce Marketing Cloud connector.

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

  12. The global element properties pop-up prompts you for information required for basic authentication.

  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.

  17. Double-click 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 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 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.

Example Use Case - Creating an Object - XML Editor

Follow these 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:

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

    <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"/>
  3. Add a Flow element to your project, then configure its attributes as follows:

    <flow name="usecase1Flow">
    </flow>
  4. Inside the flow tag add a file:inbound-endpoint element to your project, then configure its attributes as follows:

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

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

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

    <logger level="INFO" doc:name="Logger" message="Creation done."/>

Complete Flow XML

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

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

View on GitHub