Salesforce Marketing Cloud Connector 4.1 - Mule 4

Salesforce Marketing Cloud 用 Anypoint Connector (Marketing Cloud Connector) を使用すると、Marketing Cloud API Web サービス (現在は Marketing Cloud API といい、Salesforce Marketing Cloud ともいいます) に接続できます。このコネクタは、Salesforce Marketing Cloud の機能を利用した便利な操作を公開します。

リリースノート: 『Salesforce Marketing Cloud Connector リリースノート』
Exchange: Salesforce Marketing Cloud Connector Leaving the Site

始める前に

この情報を使用するには、Salesforce Marketing、Mule Runtime Engine (Mule)、Anypoint Connector、Anypoint Studio、Mule の概念、Mule フローの要素、グローバル要素に精通している必要があります。

対象リソースへの接続をテストするには、ログイン情報が必要です。

ソフトウェアの要件および互換性情報については、「コネクタリリースノート」を参照してください。

コネクタの一般的なユースケース

Salesforce Marketing Cloud Connector の一般的なユースケースを次に挙げます。

顧客インサイト

顧客の購買傾向、ライフスタイル、サブスクリプションなどの顧客の完全な統一ビューを取得して、顧客のジャーニーに継続的にリアルタイムで適応します。
パーソナライズ

SAP、Oracle E-Business Suite、NetSuite、Workday などの外部システムのバックオフィスデータと統合することで、パーソナライズされ、対象を絞り込んだメールキャンペーンを作成します。
マーケティングオートメーション

ビジネスプロセスを自動化することで時間を節約しながら、顧客とエンゲージします。たとえば、顧客への今後のメールをスケジュールできます。

これらのユースケースの例については、「Salesforce Marketing Cloud Connector の例」を参照してください。

POM ファイル情報

<dependency>
  <groupId>com.mulesoft.connectors</groupId>
  <artifactId>mule-sfdc-marketing-cloud-connector</artifactId>
  <version>x.x.x</version>
  <classifier>mule-plugin</classifier>
</dependency>xml

x.x.x を使用しているコネクタに対応するバージョンに置き換えます。最新の pom.xml ファイル情報を取得する手順は、次のとおりです。

Anypoint Exchange に移動します。
Exchange で、[Login (ログイン)] をクリックし、Anypoint Platform のユーザー名とパスワードを指定します。
Exchange で、「<connector-name>」を検索します。
コネクタを選択します。
画面の右上付近にある [Dependency Snippets (連動関係スニペット)] をクリックします。

このコネクタの新機能

このコネクタバージョンには、2.x バージョンと同じ操作がありますが、それらの一部は異なる方法でグループ化されています。また、このコネクタでは FuelSDK も使用されなくなりました。代わりに SOAP 要求自体が実行されます。

Studio プロジェクトでコネクタを追加して設定する

Studio プロジェクトでコネクタを追加する手順は、次のとおりです。

Studio で Mule プロジェクトを作成します。
[Mule Palette (Mule パレット)] ビューで、[(X) Search in Exchange ((X) Exchange 内を検索)] をクリックします。
[Add Modules to Project (モジュールをプロジェクトに追加)] で、検索項目に「marketing」と入力します。
[Available modules (使用可能なモジュール)] で、このコネクタの名前をクリックします。
[Add (追加)] をクリックします。
[Finish (完了)] をクリックします。

Studio でコネクタを設定する

コネクタを Studio キャンバスにドラッグします。
コネクタのグローバル要素を作成するには、次の項目を入力します。
- 基本認証 (ユーザー名/パスワード):
  - Username (ユーザー名) - セッションの初期化に使用するユーザー名。
  - Password (パスワード) - ユーザーの認証に使用するパスワード。
  - Service URL (サービス URL) - コネクタからアクセスする Salesforce Marketing Cloud のサービスの URL。
- OAuth クライアントログイン情報認証の場合:
  - Service URL (サービス URL) - コネクタがアクセスする Salesforce Marketing Cloud サービスの URL。 * *Client Id (クライアント ID) - インストール済みパッケージのクライアント ID。
  - Client secret (クライアントシークレット) - インストール済みパッケージのクライアントシークレット。
  - Token url (トークン URL) - アクセストークンを提供するエンドポイントの URL。

ユースケース - オブジェクトを作成する

[File (ファイル)] > [New (新規)] > [Mule Project (Mule プロジェクト)] を選択して新しい Mule プロジェクトを作成します。
プロジェクトの名前を入力して、[Finish (完了)] をクリックします。

pom.xml ファイルを開き、Mule Salesforce Marketing Connector の以下の連動関係を追加します。ここで、x.x.x は現在のコネクタバージョンです。

<dependency>
    <groupId>org.mule.connectors</groupId>
    <artifactId>mule-module-sfdc-marketing-cloud-connector</artifactId>
    <version>x.x.x</version>
    <classifier>mule-plugin</classifier>
</dependency>xml

