IBM Integration Bus Salesforce連携...1.Salesforce.comへのセキュア接続の構成...

IBM Integration Bus Salesforce連携

2017.06

日本アイ・ビー・エムシステムズ・エンジニアリング（株）

©2017 IBM Corporation2

はじめに� 当資料はIBM Integration Bus（以下IIB）v10.0.0.4で新規追加されたSalesforce.comとの連携機能についてご紹介します。

当資料に記載している内容は可能な限り稼動確認を取っておりますが、日本アイ・ビー・エム株式会社、及び日本アイ・ビー・エムシステムズ・エンジニアリング株式会社の正式なレビューを受けておらず、当資料で提供される内容に関して日本アイ・ビー・エム株式会社、日本アイ・ビー・エムシステムズ・エンジニアリング株式会社は何ら保証するものではありません。従って、当資料の利⽤またはこれらの技法の実施はひとえに使⽤者の責任において為されるものであり、当資料によって受けたいかなる被害に関しても⼀切の補償をするものではありません。


目次� Salesforce連携のサポート� Salesforce接続に必要な事前準備� Salesforceオブジェクトの操作� Salesforce用 JSONスキーマの提供


Salesforce連携のサポート


Salesforce連携のサポート� IIBv10.0.0.4でSalesforceRequestノードを提供

� Salesforce.comと連携し、Salesforce上のレコードの参照、作成、更新、削除が可能� StrongloopのLoopbackコネクター・テクノロジーを使用して、Salesforceと通信� LoopbackコネクターはForce.com REST APIを使用してSalesforceを呼び出す� SalesforceとはJSON形式のメッセージを使用して連携

� SalesforceRequestを利⽤することで、容易にSalesforceとの連携を実現� SalesforceRequestノード1つで、ログインとオブジェクトへの操作を実⾏� 参照条件などもLocalEnvironmentを使用してシンプルに設定が可能

5

In --- --- Failure--- Out


Salesforce連携のサポート� 稼動環境のIIBにはApplication Integration Suiteのライセンスが必要

� developerモードとapplicationIntegrationSuiteモードで使用可能� developerモードでは開発まで

� mqsimodeコマンドでモードの確認/変更

� サポート・プラットフォームはWindowsとLinux x64

6


� Salesforce Requestノードの主なプロパティSalesforce Requestノード

タブ設定項目必須説明Basic Salesforce URL ○ SalesforceシステムのURL（例：https://login.salesforce.com）Operation ○ 使用する操作（Create、Retrieve、Update、Deleteから選択）Salesforce object ○ 使用するSalesforceのオブジェクト名を指定（リストから選択）Security identity ○ Salesforce接続用に定義したセキュリティIDTimeout Salesforceでの処理待機時間（デフォルト120000ミリ秒）Request Data location Salesforceに送るJSONオブジェクトデータが含まれるメッセージ・ツリーの場所（デフォルト：＄Body）Result Output data location Salesforceから戻されたデータがセットされるメッセージ・ツリーの場所（デフォルト：＄OutputRoot）Copy local environment ローカル環境変数を出⼒⽤にコピーするかどうかデフォルト：チェックあり7


LocalEnvironmentツリーの使用� Salesforce呼び出しに関係するLocalEnvironment変数

� LocalEnvironment.Destination.Salesforce.Request ツリーの子エレメントとして指定� LocalEnvironmentを使用してSalesforce Requestノードの一部プロパティを動的設定可能

8

LocalEnvironment変数上書きするノードプロパティ備考url Basicタブ：Salesforce URLoperation Basicタブ：Operarionobject Basicタブ：Salesforce objectId N/A Salesforce ID指定でSalesforceレコードのRetrieve、Update、Deleteを⾏う際に指定externalIdName N/A 外部ID指定でSalesforceレコードのRetrieve、Updateを⾏う際に指定externalId N/A 外部ID指定でSalesforceレコードのRetrieve、Updateを⾏う際に指定filter N/A SalesforceレコードのRetrieveにフィルター条件を指定する際に指定timeoutMilliseconds Basicタブ：Timeout


Salesforce接続に必要な事前準備


Salesforce接続に必要な事前準備� IIBからSalesforce.comに接続するために必要な事前準備1. Salesforce.comへのセキュア接続の構成

