ibm integration bus salesforce連携...1.salesforce.comへのセキュア接続の構成...
TRANSCRIPT
IBM Integration Bus Salesforce連携
2017.06
日本アイ・ビー・エム システムズ・エンジニアリング(株)
©2017 IBM Corporation2
はじめに� 当資料はIBM Integration Bus(以下IIB)v10.0.0.4で新規追加されたSalesforce.comとの連携機能についてご紹介します。
当資料に記載している内容は可能な限り稼動確認を取っておりますが、日本アイ・ビー・エム株式会社、及び日本アイ・ビー・エムシステムズ・エンジニアリング株式会社の正式なレビューを受けておらず、当資料で提供される内容に関して日本アイ・ビー・エム株式会社、日本アイ・ビー・エム システムズ・エンジニアリング株式会社は何ら保証するものではありません。従って、当資料の利⽤またはこれらの技法の実施はひとえに使⽤者の責任において為されるものであり、当資料によって受けたいかなる被害に関しても⼀切の補償をするものではありません。
©2017 IBM Corporation3
目次� Salesforce連携のサポート� Salesforce接続に必要な事前準備� Salesforceオブジェクトの操作� Salesforce用 JSONスキーマの提供
©2017 IBM Corporation4
Salesforce連携のサポート
©2017 IBM Corporation5
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
©2017 IBM Corporation6
Salesforce連携のサポート� 稼動環境のIIBにはApplication Integration Suiteのライセンスが必要
� developerモードとapplicationIntegrationSuiteモードで使用可能� developerモードでは開発まで
� mqsimodeコマンドでモードの確認/変更
� サポート・プラットフォームはWindowsとLinux x64
6
©2017 IBM Corporation7
� 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
©2017 IBM Corporation8
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
©2017 IBM Corporation9
Salesforce接続に必要な事前準備
©2017 IBM Corporation10
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
©2017 IBM Corporation11
1. Salesforce.comへのセキュア接続の構成1.1 Salesforce.comにログインし、接続アプリケーションの定義を作成
11
①ログイン画面の「クイックリンク」->「アプリケーション」->「アプリケーションを管理する」をクリック
②「接続アプリケーション」で「新規」を選択補足:Lightning Experience使用時は左側のメニューから「アプリケーション」>「アプリケーションマネージャ」を開き、右上の「新規接続アプリケーション」をクリック
©2017 IBM Corporation12
1. Salesforce.comへのセキュア接続の構成
12
③以下のプロパティを設定し、保存<基本情報>接続アプリケーション:IBM Integration BusAPI参照名:IBM_Integration_Bus取引先責任者メール:メールアドレス<API(OAuth 設定の有効化)>OAuth 設定の有効化:チェックを入れるコールバックURL:任意のセキュアなURLを指定(HTTP URLは不可)(例)https://www.ibm.com選択したOauth範囲:データへのアクセスと管理(api)
©2017 IBM Corporation13
1. Salesforce.comへのセキュア接続の構成
13
④「Manage」をクリックし、OAuthポリシーの「許可されているユーザ」が「すべてのユーザーは自己承認可能」に設定されていることを確認
©2017 IBM Corporation14
1. Salesforce.comへのセキュア接続の構成
14
⑤接続アプリケーション作成時に、IIBからSalesforceに接続する際に使用する「コンシューマ鍵(Consumer Key)」と「コンシューマの秘密(Consumer Secret)」が生成される*後のIIBからの接続設定のために、このコンシューマ鍵とコンシューマの秘密をコピーして保管しておく
©2017 IBM Corporation15
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
©2017 IBM Corporation16
1. Salesforce.comへのセキュア接続の構成※1 セキュリティ・トークンの取得方法 (未取得または不明の場合)1. Salesforceにログインし、右上のログインユーザー名のプルダウン・メニューから「私の設定」をクリック
2. 左側のメニューから「個人用」->「私のセキュリティ・トークンのリセット」をクリック
3. 開いたページで「セキュリティトークンのリセット」ボタンをクリック4. 自分のメール・アドレスに新しいセキュリティートークンが送信される
16
補足:Lightning Experience使用時は自分のアイコン をクリックし、「設定」
©2017 IBM Corporation17
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: コマンドが完了しました。
コマンドで稼動モードを変更
©2017 IBM Corporation18
Salesforceオブジェクトの操作
©2017 IBM Corporation19
Salesforceシステムのオブジェクト・アクセス� 以下のいずれかの操作を選択し、Saleforceオブジェクトのレコードにアクセスする
� Salesforce Request NodwのBasicタブ->Operationで実施する操作を指定
19
操作 説明Create Salesforceオブジェクトにレコードを追加するRetrieve Salesforceオブジェクトからレコードを取得するUpdate Salesforceオブジェクトのレコードを更新するDelete Salesforceオブジェクトのレコードを削除する
©2017 IBM Corporation20
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
©2017 IBM Corporation21
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件以上のレコードデータ
©2017 IBM Corporation22
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指定は有効
©2017 IBM Corporation23
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のレコードが返される
©2017 IBM Corporation24
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のレコードが返される
©2017 IBM Corporation25
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の子エレメントとして取得するレコードのフィールド名を指定複数指定が可能
©2017 IBM Corporation26
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の情報のみを取得(④)する
©2017 IBM Corporation27
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
©2017 IBM Corporation28
UPDATE� 更新対象のレコードが存在しない場合、Salesforce ID指定時はエラー、外部ID指定時はUPSERT(レコードが存在しないときはInsert)の動作になる
� ただしその際は、必須フィールドの指定が必要� 外部ID指定で対象レコードが複数件ある場合はエラーとなる� Salesforce ID、外部IDともに指定がなく、⼊⼒メッセージ・ツリーにIdエレメントが存在する場合はその値をSalesforce IDとして利⽤し、該当レコードを更新
28
©2017 IBM Corporation29
DELETE� DELETE:Salesforceシステム上のレコードを削除する
� 削除対象のレコードが存在しない場合はエラーとなる
29
項目 値Salesforce Requestノード(BasicタブのOperation) DeleteSalesforceへのインプット ⼊⼒メッセージのBody部はなし削除対象のレコードのSalesforce IDを指定LocalEnvironment.Destination.Salesforce.Request.idSalesforceからのアウトプット 削除されたレコードのSalesforce ID
©2017 IBM Corporation30
Salesforce用 JSONスキーマの提供
©2017 IBM Corporation31
Salesforce用のJSONスキーマの提供� Salesforceオブジェクト用のJSONスキーマを提供
� Mappingノードで利⽤が可能� JSONスキーマは install_dir/server/sample/Salesforceディレクトリに提供
� Mappingノード使用時の注意点� 事前に共有ライブラリーを作成し、アクセスするSalesforceオブジェクト用のスキーマをインポート
31
インポート画面
アクセスするSalesforceオブジェクト用のJSONスキーマを選択してインポートSalesforceオブジェクト用のJSONスキーマはinstall_dir/server/sample/Salesforce配下に提供
©2017 IBM Corporation32
Salesforce用のJSONスキーマの提供� スキーマを利⽤するマッピングノードのマップ定義は共有ライブラリーをコンテナーとして指定� Mappingノードの⼊出⼒メッセージ定義の選択画⾯で使⽤するJSONスキーマを選択するには、JSONスキーマとマップ定義を同じ共有ライブラリーに含める必要がある� メッセージ・フローを格納するアプリケーションから該当の共有ライブラリにプロジェクト参照を設定
32
JSONスキーマをインポートした共有ライブラリをコンテナーとして指定
©2017 IBM Corporation33
Salesforce用のJSONスキーマの提供� MappingノードでのSalesforce用JSONスキーマの指定例
33
選択したJSONスキーマの定義が表示される
Mappingノードの⼊出⼒メッセージ定義の選択画⾯で、利⽤するJSONスキーマにチェックを入れる
©2017 IBM Corporation34
Salesforce用のJSONスキーマの提供� JSONスキーマ使用時の注意点
� RETRIEVEの⽅法によってマッピングノードで適切なJSONスキーマを選択する必要がある� SalesforceID指定のRETRIEVEではJSONオブジェクトで結果が戻される(単一レコードの取得)� 上記以外のRETRIEVEではJSON配列で結果が戻される
34
【Accountオブジェクト使⽤時の例】・オブジェクト用のJSONスキーマはAccount – Account.json・配列⽤のJSONスキーマはJSONArray_Account – Account.json