Salesforce Marketing Cloud Connector 4.0 | MuleSoft Documentation
# Salesforce Marketing Cloud Connector 4.0
Anypoint Connector for Salesforce Marketing Cloud (Marketing Cloud Connector) enables you to 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.
Release Notes: Salesforce Marketing Cloud Connector Release Notes Exchange: Salesforce Marketing Cloud Connector
## Before You Begin
To use this information, you should be familiar with Salesforce Marketing, Mule runtime engine (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 software requirements and compatibility information, see the Connector Release Notes.
## Common Use Cases for the Connector
Common use cases for Salesforce Marketing Cloud Connector include:
  * **Customer Insights**
Get a complete, unified view of the customer, such as their purchase habits, lifestyle, or subscriptions, and continually adjust to a customer’s journey in real time.
  * **Personalization**
Create personalized, targeted email campaigns by integrating with back-office data from external systems, such as SAP, Oracle E-Business Suite, NetSuite, and Workday.
  * **Marketing Automation**
Save time by automating your business processes while engaging with your customers. For example, you can schedule future emails for your customers.


For examples of these use cases, refer to Salesforce Marketing Cloud Connector Examples.
## POM File Information
```
<dependency>
 <groupId>com.mulesoft.connectors</groupId>
 <artifactId>mule-sfdc-marketing-cloud-connector</artifactId>
 <version>x.x.x</version>
 <classifier>mule-plugin</classifier>
</dependency>
```

Replace `x.x.x` with the version that corresponds to the connector you are using. To obtain the most up-to-date `pom.xml` file information:
  1. Go to Anypoint Exchange.
  2. In Exchange, click **Login** and supply your Anypoint Platform username and password.
  3. In Exchange, search for `<connector-name>`.
  4. Select the connector.
  5. Click **Dependency Snippets** near the upper right of the screen.


## What’s New in this Connector
This connector version has the same operations as the 2.x versions, but groups some of them differently. Also, the connector no longer uses FuelSDK. Instead, the connector performs the SOAP requests itself.
## Add and Configure the Connector in a Studio Project
To add the connector to a Studio project:
  1. In Studio, create a Mule project.
  2. In the Mule Palette view, click **(X) Search in Exchange**.
  3. In **Add Modules to Project** , type "marketing" in the search field.
  4. Click this connector’s name in **Available modules**.
  5. Click **Add**.
  6. Click **Finish**.


### Configure the Connector in Studio
  1. Drag the connector to the Studio Canvas.
  2. To create a global element for the connector, complete these fields:
     * Basic Authentication (Username Password):
       * **Username** - Username used to initialize the session
       * **Password** - Password used to authenticate the
       * **Service URL** - The URL of the service on Salesforce Marketing Cloud to be accessed from the connector.
     * OAuth Client Credentials authentication:
       * **Service URL** - URL of the Salesforce Marketing Cloud service that the connector will access** **Client Id** - Client ID for the installed package
       * **Client secret** - Client secret for the installed package
       * **Token url** - URL of the endpoint that provides the access tokens


### Use Case - Create an Object
  1. Create a new Mule project by selecting **File** > **New** > **Mule Project**.
  2. Supply a name for your project and click **Finish**.
  3. Open the pom.xml file and add the following dependency for Mule Salesforce Marketing Connector, where `x.x.x` is the current connector version:
```
<dependency>
  <groupId>org.mule.connectors</groupId>
  <artifactId>mule-module-sfdc-marketing-cloud-connector</artifactId>
  <version>x.x.x</version>
  <classifier>mule-plugin</classifier>
</dependency>
```

  4. Navigate through the project’s structure and double-click `src/main/app/smc-usecase-create-object.xml`.
  5. Search for the **HTTP** component in the Mule Palette view.
  6. Drag the **Listener** operation onto the canvas.
  7. Search for **Transform Message** and drag the component after the **Listener**.
  8. Search for **Salesforce Marketing Cloud** and drag the **Create entities** operation after **Transform Message**.
  9. Add a **Transform Message** component after **Create**.
  10. Double-click on the **Listener** component.
  11. Click next to the **Connector configuration** field.
  12. Specify the **Host** as localhost and **Port** as `8081`, then click **OK**.
  13. Specify the **Path** as `/create`.
  14. Double-click **Create**.
  15. Click the next to Connector configuration.
  16. Specify the required fields with the credentials for your organization and click **OK**.
  17. From the **Object type** drop-down select `List`.
  18. Double-click **Transform Message** (to the left of **Create** in the flow) and configure as shown below:
  19. Double-click **Transform Message** (to the right of **Create** in the flow) and configure as shown below:
  20. Deploy the app.
  21. Use a REST client to make a POST request to `x-www-form-urlencoded to localhost:8081/create` with the following parameter payload: `listName=testlist`.
For example, `curl -d listName=MyName-Test localhost:8081/create`.
  22. Go to your instance and check that the list was created.
You can use a similar flow for other connector operations, such as Upload and Delete, but you must 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.
### Use Case: XML
Check your code against the app’s XML representation:
```
<?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/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/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:config
  name="Salesforce_Marketing_Cloud_Config"
  doc:name="Salesforce Marketing Cloud Config" >
		<sfdc-marketing-cloud:basic-connection
   username="${config.username}"
   password="${config.password}"
   serviceUrl="${config.endpoint}" />
	</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_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
Salesforce Marketing Cloud Connector has some limitations, including when:
  * Working with subclasses inside complex fields
  * Trying to retrieve fields from a hierarchy
  * Attempting to return an Automation object.


### Working with Subclasses Inside Complex Fields
Some objects in Salesforce Marketing Cloud have complex fields, such as the Recurrence field, which belong to a base class. DataSense can only bring up fields specific to the base class.
To use additional fields that belong to a subclass of a base class, manually add the desired fields to the Transform Message component. For Salesforce Marketing Cloud to know that you want to work with a subclass and recognize the fields you added, you must also add a field called concreteClassType of type String whose value is the name of the subclass.
See Providing a Subclass as a Type to a Complex Field for an example detailing how to achieve this.
### Retrieve Operation Limitations
The Retrieve operation enables you to retrieve records in a SQL query-like fashion. When you use the Retrieve operation, Salesforce Marketing Cloud prevents the retrieval of fields that are part of a hierarchy. For example, the Subscriber object has a complex structure:
The API only allows you to query fields on the first level, such as `EmailAddress` or `SubscriberKey`, but not fields such as `Attributes.Name`.
The `Retrieve` operation supports filters for querying the data. However the filters do not behave like an SQL filter condition. For example, a clause such as `WHERE 1=1` works in SQL, but results in an error in Salesforce Marketing Cloud because the API doesn’t support it. In this example, the operand to the left of the equal sign must be a valid property of the Salesforce data extension (SFDE).
When executing the request with the `WHERE 1=1` clause, the filter expects a property. It is transformed into the following request:
`<Filter xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SimpleFilterPart"> <Property>1</Property> <SimpleOperator>equals</SimpleOperator> <Value>1</Value> </Filter>`.
The response is:
```
`<OverallStatus>Error: The Filter Property '1' is not a retrievable property.</OverallStatus>`.
```

When filtering the results of a query, only the following operators are supported in WHERE clauses:
Operator | Salesforce Marketing API equivalent  
---|---  
greaterThanOrEqual  
lessThanOrEqual  
This connector uses DSQL Query syntax instead of native Salesforce OQL and does not send the SQL query to the Salesforce server as is. Instead, the query is parsed and transformed into an XML object before it is sent. Because of this, any filters that are not included in the table above or any SQL syntax features, such as TOP(x), LIMIT, OFFSET, ALIAS, or JOINs, are unsupported. For more details, refer to the Salesforce API Guide.   
---  
### Server Results Containing an Automation Object
Server results that contain an Automation object cause an exception to be thrown. When performing an operation, such as Create or Delete, on an Automation object, the returned result contains the structure of the Automation object you acted upon. The server also returns an additional field in the Automation object called isPlatformObject that is not recognized by the WSDL.
To bypass this issue, make all operations that directly use an Automation object asynchronous. If an operation is asynchronous, the immediate response of the operation is `Operation Queued`.
For more information, see Asynchronous Operations.
## Common Use Cases
Use Salesforce Marketing Cloud Connector operations for the following common use cases:
  * `Configure action` operation - Calls the Configure method with Create, Delete, or Update as the value of the Action parameter when connected to the Marketing Cloud API SOAP web service.
  * `Create entities` operation - Creates new objects on the Marketing Cloud API web server.
  * `Delete objects` operation - Deletes existing objects on the Marketing Cloud API web server.
  * `Perform operation` - Calls the Perform method with the GetMaxCount, Start, or Stop as the value of the Action parameter when connected to the Marketing Cloud API SOAP web service.
  * `Retrieve entities` operation - Retrieves objects from the Marketing Cloud API web server in a SQL query-like fashion.
  * `Schedule start` operation - Calls the Schedule method with Start as the value of the Action parameter when connected to the Marketing Cloud API SOAP web service.
  * `Update entities` operation - Updates existing objects on the Marketing Cloud API web server.
  * `Upsert entities` operation - Creates objects on the Marketing Cloud API web server if the objects do not already exist, or updates existing objects on the server.


### Add a Proxy
To use a proxy server, set the following configuration properties on the **Advanced** tab of your configuration:
### Providing a Subclass as a Type to a Complex Field
Suppose you want to schedule an existing Automation that sends emails to a subscriber list once per minute. To do this, add a Schedule Reference to the connector through a flow variable:
Use the **Recurrence** field in **ScheduleDefinition** to provide information such as how much time to pass between sending emails. The **Recurrence** field is a complex field that has no structure.
To specify a MinutelyRecurrence instead of a Recurrence:
  * Manually add the fields belonging to the MinutelyRecurrence class.
  * Add an additional field called concreteClassType of type String whose value is the name of the subclass.
### Add a Proxy
To use a proxy server, set the following configuration properties on the **Advanced** tab of your configuration:
### Providing a Subclass as a Type to a Complex Field
Suppose you want to schedule an existing Automation that sends emails to a subscriber list once per minute. To do this, add a Schedule Reference to the connector through a flow variable:
Use the **Recurrence** field in **ScheduleDefinition** to provide information such as how much time to pass between sending emails. The **Recurrence** field is a complex field that has no structure.
To specify a MinutelyRecurrence instead of a Recurrence:
  * Manually add the fields belonging to the MinutelyRecurrence class.
  * Add an additional field called concreteClassType of type String whose value is the name of the subclass.


The mapping for the ScheduleDefinition looks like this in the example:
This map has a field called `minuteInterval` that belongs to a subclass of Recurrence called `MinutelyRecurrence`.
For the connector to use the MinutelyRecurrence object, you must also add the 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 of the Marketing Cloud API, access the Salesforce Marketing Cloud Methods documentation.
To specify that you want an operation to behave asynchronously, use the Options parameter for the operation.
The following example creates a list of Automation objects to provide in the payload. Because the result of any operation that works directly with Automation objects throws an exception caused by the presence of an unknown field, the example uses the CreateOptions parameter to make the call asynchronous. In this example, the CreateOptions value is provided in a variable called `vars`.
This mapping for CreateOptions in vars looks like this:
  * The requestType field determines the type of call (SYNCHRONOUS or ASYNCHRONOUS).
  * The conversationID field assigns a unique identifier to the asynchronous call.


You can group asynchronous calls together using the conversationID, callsInConversation, and sequenceCode fields. For example, suppose you want to make five asynchronous calls to the server, execute the calls together, and specify their execution order. To do this:
  1. Assign the same conversationID to each call.
  2. Set the callsInConversation field to 5.
  3. Use the sequenceCode field to order the calls.


The following example has a single call, so it passes a value of 1 to callsInConversation and sequenceCode.
The Options parameter has more functionality than shown in this example. For more information, see the Salesforce Marketing Cloud Objects documentation.
## See Also
  * Salesforce Get Started with the SOAP Web Services API
  * Salesforce API Integration.
  * Introduction to Anypoint Connectors
  * MuleSoft Help Center