� 事前にSalesforce.comのアカウントを取得1.1 Salesforce.comにログインし、IIB用の接続アプリケーション定義を作成1.2 IIBでSalesforce接続用のセキュリティーIDを定義2. 統合ノードの動作モードを確認� 稼働環境はapplication Integration Suiteモード、もしくはdeveloperモードであることが前提� 必要なライセンスを取得し、mqsimodeコマンドで適切なモードになっていることを確認

10


1. Salesforce.comへのセキュア接続の構成1.1 Salesforce.comにログインし、接続アプリケーションの定義を作成

11

①ログイン画面の「クイックリンク」->「アプリケーション」->「アプリケーションを管理する」をクリック

②「接続アプリケーション」で「新規」を選択補足：Lightning Experience使用時は左側のメニューから「アプリケーション」>「アプリケーションマネージャ」を開き、右上の「新規接続アプリケーション」をクリック


1. Salesforce.comへのセキュア接続の構成

12

③以下のプロパティを設定し、保存<基本情報>接続アプリケーション：IBM Integration BusAPI参照名：IBM_Integration_Bus取引先責任者メール：メールアドレス<API（OAuth 設定の有効化）>OAuth 設定の有効化：チェックを入れるコールバックURL：任意のセキュアなURLを指定（HTTP URLは不可）（例）https://www.ibm.com選択したOauth範囲：データへのアクセスと管理（api）



13

④「Manage」をクリックし、OAuthポリシーの「許可されているユーザ」が「すべてのユーザーは自己承認可能」に設定されていることを確認



14

⑤接続アプリケーション作成時に、IIBからSalesforceに接続する際に使用する「コンシューマ鍵（Consumer Key）」と「コンシューマの秘密（Consumer Secret）」が生成される*後のIIBからの接続設定のために、このコンシューマ鍵とコンシューマの秘密をコピーして保管しておく


1. Salesforce.comへのセキュア接続の構成1.2 IIBでSalesforce接続用のセキュリティIDを定義

� mqsisetdbparmsコマンドで定義

15

構文：mqsisetdbparms NODE_NAME –n salesforce::securityIdentity –u UserId–p Password –c ClientIdentity –s ClientSecret

-n：Salesforce接続用のセキュリティID名-u：SalesforceのユーザーID-p：Salesforceに接続する際のパスワード+セキュリティ・トークン※1（次ページ参照）-c：Salesforceで接続アプリケーションを作成した際に生成されたConsumer Key-s：Salesforceで接続アプリケーションを作成した際に生成されたConsumer Secret

実⾏例：mqsisetdbparms SFBK -n salesforce::SFID -u [email protected] -p passw0rdr61Ae2hwGboJ7FrB88m64SN5z -c 3MVG9ZL0ppGP5UrBRMuimNnkEamT4oTPXVKGOGknCb.Z1YRCp4BAeNp1E9h

5dIXlENwAzqAMhWxGTbtmEHXKF -s 1920811130463312789


1. Salesforce.comへのセキュア接続の構成※1 セキュリティ・トークンの取得方法（未取得または不明の場合）1. Salesforceにログインし、右上のログインユーザー名のプルダウン・メニューから「私の設定」をクリック

2. 左側のメニューから「個人用」->「私のセキュリティ・トークンのリセット」をクリック

3. 開いたページで「セキュリティトークンのリセット」ボタンをクリック4. 自分のメール・アドレスに新しいセキュリティートークンが送信される

16

補足：Lightning Experience使用時は自分のアイコンをクリックし、「設定」


2. 統合ノードの動作モードを確認2. 統合ノードがapplicationIntegrationSuiteモードになっていることを確認

� applicationIntegrationSuiteモードでない場合は、mqsimodeコマンドで変更

17

稼動モードの変更の実⾏例：C:¥Program Files¥IBM¥IIB¥10.0.0.8>mqsimode SFBKBIP1802I: 統合ノード 'SFBK' は 'advanced' モードです。BIP1831I: 統合ノード 'SFBK' にはモード拡張機能 '' があります。BIP8071I: コマンドが完了しました。

