外部システムで管理しているマスタデータを Questetra BPM Suite でも利用したいということが考えられます。今回は Salesforce で管理している顧客データを、Questetra BPM Suite に取り込んで、セレクトボックスの選択肢として使用することに取り組みたいと思います。
大枠の仕組みとしては、次の通りです。
Salesforce の顧客データを、API を介して取得します。そしてそのデータを Ver.9.9.0 で追加された新機能「サービスタスク（選択肢マスタ更新）」を利用して、Questetra BPM Suite の『選択肢マスタ』として取り込みます。ここまでを１つのワークフローアプリで実現します。
かたや Salesforce の顧客データを選択肢として利用したいアプリにおいては、選択型データ項目の選択肢設定にて、先の『選択肢マスタ』を指定するようにします。
今回は、前半の Salesforce の顧客データを、選択肢マスタとして取り込むアプリについて説明します。今回作成したサンプルのアプリは以下の通りです。
大まかな流れを示します。
-
- メッセージ送信中間イベント(HTTP)「APIに接続」で、Salesforce の API に接続。顧客データを取得し、文字型データ項目に保存する。
- スクリプトタスク「応答の解析」で、1 で取得した応答テキスト（JSON）を解析し、選択型データ項目として使用できる状態にする。
- サービスタスク（選択肢マスタ更新）「マスタ更新」で、2 で構成した選択型データ項目の選択肢を、選択肢マスタとして保存する。
途中、2つのタスクがありますが、先頭のタスクはプロセスを開始する役割、途中の「確認」タスクは 2 で構成した選択肢のデータを確認するためのものです。ゲートウェイ(分岐)は Salesforce の API アクセスでエラーがあった場合に、以降のプロセスの処理を行わないようにするためのものです。
アプリの主要な設定について説明します。まず必要なデータ項目は以下の通りです。
| 番号 | データ項目名 | データ型 | 補足説明 |
|---|---|---|---|
| 0 | 正常応答 | 文字型複数行 | Salesforce Platform から 顧客データを取得した時の応答 |
| 1 | エラー | 文字型複数行 | Salesforce Platform から 顧客データを取得した時に、エラーが発生した場合のエラー内容 |
| 2 | 顧客ID一覧 | 文字型複数行 | JSON応答を解析した結果、顧客ID一覧を格納する文字列 |
| 3 | 顧客名一覧 | 文字型複数行 | JSON応答を解析した結果、顧客名一覧を格納する文字列 |
| 4 | 顧客データ | 選択型ラジオ | サービスタスク（選択肢マスタ更新）で使用するためのデータ項目 |
1-1．Salesforce Platform から顧客データを取得する
メッセージ送信中間イベント(HTTP) を使用して、Salesforce Platform の API を呼び出し、顧客データを取得します。使用する API は、Lightning Platform REST API の Query です。
| 設定名 | 値 | 補足説明 |
|---|---|---|
| アクセスURL | https://na10.salesforce.com/services/data/v29.0/query/ | |
| HTTP Method | GET | |
| エラー発生時にエラー内容を格納する文字型データ項目 | エラー | 番号1 の文字型複数行のデータ項目を指定します。 |
| セキュリティ | ||
| OAuth2.0 で接続する | ||
| 設定名 | Force.com | 任意の値で構いませんが、後述する OAuth 2.0 の設定名とあわせる必要があります。OAuth 2.0 の設定の詳細は後述します。 |
| レスポンス | ||
| レスポンスを保存する | チェック | |
| 保存先のデータ項目 | 正常応答 | 番号0 の文字型複数行データ項目を指定します。 |
送信パラメータについては以下の通りです。
| パラメータ名 | 値 | 補足説明 |
|---|---|---|
| q | SELECT Id, Name from Account |
このAPI では、SOQL (Salesforce Object Query Language) という SQL に似たクエリを実行し、結果のオブジェクトを取得します。”SELECT Id, Name From Account” というクエリで、Account オブジェクトから、ID 属性と Name 属性を取得しています。Account オブジェクトはSalesforce の標準オブジェクトで、顧客データを表すオブジェクトです。どのようなオブジェクトがあるかは、オブジェクトリファレンスで参照できます。
1-2．Salesforce で OAuth2.0 の設定をする
Questetra BPM Suite から Salesforce の API に OAuth2.0 で接続するためには、Salesforce 側で設定をする必要があります。「アプリケーションの設定→作成→アプリケーション」から、「接続アプリケーション」を新規作成します。設定内容は以下の通りです。Salesforce での設定項目は多数ありますが、リストに記載している情報以外は、空で構いません。
| 設定名 | 値 | 補足説明 |
|---|---|---|
| 接続アプリケーション名 | Questetra BPM Suite | 任意の値で構いません。 |
| API参照名 | QBPMS | 任意の値で構いませんが、スペースや記号は使えません。 |
| 取引先責任者メール | この設定に関する責任者のメールアドレスを設定してください。 | |
| OAuth 設定の有効化 | チェック | |
| コールバック URL | https://*****.questetra.net/oauth2callback | Questetra BPM Suite の OAuth 2.0 設定に記載されている値をコピーしてください。 |
| 選択した OAuth 範囲 | データへのアクセスと管理(api), ユーザに代わっていつでも要求を実行(refresh_token, offline_access) | この２つを「選択した OAuth 範囲」に加えてください。 |
1-3．Questetra BPM Suite で OAuth 2.0 の設定をする
メッセージ送信中間イベント(HTTP) の「セキュリティ」タブで、「OAuth2.0 で接続する」にある「設定はこちら」ボタンを押すと、OAuth 2.0 の設定画面が開きます。ここで OAuth 2.0 の設定を追加します。
| 設定名 | 値 | 補足説明 |
|---|---|---|
| 名前 | Force.com | メッセージ送信中間イベント(HTTP) で指定した設定名と同じにする必要があります。 |
| 認可エンドポイントUR | https://login.salesforce.com/services/oauth2/authorize | |
| トークンエンドポイントURL | https://login.salesforce.com/services/oauth2/token | |
| スコープ | 空で構いません。 | |
| クライアントID | Salesforce Platform の接続アプリケーションの画面で、「コンシューマ鍵」と表示されているものの値をコピーします。 | |
| クライアントシークレット | Salesforce Platform の接続アプリケーションの画面で、「コンシューマの秘密」と表示されているものの値をコピーします。 |
設定を追加すると、「トークンの取得」ボタンを押して、Salesforce から OAuth2.0 のトークンを取得する処理を、開始します。設定が正しければ、以下のような、Questetra BPM Suite から Salesforce への接続を許可するかどうか確認する画面を経て、処理が完了します。トークンが取得されていると、「トークンの有無」の欄に丸印がつきます。
2．API 応答の解析
スクリプトタスクを使用し、API の応答である JSON テキストを解析します。JSON テキストを解析し、いったん選択型データ項目の選択肢として使用できる状態にします。API の応答は、以下のような形式になっています。
{"totalSize":16,
"done":true,
"records":[
{
"attributes":{
"type":"Account",
"url":"/services/data/v29.0/sobjects/Account/001A0000002wEMkIAM"
},
"Id":"001A0000002wEMkIAM",
"Name":"United Oil & Gas, UK"
},{
"attributes":{
"type":"Account",
"url":"/services/data/v29.0/sobjects/Account/001A0000002wEMlIAM"
},
"Id":"001A0000002wEMlIAM",
"Name":"United Oil & Gas, Singapore"
},{
...
}]
}この応答を、選択型データ項目「顧客データ」の選択肢として構成します。２つの文字型データ項目の値を選択肢として使用する設定になっているので、スクリプトタスクでは、この2つの文字型データ項目に、IDの一覧と顧客名の一覧を格納するようにします。
| 設定名 | 値 | 補足説明 |
|---|---|---|
| 文字型データ項目で選択肢を指定 | ||
| 選択肢ID | 顧客ID一覧 | スクリプトタスクで、ID一覧を保存する文字型データ項目を指定します。 |
| 表示ラベル | 顧客名一覧 | スクリプトタスクで、顧客名一覧を保存する文字型データ項目を指定します。 |
以下がスクリプトタスクのスクリプトです。
var text = engine.findDataByNumber("0");
var result = JSON.parse(text); // JSON 解析
var ids = "";
var labels = "";
for (var i = 0; i < result.records.length; i++) {
var account = result.records[i];
ids += account.Id + "\n"; // ID 取得
labels += account.Name + "\n"; // Name 取得
}
engine.setDataByNumber("2", ids);
engine.setDataByNumber("3", labels);ここまで正常に動作すれば、「確認」タスクにて、「顧客データ」選択型データ項目の選択肢として、Salesforce から取得した顧客データが表示されているはずです。
3．選択肢マスタへの保存
最後に選択肢マスタへ保存する「サービスタスク（選択肢マスタ更新）」の設定です。2 で構成した選択型データ項目を指定します。
| 設定名 | 値 | 補足説明 |
|---|---|---|
| 選択肢マスタを更新するユーザ（要システム管理権限） | (あなた) | このアプリを編集しているユーザ（つまりあなた）にしか変更できません。あなたがもしシステム管理権限を持っていないのであれば、持っているユーザに設定してもらうようにしてください。 |
| 自身の選択肢一覧を「アプリ共有アドオン」として保存する選択型データ項目 | 顧客データ | |
| アプリ共有アドオンに保存する際のファイル名 | 顧客マスタ | 任意の値で構いません。 |
このアプリでプロセスを処理すると、Salesforce Platform の顧客データが、選択肢マスタとして保存されます。保存された選択肢マスタは、アプリ設定以下にある「アプリ共有アドオン」機能から確認することができます。
以上、説明致しましたアプリを添付します。(*) アーカイブには、OAuth2.0 の設定は含まれていないので、この部分は適切に設定する必要があります。また今回使用した API には取得できるデータ件数に上限があります。上限を超えた場合に、続きのデータを取得することもできるのですが、このアプリは対応していません。
(*) 拡張子 zip のファイルがダウンロードされます。拡張子を qar に変更してご利用ください。
（おまけ）選択肢として用いる際に salesforce サイトへ
選択肢マスタとしては、ID と顧客名のみを取り込みましたが、Salesforce にはもっとたくさんのデータが保持されています。したがって処理画面にて顧客を選択した際、他のデータを確認したいということが考えられます。そこで他のデータを確認できるよう、押したらSalesforce の顧客データのページが表示されるボタンを配置します。
選択型のデータ項目１つと、参照ボタンを横に１つ配置しています。この参照ボタンは、ガイドパネルで、HTML を記述しています。選択型のセレクトボックスで顧客を選択し、参照ボタンを押すと、該当する顧客の Salesforce ページが表示されるイメージです。
サンプルアプリの設定について、説明します。タスクが１つだけのアプリなので、プロセス図については省略します。
1. 選択型データ項目
選択型のセレクトボックスを指定してください。
ラジオボタンや検索セレクトボックスでも同じことができますが、次のガイドパネルの内容が若干異なります。ここではセレクトボックスを指定してください。
| 設定名 | 値 | 補足説明 |
|---|---|---|
| 選択肢マスタ（アプリ共有アドオン） | ||
| ファイル名 | 顧客マスタ | Salesforce の顧客データが保存されている顧客マスタを指定してください。 |
2. 参照ボタン
参照ボタンはガイドパネルで構成します。ガイドパネルのデザイン設定で、以下の HTML を指定してください。
<br>
<button onclick="jumpToSalesforce();" type="button">参照</button>
<script type="text/javascript">
function jumpToSalesforce() {
var id = jQuery("select[name='data[0].selects']").val(); // 選択型の値を参照
if (id == '') return;
window.open('https://****.salesforce.com/' + id); // Salesforce のページを開く
}
</script>ポイントは “jumpToSalesforce()” という関数を定義している Javascript です。この中で選択型の値を参照し、Salesforce のページを開いています。こんなことができるのは、
https://****.salesforce.com/(ID)
という URL で、該当データが参照できるように、Salesforce が作られているからです。当然のことながら、Salesforce にアカウントがなければ、データを参照することはできません。
説明内容に沿ったアプリを添付します。2 の javascript にあるSalesforce のURL
https://****.salesforce.com/(ID)
の **** の部分は、Salesforce を利用している組織によって異なるので、適切なものに変更してください。
いかがでしたでしょうか。 Salesforce の顧客データを選択肢として利用する際の、ちょっとした Tips について紹介しました。データの ID がわかっていれば、Salesforce の API 経由で、顧客名以外のデータを取得し、Questetra BPM Suite のデータ項目にコピーすることも可能です。またの機会に紹介したいと思います。
ピンバック: Questetra から他サービスの REST API を呼び出す場合の設定（Questetra が OAuth2 クライアントになる場合） – Questetra Support
ピンバック: Salesforce アクセス専用プロセス – Questetra Support