プロジェクトの構造内で移動して、src/main/app/smc-usecase-create-object.xml をダブルクリックします。
[Mule Palette (Mule パレット)] ビューで [HTTP] コンポーネントを探します。
Listener 操作をキャンバスにドラッグします。
[Transform Message] コンポーネントを探して、[Listener] の後にドラッグします。
[Salesforce Marketing Cloud] を探して、[Create entities] 操作を [Transform Message] の後にドラッグします。
フローに [Transform Message] コンポーネントを [Create] の後に追加します。
[Listener] コンポーネントをダブルクリックします。
[Connector configuration (コネクタ設定)] 項目の横にあるをクリックします。
[Host (ホスト)] に「localhost」、[Port (ポート)] に「8081」を指定して、[OK] をクリックします。
[Path (パス)] に「/create」を指定します。
[Create (作成)] をダブルクリックします。
[Connector configuration (コネクタ設定)] の横にあるをクリックします。
必須項目に組織のログイン情報を指定して、[OK] をクリックします。
[Object type (オブジェクト種別)] ドロップダウンから、[List (リスト)] を選択します。
[Transform Message] (フローの [Create] の左側) をダブルクリックして、以下のとおり設定します。
[Transform Message] (フローの [Create] の右側) をダブルクリックして、以下のとおり設定します。
アプリケーションをデプロイします。
REST クライアントを使用して、POST 要求に listName=testlist のパラメーターペイロードを指定し、x-www-form-urlencoded to localhost:8081/create に対して実行します。

例: curl -d listName=MyName-Test localhost:8081/create。
インスタンスに移動してリストが作成されたことを確認します。

Upload や Delete などの他のコネクタ操作についても同様のフローを使用できますが、Salesforce Marketing Cloud でオブジェクト種別を作成するオブジェクトの名前に変更し、必要に応じて Transform Message コンポーネントの項目をマップし直す必要があります。

ユースケース: XML

各自のコードをアプリケーションの XML 表現と比較します。

<?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>xml
コンテンツを展開する

既知の問題と制限事項

Salesforce Marketing Cloud Connector には、次のような場合を含めて、いくつか制限があります。

複雑な項目内でサブクラスの操作
階層から項目の取得
Automation オブジェクトを返すための試行。

複雑な項目内のサブクラスの操作

Salesforce Marketing Cloud の一定のオブジェクトには基本クラスに属する複雑な項目があります (Recurrence 項目など)。DataSense では基本クラスに固有の項目しか表示できません。

基本クラスのサブクラスに属する他の項目を使用するには、Transform Message コンポーネントに目的の項目を手動で追加します。サブクラスを使用することを Salesforce Marketing Cloud に知らせ、追加した項目を認識させるために、このサブクラスの名前を値とする文字列型の concreteClassType という項目を追加する必要があります。

この手順を詳述した例については、「複雑な項目にサブクラスをデータ型として指定」を参照してください。

Retrieve 操作の制限

Retrieve 操作では、SQL クエリのようなやり方でレコードを取得できます。Retrieve 操作を使用する場合、Salesforce Marketing Cloud によって階層内の項目の取得が妨げられます。たとえば、Subscriber オブジェクトの構造は複雑です。

API では、EmailAddress や SubscriberKey といった第 1 レベルの項目のみ照会でき、Attributes.Name のような項目は照会できません。

Retrieve 操作では、データを照会するための検索条件がサポートされます。ただし、検索条件の動作は SQL 検索条件とは異なります。たとえば、WHERE 1=1 などの句は SQL では動作しますが、Salesforce Marketing Cloud では API でサポートされないため、エラーになります。この例では、等号の左にあるオペランドは Salesforce データエクステンション (SFDE) の有効なプロパティである必要があります。

WHERE 1=1 句を使用して要求を実行すると、検索条件でプロパティが想定されます。次の要求に変換されます。

<Filter xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SimpleFilterPart"> <Property>1</Property> <SimpleOperator>equals</SimpleOperator> <Value>1</Value> </Filter>。

応答は次のようになります。

`<OverallStatus>Error: The Filter Property '1' is not a retrievable property.</OverallStatus>`。

クエリの結果を絞り込む場合、WHERE 句でサポートされるのは次の演算子のみです。

演算子	Salesforce Marketing API の同等の演算子
=	equals
<>	notEquals
>	greaterThan
>=	greaterThanOrEqual
<	lessThan
⇐	lessThanOrEqual
like	like

演算子

Salesforce Marketing API の同等の演算子

equals

notEquals

greaterThan

greaterThanOrEqual

lessThan

⇐

lessThanOrEqual

このコネクタは、ネイティブの Salesforce OQL ではなく DSQL クエリ構文を使用し、Salesforce サーバーに SQL クエリをそのまま送信しません。代わりに、クエリを解析して XML オブジェクトに変換してからクエリを送信します。このため、上記の表に含まれない検索条件や、TOP(x)、LIMIT、OFFSET、ALIAS、JOIN などの SQL 構文機能はサポートされません。詳細は、『Salesforce API ガイド』 Leaving the Site