C:¥Program Files¥IBM¥IIB¥10.0.0.8>mqsimode SFBK -o applicationIntegrationSuiteBIP1809I: 統合ノードのモードを 'SFBK' から 'applicationIntegrationSuite' に変更中...BIP8071I: コマンドが完了しました。

C:¥Program Files¥IBM¥IIB¥10.0.0.8>mqsimode SFBKBIP1802I: 統合ノード 'SFBK' は 'applicationIntegrationSuite' モードです。BIP1831I: 統合ノード 'SFBK' にはモード拡張機能 '' があります。BIP8071I: コマンドが完了しました。

コマンドで稼動モードを変更


Salesforceオブジェクトの操作


Salesforceシステムのオブジェクト・アクセス� 以下のいずれかの操作を選択し、Saleforceオブジェクトのレコードにアクセスする

� Salesforce Request NodwのBasicタブ->Operationで実施する操作を指定

19

操作説明Create Salesforceオブジェクトにレコードを追加するRetrieve Salesforceオブジェクトからレコードを取得するUpdate Salesforceオブジェクトのレコードを更新するDelete Salesforceオブジェクトのレコードを削除する


CREATE� CREATE: Salesforceシステム上のオブジェクトにレコードを1件追加する

20

項目値Salesforce Requestノード（BasicタブのOperation） CreateSalesforceへのインプット⼊⼒メッセージのBody部に追加するレコードの情報をセット例：「取引先」の登録項目の例Root.JSON.Data.NameRoot.JSON.Data.BillingStreetRoot.JSON.Data.BillingCityRoot.JSON.Data.BillingStateRoot.JSON.Data.BillingPostalCodeRoot.JSON.Data.BillingCountryRoot.JSON.Data.PhoneRoot.JSON.Data.AccountNumberSalesforceからのアウトプット⼊⼒メッセージ＋Salesforceに追加されたレコードのSalesforce ID


RETRIEVE� RETRIEVE: Salesforceシステム上の1件または複数のレコードを取得する

� SalesforceID指定のRETRIEVEではJSONオブジェクトで結果が戻される（単一レコードの取得）� 上記以外のRETRIEVEではJSON配列で結果が戻される

21

項目値Salesforce Requestノード（BasicタブのOperation） RetrieveSalesforceへのインプット⼊⼒メッセージのBody部はなしSalesforce ID指定、外部ID指定、Filter指定をする場合はLocalEnvironment.Destination.Salesforce.Request以下に使用する制御条件に応じてフィールド名と値を指定例：Idによるフィルタリングの場合LocalEnvironment.Destination.Salesforce.Request.IdSalesforceからのアウトプット SalesforceID指定時は該当のレコード、指定しない場合はJSON配列で0件以上のレコードデータ


RETRIEVE� 取得するレコードの制御

� Salesforce IDを指定することで、特定のレコードの取得が可能� LocalEnvironment.Destination.Salesforce.Request.Id環境変数にセット

� 外部ID名と外部ID値を指定することで、該当の外部IDを持つ特定もしくは複数レコードの取得が可能� LocalEnvironment.Destination.Salesforce.Request.externalIdName� LocalEnvironment.Destination.Salesforce.Request.externalIdにセット

� 上記項目をセットしない場合は、すべてのレコードを取得� 取得レコードのフィルタリングは可能

� 取得レコードのフィルタリング� LocalEnvironment.Destination.Salesforce.Request.filterに以下を使用してフィルター条件をセット

� where� Limit ・・・取得するレコードを制御� skip� Order ・・・指定した順番で取得� field ・・・特定のフィールドのみ取得

� 取得するレコードは以下の順番で精査される1. Salesforce ID2. External ID3. Filter� 取得レコードがない場合は空データが返される（エラーではない）

22

Salesforce IDでヒットしたらその他のフィルター条件は無視＊field指定は有効


RETRIEVE� Salesforce ID指定のフィルタリング

� レコード追加時にSalesforceで割り当てられたユニークIDを指定して取得� 実装例

� 要求メッセージの設定内容

� 取得結果

23

