Free MuleSoft CONNECT Keynote & Expo Pass Available!

Register now+
Nav

Salesforce Marketing Cloud Connector

Select

The Salesforce Marketing Cloud connector lets you connect to the Marketing Cloud API web services (now known as the Marketing Cloud API), which is also known as the Salesforce Marketing Cloud. This connector exposes convenient operations for exploiting the capabilities of Salesforce Marketing Cloud.

Prerequisites

This document assumes that you are familiar with Salesforce Marketing, Mule, Anypoint Connectors, Anypoint Studio, Mule concepts, elements in a Mule flow, and Global Elements.

You need login credentials to test your connection to your target resource.

For hardware and software requirements and compatibility information, see the Connector Release Notes.

To use this connector with Maven, view the pom.xml dependency information in the Dependency Snippets in Anypoint Exchange.

What’s New in this Connector

Now each operation returns a map instead of a POJO. The map is a representation of old POJO having field name as key and field value as value.

To Connect in Design Center

  1. Click a trigger. You can create a global element by selecting this connector as they trigger. If a global element is not needed, you can use an HTTP Listener or Scheduler trigger.

  2. To create an optional global element for the connector, set these fields:

    Design Center global element

  3. See Required Parameters for Username Password More details and see Username Password in the See Also section of this document.

  4. See Required Parameters for the OAuth Username Password and see OAuth Username Password in See Also.

  5. Select the plus sign to add a component.

  6. Select the connector as a component.

  7. Configure these fields:

    • Create:

      • ObjectType - Type of API object to create.

      • Api Objects - An array of one or more API objects.

        Create fields

    • Delete:

      • ObjectType - Type of API object to delete.

      • Api Objects - An array of one or more API objects.

        Delete fields

    • Update:

      • ObjectType - Type of API object to update.

      • Api Objects - An array of one or more API objects.

        SMC-update

    • Upsert:

      • ObjectType - Type of API object to upsert.

      • Api Objects - An array of one or more API objects.

        SMC-upsert

    • Configure Create:

      • ObjectType - Type of configuration.

      • Configurations - An array of one or more configurations to create.

        DC-configure-create

    • Configure Update:

      • ObjectType - Type of configuration.

      • Configurations - An array of one or more configurations to update.

        DC-configure-update

    • Configure Delete:

      • ObjectType - Type of configuration.

      • Configurations - An array of one or more configurations to delete.

        DC-configure-delete

    • Perform Start:

      • ObjectType - Type of object to do a perform on.

      • Definitions - An array of one or more definitions for the perform operation.

        DC-perform-start

    • Perform Stop:

      • ObjectType - Type of object that supports the Stop Action of the Perform Operation.

      • Definitions - An array of one or more definitions for the perform operation.

        DC-perform-stop

    • Perform Get Max Count:

      • ObjectType - Type of object to do a perform on

      • Definitions - An array of one or more definitions for the perform operation.

        DC-perform-get-max-count

    • Schedule Start:

      • ObjectType - Type of object to do a schedule on.

      • Interactions - An array of one or more interactions in the schedule operation.

        DC-schedule-start

    • Retrieve:

      • Query - Query describing the objects that you want to retrieve.

        DC-retrieve

Required Parameters for Username Password

  • Username - Username used to initialize the session.

  • Password - Password used to authenticate the user.

    user-pass-config

Required Parameters for the OAuth Username Password

  • Client ID - Client ID for your installed package.

  • Client Secret - Client Secret for your installed package.

  • OAuth Endpoint - Endpoint for Identity Provider (IDP) responsible with issuing API Key.

  • Soap Endpoint - Endpoint for Service Provider (SP) hosting services to be used with issued API Key.

    user-pass-config

    Note: Be careful where you store your Client ID and Secret. Never expose this information on the client side using JavaScript or store it in a mobile application. Ensure that these credentials are stored securely in your application.

Connect in Anypoint Studio 7

You can use this connector in Anypoint Studio by first downloading it from Exchange and configuring it as needed.

Install Connector in Studio

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

  2. Click Login in Anypoint Exchange.

  3. Search for this connector and click Install.

  4. Follow the prompts to install this connector.

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

Configure in Studio

  1. Drag and drop the connector to the Studio Canvas.

  2. To create a global element for the connector, set these fields:

    1. Username Password:

      • Username - Username used to initialize the session

      • Password - Password used to authenticate the user

        user-pass-config

    2. OAuth Username Password:

      • Client ID - Client ID for your installed package.

      • Client Secret - Client Secret for your installed package.

      • OAuth Endpoint - Endpoint for Identity Provider (IDP) responsible with issuing API Key.

      • Soap Endpoint - Endpoint for Service Provider (SP) hosting services to be used with issued API Key.

        user-pass-config