を参照してください。

Automation オブジェクトが含まれるサーバー側の結果

Automation オブジェクトが含まれるサーバー側の結果によって例外がスローされます。Automation オブジェクトで操作 (Create や Delete など) を実行すると、返された結果に実行した Automation オブジェクトの構造が含まれます。サーバーは Automation オブジェクトに isPlatformObject という追加項目も返しますが、WSDL で認識されません。

この問題を回避するには、どの操作でも Automation オブジェクトを直接非同期に使用します。操作が非同期の場合は、操作で即時に Operation Queued (操作をキューに追加済み) という応答を受信します。

詳細は、「非同期操作」を参照してください。

一般的なユースケース

次の一般的なユースケースでは、Salesforce Marketing Cloud Connector 操作を使用します。

Configure action 操作 - Marketing Cloud API SOAP Web サービスに接続した状態で、[Action (アクション)] パラメーターの値として [Create (作成)]、[Delete (削除)]、[Update (更新)] を指定した Configure メソッドをコールする。
Create entities 操作 - Marketing Cloud API Web サーバーに新しいオブジェクトを作成する。
Delete objects 操作 - Marketing Cloud API Web サーバーの既存のオブジェクトを削除する。
Perform operation - Marketing Cloud API SOAP Web サービスに接続した状態で、[Action (アクション)] パラメーターの値として [GetMaxCount (最大数を取得)]、[Start (開始)]、[Stop (停止)] を指定した Perform メソッドをコールする。
Retrieve entities 操作 - SQL クエリのような方法で Marketing Cloud API Web サーバーからオブジェクトを取得する。
Schedule start 操作 - Marketing Cloud API SOAP Web サービスに接続した状態で、[Action (アクション)] パラメーターの値として [Start (開始)] を指定した Schedule メソッドをコールする。
Update entities 操作 - Marketing Cloud API Web サーバーの既存のオブジェクトを更新する。
Upsert entities 操作 - オブジェクトがまだ存在しない場合は Marketing Cloud API Web サーバーにオブジェクトを作成し、サーバーに既存のオブジェクトが存在する場合は更新する。

プロキシの追加

プロキシサーバーを使用するには、設定の [Advanced (詳細)] タブで次の設定プロパティを設定します。

複雑な項目にサブクラスをデータ型として指定

サブスクライバーのリストに毎分メールを送信する既存の自動化をスケジュールするとします。このためには、フロー変数を使用して、スケジュール参照をコネクタに追加します。

[ScheduleDefinition] の [Recurrence (繰り返し)] 項目を使用して、メールの送信間隔などの情報を提供します。[Recurrence (繰り返し)] 項目は、構造のない複雑な項目です。

Recurrence の代わりに MinutelyRecurrence を指定するには、次の作業を行います。

MinutelyRecurrence クラスに属する項目を手動で追加する。
値がサブクラスの名前である文字列型の concreteClassType という項目を追加する。

この例の ScheduleDefinition のマッピングは次のようになります。

このマップに minuteInterval という項目がありますが、この項目は MinutelyRecurrence という Recurrence のサブクラスに属しています。

コネクタで MinutelyRecurrence オブジェクトを使用するには、concreteClassType 項目を追加し、値に MinutelyRecurrence を指定する必要もあります。

非同期操作

大半の操作はデフォルトで同期的に行われ、コネクタが操作の結果を待機します。Marketing Cloud API の操作に関する詳細は、Salesforce Marketing Cloud のメソッドのドキュメントを参照してください。

操作が非同期で行われるよう指定するには、操作の Options パラメーターを使用します。

次の例では、ペイロードに提供される Automation オブジェクトのリストを作成します。操作で Automation オブジェクトを直接処理すると、未知の項目が存在した場合に例外がスローされるため、この例では CreateOptions パラメーターを使用して非同期でコールを実行します。この例では、vars という変数に CreateOptions 値が指定されています。

値が指定されている [Create options (オプションを作成)] 項目

vars の CreateOptions のこのマッピングは次のようになります。

requestType 項目がコールの種別 (SYNCHRONOUS または ASYNCHRONOUS) を判断します。
conversationID 項目が非同期コールに一意の ID を割り当てます。

conversationID、callsInConversation、sequenceCode 項目を使用して、非同期コールをグループ化できます。たとえば、サーバーに対して 5 つの非同期コールを実行順序を指定して同時に実行するとします。次の手順を実行します。

同じ conversationID を各コールに割り当てる。
callsInConversation 項目を 5 に設定する。
sequenceCode 項目を使用してコールの順序を指定します。

次の例では、コールが 1 回であるため、callsInConversation と sequenceCode に 1 の値を渡します。

Options パラメーターにはこの例で示したもの以外にも機能があります。詳細は、Salesforce Marketing Cloud オブジェクトのドキュメントを参照してください。