SET OutputLocalEnvironment.Destination.Salesforce.Request.id = '0012800001J7zALAAZ';(0x01000000:Object):JSON = ( ['json' : 0xc032360] (0x01000000:Object):Data = ( (0x03000000:NameValue):Id = '0012800001J7zALAAZ' (CHARACTER) (0x01000000:Object ):attributes = ( (0x03000000:NameValue):type = 'Account' (CHARACTER) (0x03000000:NameValue):url= '/services/data/v34.0/sobjects/Account/0012800001J7zALAAZ' (CHARACTER) ) (0x03000000:NameValue):IsDeleted = FALSE (BOOLEAN) (0x03000000:NameValue):MasterRecordId = NULL (0x03000000:NameValue):Name = ‘ABC company’ (CHARACTER) (0x03000000:NameValue):Type = ‘WARM’ (CHARACTER) (0x03000000:NameValue):ParentId = NULL (0x03000000:NameValue):BillingStreet = ‘Nakase1-1' (CHARACTER) (0x03000000:NameValue):BillingCity = ‘Mihama-ku' (CHARACTER) (0x03000000:NameValue):BillingState = 'Chiba' (CHARACTER) (0x03000000:NameValue):BillingPostalCode = '111-0000' (CHARACTER) (0x03000000:NameValue):BillingCountry = 'Japan' (CHARACTER)

指定したSalesforceIDのレコードが返される


RETRIEVE� 外部IDによるフィルタリング

� 外部IDを指定して取得� 該当レコードが複数ある場合は、複数件取得� 実装例

� 要求メッセージの設定内容� LocalEnvironment.Destination.Salesforce.Request.externalIdName に外部IDの項目名を指定（例はCustom_ID__c）� LocalEnvironment.Destination.Salesforce.Request.ExternalIdにその設定値を指定

� 取得結果

SET OutputLocalEnvironment.Destination.Salesforce.Request.externalIdName = 'Custom_ID__c';SET OutputLocalEnvironment.Destination.Salesforce.Request.externalId = '1000';[{"Id": "0012800001LbxHGAAZ", "Name": "AAA", "Custom_ID__c": "1000"}]指定した外部IDのレコードが返される


RETRIEVE� Filter条件によるフィルタリング

� Filter条件をかけることにより、Salesforceから返されるデータ量やSalesforceでの処理負荷を削減� LocalEnvironment.Destination.Salesforce.filterの子エレメントとして取得するレコードのフィルター条件を設定する� 使用可能なフィルター条件

25

エレメントタイプ説明where string Salesforce Object Query Language(SOQL) の条件式でwhere条件を指定limit positive integer 戻されるレコード数の上限数を指定skip positive integer 取得レコードの先頭から指定した件数分スキップしたレコードを戻すorder structure 取得レコードの順番をASCまたはDESCで指定orderの⼦エレメントとして昇順、降順を判断するレコードのフィールド名を指定複数指定が可能field structure レコードの中から取得するフィールドTRUEまたはFALSE、もしくは1または0で指定fieldの子エレメントとして取得するレコードのフィールド名を指定複数指定が可能


RETRIEVE� 実装例

� 要求メッセージの設定内容� 取得するSalesforceオブジェクトはAccount

� 取得結果

26

SET OutputLocalEnvironment.Destination.Salesforce.Request.filter.limit = 5;SET OutputLocalEnvironment.Destination.Salesforce.Request.filter.skip = 2;SET OutputLocalEnvironment.Destination.Salesforce.Request.filter.order[1].Name = 'ASC';SET OutputLocalEnvironment.Destination.Salesforce.Request.filter.order[2].AccountNumber = 'ASC';SET OutputLocalEnvironment.Destination.Salesforce.Request.filter.order[3].Type = 'DESC';SET OutputLocalEnvironment.Destination.Salesforce.Request.filter.field[1].Name = true;SET OutputLocalEnvironment.Destination.Salesforce.Request.filter.field[2].Phone = true;[{"Name":"Dickenson plc","Phone":"(785) 241-6200"},{"Name":"Edge Communications","Phone":"(512) 757-6000"},{"Name":"Express Logistics and Transport","Phone":"(503) 421-7800"},{"Name":"GenePoint","Phone":"(650) 867-3450"},{"Name":"Grand Hotels & Resorts Ltd","Phone":"(312) 596-1000"}]

・・・①・・・②・・・③・・・④

複数のorder条件（③）により、Accountから取得する結果セットを並べ、そこから先頭2件（②）を飛ばしたあとの5件（①）のレコードを取得。その際、レコードの中のNameとPhoneの情報のみを取得（④）する


UPDATE� UPDATE:Salesforceシステム上のレコードを更新する

27

項目値Salesforce Requestノード（BasicタブのOperation） UpdateSalesforceへのインプット⼊⼒メッセージのBody部にレコードの更新情報をセット＋以下のいずれかを設定Salesforce ID指定をする場合LocalEnvironment.Destination.Salesforce.Request.Id外部ID指定をする場合LocalEnvironment.Destination.Salesforce.Request.externalIdNameLocalEnvironment.Destination.Salesforce.Request.externalIdSalesforceからのアウトプット Salesforce ID指定時⼊⼒メッセージ＋更新されたレコードのSalesforce ID外部ID指定時（更新対象レコードが存在する場合）⼊⼒メッセージのみ外部ID指定時（更新対象レコードが存在しない場合）⼊⼒メッセージ＋Salesforceに追加されたレコードのSalesforce ID


UPDATE� 更新対象のレコードが存在しない場合、Salesforce ID指定時はエラー、外部ID指定時はUPSERT（レコードが存在しないときはInsert）の動作になる

� ただしその際は、必須フィールドの指定が必要� 外部ID指定で対象レコードが複数件ある場合はエラーとなる� Salesforce ID、外部IDともに指定がなく、⼊⼒メッセージ・ツリーにIdエレメントが存在する場合はその値をSalesforce IDとして利⽤し、該当レコードを更新

28


DELETE� DELETE:Salesforceシステム上のレコードを削除する

� 削除対象のレコードが存在しない場合はエラーとなる

29

項目値Salesforce Requestノード（BasicタブのOperation） DeleteSalesforceへのインプット⼊⼒メッセージのBody部はなし削除対象のレコードのSalesforce IDを指定LocalEnvironment.Destination.Salesforce.Request.idSalesforceからのアウトプット削除されたレコードのSalesforce ID


Salesforce用 JSONスキーマの提供


Salesforce用のJSONスキーマの提供� Salesforceオブジェクト用のJSONスキーマを提供

� Mappingノードで利⽤が可能� JSONスキーマは install_dir/server/sample/Salesforceディレクトリに提供

� Mappingノード使用時の注意点� 事前に共有ライブラリーを作成し、アクセスするSalesforceオブジェクト用のスキーマをインポート

31

インポート画面

アクセスするSalesforceオブジェクト用のJSONスキーマを選択してインポートSalesforceオブジェクト用のJSONスキーマはinstall_dir/server/sample/Salesforce配下に提供


Salesforce用のJSONスキーマの提供� スキーマを利⽤するマッピングノードのマップ定義は共有ライブラリーをコンテナーとして指定� Mappingノードの⼊出⼒メッセージ定義の選択画⾯で使⽤するJSONスキーマを選択するには、JSONスキーマとマップ定義を同じ共有ライブラリーに含める必要がある� メッセージ・フローを格納するアプリケーションから該当の共有ライブラリにプロジェクト参照を設定

32

JSONスキーマをインポートした共有ライブラリをコンテナーとして指定


Salesforce用のJSONスキーマの提供� MappingノードでのSalesforce用JSONスキーマの指定例

33

選択したJSONスキーマの定義が表示される

Mappingノードの⼊出⼒メッセージ定義の選択画⾯で、利⽤するJSONスキーマにチェックを入れる


Salesforce用のJSONスキーマの提供� JSONスキーマ使用時の注意点

� RETRIEVEの⽅法によってマッピングノードで適切なJSONスキーマを選択する必要がある� SalesforceID指定のRETRIEVEではJSONオブジェクトで結果が戻される（単一レコードの取得）� 上記以外のRETRIEVEではJSON配列で結果が戻される

34

【Accountオブジェクト使⽤時の例】・オブジェクト用のJSONスキーマはAccount – Account.json・配列⽤のJSONスキーマはJSONArray_Account – Account.json

IBM Integration Bus Salesforce連携...1.Salesforce.comへのセキュア接続の構成...

Documents

Transcript of IBM Integration Bus Salesforce連携...1.Salesforce.comへのセキュア接続の構成...