Contact Free trial Login

Salesforce Marketing Cloud Connector 3.1 - Mule 4

Support Category: Select

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.

Prerequisites

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.

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.

Connect in Design Center

  • The Configure Create, Configure Update, and Configure Delete operations are grouped into one operation called Configure. Use a parameter to specify the Create, Update, and Delete actions.

  • The Perform Start, Perform Stop, and Perform Get Max Count operations are grouped into one operation called Perform. Use a parameter to specify the Start, Stop, Get, and Max Count actions.

The connector no longer supports OAuth Username and Password authentication because the Salesforce Marketing Cloud deprecated this authentication type. The connector now supports OAuth Client Credentials authentication.

To Use the Connector in Design Center

To use the connector in Design Center:

  1. In Design Center, click Create.

  2. Click Create new application to open Flow Designer.

  3. Specify a value for Project name and click Create.

  4. Click Go straight to canvas to exit from Let’s get started.

  5. Click on the trigger card.

  6. Search for the connector.

  7. Select the connector name.

  8. Select the On modified object or On new object operation to use it as a source.

    Alternatively, you can also use the HTTP Listener or Scheduler component as a source.

  9. Click Click here to set it up.

  10. To create a global element for the connector, enter values for the Basic Authentication (Username Password) or OAuth Username Password authentication types:

    Design Center global element
    • For Basic Authentication (Username Password):

      • Username - Username used to initialize the session

      • Password - Password used to authenticate the

      • Service URL - URL of the service on Salesforce Marketing Cloud to be accessed from the connector

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

  11. Select the plus sign to add a component.

  12. Select the connector as a component.

  13. Configure these fields:

    • Create operation:

      • Object Type - Type of API object to create

      • Api Objects - Array of one or more API objects

        Create fields
    • Delete operation:

      • Object Type - Type of API object to delete

      • Api Objects - Array of one or more API objects

        Delete fields
    • Update operation:

      • Object Type - Type of API object to update

      • Api Objects - Array of one or more API objects

        SMC-update
    • Upsert operation:

      • Object Type - Type of API object to upsert

      • Api Objects - Array of one or more API objects

        SMC-upsert
    • Configure operation:

      • Configurations - Array of one or more configurations to create

      • Action - Create, Update, or Delete

      • Object Type - Type of configuration

        DC-configure
    • Perform operation:

      • Definitions - Array of one or more definitions for the Perform operation

      • Action - Action to perform. Can have the value Start, Stop, or Get. Max Count

      • Object Type - Target of the Perform operation

        DC-perform
    • Schedule Start operation:

      • Object Type - Type of object on which to have a schedule

      • Interactions - Array of one or more interactions in the Schedule operation

        DC-schedule-start
    • Retrieve operation:

      • Query - Query describing the objects to retrieve

        DC-retrieve

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.

        user-pass-config
    • 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

        user-pass-config

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.

    HTTP Listener component
  11. Click plus Button 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.

    SMC Create config
  15. Click the plus Button next to Connector configuration.

    SMC user-pass config
  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:

    Transform message before
  19. Double-click Transform Message (to the right of Create in the flow) and configure as shown below:

    Transform message after
  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:

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

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

Schedule Start Automation

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:

Schedule Start Automation

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:

Schedule Definition

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

Create Automation

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.

CreateOptions

The Options parameter has more functionality than shown in this example. For more information, see the Salesforce Marketing Cloud Objects documentation.