Use Case - Creating an Object

  1. Create a new Mule Project by clicking on File > New > Mule Project.

  2. Supply a name for your project and click Finish.

    New project dialog

  3. Open pom.xml and under dependencies section add the following dependency for Mule Salesforce Marketing Connector, but first replace --VERSION-- with the latest version available:

    
                 
              
    1
    2
    3
    4
    5
    6
    
    <dependency>
        <groupId>org.mule.connectors</groupId>
        <artifactId>mule-module-sfdc-marketing-cloud-connector</artifactId>
        <version>--VERSION--</version>
        <classifier>mule-plugin</classifier>
    </dependency>
  4. Create the flow.

Navigate through the project’s structure, double-click src/main/app/smc-usecase-create-object.xml, and follow the steps below:

  1. Search for the HTTP > Listener element in the palette.

  2. Drag the Listener element onto the canvas.

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

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

  5. Add a Transform Message after Salesforce Marketing Cloud.

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

    HTTP Listener component

  7. Click the plus Button next to Connector configuration.

  8. Specify the Host as localhost and Port as 8081, then click OK.

  9. Specify the Path as /create.

  10. Double-click Create (Salesforce Marketing Cloud).

    SMC Create config

  11. Click the plus Button next to Connector configuration.

    SMC user-pass config

  12. Specify the required fields with the credentials for your organization, then click OK.

  13. From the Object type drop down choose List.

  14. Double-click Transform Message (the one before Create) and configure it as below:

    Transform message before

  15. Double-click Transform Message (the one after Create) and configure it as below:

    Transform message after

  16. Once you are done with the Mule app, you can deploy it.

  17. Once deployed, use your favorite REST client and make a POST request to x-www-form-urlencoded to localhost:8081/create and the following parameter payload listName=testlist (such as curl -d listName=MyName-Test localhost:8081/create).

  18. You should get a successful result and once you get it, go to your instance and check that the list was created.

Note: 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 remap fields on the Transform Message component as needed. Upload and Delete could be configured in exactly the same way.

Use Case: 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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:sfdc-marketing-cloud="http://www.mulesoft.org/schema/mule/sfdc-marketing-cloud"
xmlns:ee="http://www.mulesoft.org/schema/mule/ee/core"
xmlns:http="http://www.mulesoft.org/schema/mule/http"
xmlns="http://www.mulesoft.org/schema/mule/core"
xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.mulesoft.org/schema/mule/core
http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/http
http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/ee/core
http://www.mulesoft.org/schema/mule/ee/core/current/mule-ee.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">
        <configuration-properties file="mule-app.properties" />
        <http:listener-config name="HTTP_Listener_config" doc:name="HTTP Listener config">
                <http:listener-connection host="localhost" port="8081" />
        </http:listener-config>
        <sfdc-marketing-cloud:sfdc-marketing-cloud-config name="Salesforce_Marketing_Cloud_Sfdc_marketing_cloud_config" doc:name="Salesforce Marketing Cloud Sfdc marketing cloud config">
                <sfdc-marketing-cloud:basic-connection username="${config.username}" password="${config.password}" authEndPoint="${config.endpoint}" />
        </sfdc-marketing-cloud:sfdc-marketing-cloud-config>
        <flow name="smc-usecase-create-objectFlow">
                <http:listener doc:name="Listener" config-ref="HTTP_Listener_config" path="/create"/>
                <ee:transform doc:name="Transform Message">
                        <ee:message >
                                <ee:set-payload ><![CDATA[%dw 2.0
output application/java
---
[{
        ListName: payload.listName
}]]]></ee:set-payload>
                        </ee:message>
                </ee:transform>
                <sfdc-marketing-cloud:create doc:name="Create" config-ref="Salesforce_Marketing_Cloud_Sfdc_marketing_cloud_config" objectType="List"/>
                <ee:transform doc:name="Transform Message">
                        <ee:message >
                                <ee:set-payload ><![CDATA[%dw 2.0
output application/json
---
payload]]></ee:set-payload>
                        </ee:message>
                </ee:transform>
        </flow>
</mule>

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, see the next section.

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.

Note: You can achieve this behavior by manually adding the desired fields inside the Transform Message component. Also, 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.

See the Providing a Subclass as a Type to a Complex Field section 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.

Note: The Salesforce Marketing Cloud has a limitation preventing retrieval of fields that are part of a hierarchy.

To better illustrate this issue, consider this 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 also contains the structure of the Automation object you acted upon.

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

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 is Operation Queued.

See the Asynchronous Operations section for more information 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 API 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 Salesforce Marketing Cloud SOAP API.

Add a Proxy

To use a proxy server the following system properties must be set at runtime:


          
       
1
2
3
Dhttp.proxyHost =<proxy host>

Dhttp.proxyPort=<proxy port>

If the proxy server is configured to require authentication the following Java system properties must be set:


          
       
1
2
3
Dhttp.proxyUser=<proxy user>

Dhttp.proxyPassword=<proxy password>

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.

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 Automation

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.

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 Variables (vars) 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. For more details regarding the operations from Marketing Cloud API, access the Salesforce Marketing Cloud Methods documentation listed in the See Also section of this document.

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 Variables(vars).

Create Automation

This is how the mapping for CreateOptions looks in the Variables (vars). 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 has 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 documentation and look for the Option objects(such as for CreateOptions or DeleteOptions).