クエステトラユーザのみなさん、こんにちは。開発責任者の畠中です。
今回は以下のブログの続きです。
このブログでは、Twilio への API リクエストを、メッセージ送信中間イベント (HTTP) からスクリプトタスクに変更しました。
Queststra BPM Suite では、スクリプトタスクで行っている処理を、独自の自動工程として抜き出すことができます。今回、Twilio の API を使って SMS 送信する処理部分を、独自の自動工程として抜き出したいと思います。作り出した自動工程は、他のワークフローアプリで再利用することができます。
ワークフロー図は、最終的に以下のように変わります。独自の自動工程になります。
まず自動工程の設定項目を考えたいと思います。設定に応じて、SMS 送信先や本文を変えられる方が、使い勝手の良いものになります。設定画面としては、このようなものを目指したいと思います。
設定項目としては、
- C1. アカウント SID
- C2. AUTH TOKEN
- C3. 送信用の電話番号
- I1. 送信先の電話番号
- I2. SMS 本文
となります。「処理失敗時に、トークンをエラー境界イベントに移動」という設定項目もありますが、これは標準でつく設定項目で、コントロールできないものです。
この自動工程を実現するための、定義ファイルは以下の通りです。
以降、個別に説明していきたいと思います。
1. 自動工程の種類名
定義ファイルは XML 形式で、<service-task-definition>で囲みます。<engine-type> は “2”、 <last-modified> は作成日を YYYY-MM-DD 形式で指定してください。
<?xml version="1.0" encoding="UTF-8"?>
<service-task-definition>
<engine-type>2</engine-type>
<last-modified>2018-07-24</last-modified>
<label>Sending SMS by Twilio</label>
<label locale="ja">SMS 送信 by Twilio</label>
...
</service-task-definition><label> は自動工程の種類名となり、設定ダイアログのタイトルとして表示されます。Questetra BPM Suite は多言語対応していますので、日本語環境の場合は locale="ja" のものが表示されます。他に “en” “de” “es” などがあります。現在の設定の場合、日本語の時だけ「SMS 送信 by Twilio」と表示され、それ以外の言語の場合は “Sending SMS by Twilio” と表示されます。
2. 設定項目
<configs> 内の <config> は、設定ダイアログでの１つ１つの設定項目に対応しています。この設定によって、先程のような設定項目が表示されています。
<configs>
<config name="AccountSid" required="true">
<label>C1. ACCOUNT SID</label>
<label locale="ja">C1. アカウント SID</label>
</config>
<config name="AuthToken" required="true">
<label>C2. AUTH TOKEN</label>
</config>
<config name="From" required="true">
<label>C3. From Telephone Number (You got at Twilio) ex. +180XXXXXXXX</label>
<label locale="ja">C3. 送信用の電話番号 ex. +180XXXXXXXX</label>
</config>
<config name="To" form-type="SELECT" select-data-type="STRING_TEXTFIELD" required="true">
<label>I1. To Telephone Number (Data: Singlie-line String)</label>
<label locale="ja">I1. 送信先の電話番号 (指定: 単一行文字型データ)</label>
</config>
<config name="Message" form-type="SELECT" select-data-type="STRING" required="true">
<label>I2. SMS body (Data: String)</label>
<label locale="ja">I2. SMS 本文 (指定: 文字型データ)</label>
</config>
</configs><config> 内の<label> は、設定項目のラベルを表しています。これも多言語対応しています。
name 属性で、項目名を指定しています。これはスクリプトから設定値を参照するのに使用します。後で登場します。
form-type 属性で、設定項目の入力タイプを指定します。指定がない場合は、「テキストフィールド」です。”SELECT” は、ワークフローアプリのデータ項目の中から、１つ選択させる入力タイプです。select-data-type 属性で、選択対象のデータ項目のタイプを指定します。”STRING_TEXTFIELD” は単一行文字タイプのデータ項目の中から１つ、”STRING” は単一行／複数行問わず、文字タイプのデータ項目の中から１つ選択させることを表します。「I1. 送信先の電話番号」は、ワークフローアプリ内の単一行文字型データ項目から１つ選択させることになります。
required 属性で、設定項目が必須かどうか指定します。ワークフローアプリの開発時に、required="true" の設定項目が空の場合、バリデーションエラーとなります。必ず入力させることができるようになります。この自動工程では、5 つの設定項目全てが必須であり、どれも空となることを許していないことになります。
これらの設定で、先のダイアログのような設定項目が表示されるようになります。
3. スクリプトとアイコン
<script> タグは、自動工程で行われる処理をスクリプトで記述しています。ここでは、main() 関数を定義し、その main() 関数を呼び出すという構造にしています。<script> タグは、定義ファイル内に必ず必要です。スクリプトの内容は、後で詳しく説明します。
<icon> タグは、ワークフロー図上での該当アイテムの右下に表示されるアイコンを指定しています。ない場合、アイコンは表示されません。<icon> タグ内には、画像データを Base64 エンコードしたテキストを指定しています。JPEG / GIF / PNG で、64 x 64 以下のサイズのみに対応しています。
<script><![CDATA[
main();
function main(){
...
}
]]></script>
<icon>iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAAAXNSR0IArs4c6QAAAARnQU1BAACx
...
uePkzUgCK3dpZumzf46+87b5uTkP4D50skW/Mt0AAAAAElFTkSuQmCC</icon>4. スクリプトの詳細
<script> タグの中、main() 関数の中身について説明します。前半部分についてです。
const accountSID = configs.get("AccountSid");
const authToken = configs.get("AuthToken");
const fromPhone = configs.get("From");
const apiUrl = 'https://api.twilio.com/2010-04-01/Accounts/' + accountSID + '/Messages.json';
const toPhone = engine.findDataByNumber(configs.get("To"));
const message = engine.findDataByNumber(configs.get("Message"));
configs.get(...) で、先の設定項目に設定された値を取得します。引数には、<config> タグの name 属性の値を指定します。「C1. アカウント SID」「C2. AUTH TOKEN」「C3. 送信用の電話番号」の設定値を、”AccountSid” “AuthToken” “From” という項目名を使って、順に取得しています。
画面ダンプでは、設定に ${var[AccountSID]} といった変数が使用されています。スクリプトには、展開後の値で渡されてきます。スクリプトで変数を意識する必要はありません。
engine.findDataByNumber() は、番号でデータ項目を検索し、そのデータ項目内の値を返す関数です。form-type="SELECT" の設定項目には、設定されたデータ項目の番号が入っています。したがって engine.findDataByNumber(configs.get(...)); の形で、設定されたデータ項目の値を取得することができます。この自動工程では、「I1. 送信先の電話番号」「I2. SMS 本文」で設定されたデータ項目の値を、順に取得しています。
スクリプトの後半については、以前のブログの内容と同じになります。設定された値を使用し、Twilio の API にアクセスして SMS を送信します。API のレスポンスで、成否を把握しています。詳細は、以前のブログを参照してもらえればと思います。
const apiRes = httpClient.begin()
.basic(accountSID, authToken)
.formParam('From', fromPhone)
.formParam('To', toPhone)
.formParam('Body', message)
.post(apiUrl);
const responseCode = apiRes.getStatusCode();
const responseBody = apiRes.getResponseAsString();
engine.log("response: " + responseCode);
engine.log(responseBody);
if (responseCode != 201) {
throw "response is not 201: " + responseCode;
}
5. 定義ファイルの登録とワークフローアプリでの使用
作成した定義ファイルを、Questetra BPM Suite に登録すると、登録した自動工程を使ったワークフローアプリを作成することができるようになります。登録はアプリ詳細ページの「アプリ」のプルダウンメニューから、「アドオンの管理」の先で行います。
登録に成功すると、モデラにて、ワークフロー図のパレットで表示されるようになります。
２段め一番左のものが、今回登録したものです。これを使用し、スクリプトタスクを置き換えて、以下のようなワークフロー図にしてください。画面ダンプでは、他に登録したものが２つ表示されています。後は、置き換えた自動工程の設定をすれば完成です。
この機能を利用すれば、自動処理の再利用性が高まります。またスクリプトタスクで記述している、スクリプト処理を隠蔽することができるメリットもあります。機会があれば、利用してもらえればと思います。
今回は以上です。それではまた。