今回はBox Webhook関連のアドオン3種について、指定フォルダへのファイルアップロードを監視するサンプルアプリをもとにご紹介します。


Box Webhookとは

Boxでは、フォルダやファイルに対してWebhookを設定できます。Webhookは対象のファイル/フォルダに対して指定された操作(プレビュー・ダウンロード・削除など)が行われたとき、その操作に関する情報を指定したURLへ送信します。送信された情報は様々なアプリで受信し、活用することができます(Questetra BPM Suiteでももちろん受信可能です)。

フォルダ・ファイル単位でのWebhookの設定は通常コマンドラインやスクリプトなどを用いて行いますが、Questetraではアドオンを使ってフォルダに対してWebhookを作成したり、削除することができます。


アドオンについての説明

今回説明するBox Webhook関連のアドオンは以下の3種類です。

BoxのWebhookを作成(フォルダの監視)

ダウンロードページはこちら

作成アドオンの設定画面

Box上のフォルダに対してWebhookを作成します。Webhookのトリガーは任意に設定可能です(トリガーの種類についてはBoxの公式ドキュメントをご覧ください)。

作成したWebhookに関する情報は実行結果の「自動処理ログ」に出力されます。

BoxのWebhookを削除

ダウンロードページはこちら

削除アドオンの設定画面

Box上のフォルダに対して設定されているWebhookを削除します。

BoxのWebhookのJSONを解析

ダウンロードページはこちら

解析アドオンの設定画面

設定したWebhookによって送られてくるJSONオブジェクトを解析し、イベントに関する情報を対応するデータ項目に保存します。

これら3種のアドオンを使用するにはOAuth2.0の設定、およびアドオンのアプリへのインポートが必要です。以下に示す方法で設定してください。


Box OAuth2.0の設定

Box側の設定

まず、Box Developerアカウントを作成し、アプリを作成しましょう。

Box Developersのコンソールで、「アプリの新規作成」をクリックし、その先のメニューで「カスタムアプリ」を選択します。

次の画面で「認証方法」を選ぶよう求められるので、「標準OAuth2.0(ユーザー認証)」を選びます。

あとは好きな名前をつければアプリの作成は完了です。「アプリの表示」をクリックしてください。

作成できたら、「構成」タブで以下の設定を行います。

  1. 「クライアントID」「クライアント機密コード」をメモしておく(後で使います)。
  2. 「OAuth 2.0リダイレクトURI」に、QuestetraのOAuth2.0設定ページにあるコールバックURL(下の画像2を参照)を入力する。
  3. 「アプリケーションスコープ」の項にある「Webhookを管理」のチェックボックスをオンにする。
画像1:Boxアプリの設定画面
画像2:コールバックURL

 

※コールバックURLは使用している環境によって異なるので、上の画像2に示されているものではなく実際のアプリの画面にあるものを使うようにしてください。

Questetra側の設定

次に、Questetraに移動し、アプリのOAuth2.0設定画面(上の画像2の画面)を開いて、「追加」をクリックします。

開いた画面で以下のように設定します。

項目 設定内容
名前 わかりやすい名前をつける(アドオンが認証情報を得るときに使います)
認可エンドポイントURL https://account.box.com/api/oauth2/authorize
トークンエンドポイントURL https://api.box.com/oauth2/token
スコープ 空欄のまま
クライアントID・クライアントシークレット Boxの「構成」タブに示されているものを入力(クライアントシークレットは「クライアント機密コード」を入力します)

最後に「トークンを取得」を押し、Webhookを設定するフォルダのあるアカウントでログインしてトークンを取得します。これで設定は完了です。

アドオンを使用するときは、設定時につけた名前をアドオンの「C1.OAuth設定名」に入力してください。


アドオンのインポート

まず、それぞれのアドオンをダウンロードしてください。ダウンロードページヘのリンクは上の「アドオンについての説明」部にあります。

次に、アプリの詳細画面から「アドオンの管理」を開きます。

アプリ設定画面のメニュー

開いたら「サービスタスク定義ファイル (ベータ版)」に切り替えて、「追加」をクリックします。

アドオン管理画面

ファイルを選択」からダウンロードしたアドオンを選択し、「追加」をクリックすると追加されます。「名前」「コメント」は必要に応じて編集してください。


サンプルアプリ

これらのアドオンを使って作成したサンプルアプリがこちらです。

サンプルアプリのフロー図

このアプリは「作成・削除」部(上部)と「受信・解析」部(下部)に分かれています。見た目には途中でつながっているように見えますが、これは Questetra BPM Suiteの仕様上、つながっていなければエラーとなるためで、実際にはトークンが2つのスイムレーンをまたいで動くことはありません。

データ項目は以下の通りです。

データ項目 タイプ 必須 「Webhook削除の設定」 データ項目の説明
件名 編集可 プロセスの件名です。
「作成・削除」部で使うもの
Webhookを指定時間に削除する? 選択型(ラジオボタン) 編集可 Webhookを削除するか否かを選択・判定するのに使います。
設定

選択肢ID 表示ラベル 初期値
true はい
false いいえ
Webhook削除日時 日時型 編集可 Webhookを削除する場合、いつ削除するのかを設定します。
初期値

processInstanceStartDatetime.addDays(1)
Webhook ID 文字列型(単一行) 非表示 「作成」アドオンがWebhookのIDを保存し、「削除」アドオンが読み込みます。
「受信・解析」部で使うもの
JSON 文字列型(複数行) 非表示 Box から送信されてきたJSONオブジェクトを保存します。
イベント発生日時 日時型 非表示 JSON オブジェクトから抜き出したイベント発生日時を保存します。
ユーザー名 文字列型(単一行) 非表示 JSON オブジェクトから抜き出したユーザー名を保存します。
ファイルID 文字列型(単一行) 非表示 JSON オブジェクトから抜き出したファイルIDを保存します。
ファイル名 文字列型(単一行) 非表示 JSON オブジェクトから抜き出したファイル名を保存します。
上位フォルダの名前 文字列型(複数行) 非表示 JSON オブジェクトから抜き出した上位フォルダの名前を保存します。
親フォルダの名前 文字列型(単一行) 非表示 「上位フォルダの名前」から抽出した親フォルダの名前を保存します。
親フォルダは何階層目か? 数値型 非表示 「上位フォルダの名前」の中で親フォルダが何階層目にあるのかを数値として保存します。

 


Webhookを作成・削除する

「作成・削除」部のフロー図

「作成・削除」部では、Webhookの作成と削除を行います。まず、最初の「Webhook削除の設定」工程で「作成するWebhookを自動的に削除するか否か」と、削除する場合は「削除する時間」を設定します。

「Webhook削除の設定」工程

「作成」アドオンの設定

「Webhook削除の設定」工程を完了すると、「作成」アドオンによりWebhookの作成が行われます。

「作成」アドオンで設定する項目は以下のとおりです。

項目名 形式 必須 説明
C1:OAuth設定名 設定時に直接入力(単一行) OAuth2.0の設定(先述)のとき設定した名前を指定します。
C2:フォルダID(数字) 設定時に直接入力(単一行) Webhookを設定する先となるフォルダをIDで指定します。数字以外が入力された場合エラーとなります。フォルダのIDはフォルダの表示URLに含まれています。https://app.box.com/folder/1111xxxx というURLのフォルダなら「1111xxxx」がIDです。
C3:Webhook URL(https:) 設定時に直接入力(単一行) Webhookが情報を送信する先となるURLを指定します。”https:”から始まるもの以外はエラーとなります。今回は「受信・解析」部のメッセージ開始イベント(Webhook)の受信URLを入力します。
C4:Webhookのトリガー(1行につき1つ) 設定時に直接入力(複数行) 設定するWebhookのトリガーを指定します。複数個設定する場合は1行につき1つのトリガーを書くようにしてください。今回は「指定フォルダへのファイルのアップロード」に対応するトリガー(FILE.UPLOADED)のみを指定します。
O1:Webhook IDの出力先(指定:単一行文字型データ) 単一行文字型データを指定 作成したWebhookのIDを出力するデータ項目を指定します。今回は「Webhook ID」を使います。

XOR ゲートウェイの設定

次の分岐点では、「Webhookを指定時間に削除する?」の値によって分岐します。分岐タイプは「XOR」、「遷移先の決定」は以下のように設定します。

条件名 条件式 遷移先
削除する Webhookを指定時間に削除する? = true(はい) タイマー
削除しない Webhookを指定時間に削除する? = false(いいえ) 合流
デフォルトフロー 無条件に推移 ダミー

最後の「デフォルトフロー」はあくまでダミーで、こちらに分岐することはありません(必須設定をしてあるため、「Webhookを指定時間に削除する?」は必ずtrueかfalseのどちらかになっています)。

「削除」部分の設定

「Webhookを指定時間に削除する?」がtrueの場合(つまり、最初に削除を設定していた場合)、次はタイマー中間イベントで指定時間まで待機した後、削除を行います。

タイマー中間イベントの設定画面

タイマー中間イベントは、今回は「データで指定された日時」を選び、「Webhook削除日時」を指定します。これで、「Webhook削除の設定」工程で設定した時間に削除を行えます。

「削除」アドオンで設定する項目は以下のとおりです。

項目名 形式 必須 説明
C1:OAuth設定名 設定時に直接入力(単一行) OAuth2.0の設定(先述)のとき設定した名前を指定します。
I1:Webhook ID(指定:単一行文字型データ) 単一行文字型データを指定 削除する対象となるWebhookのIDの入っているデータ項目を指定します。今回は「Webhook ID」を使います。

削除には対象となるWebhookのIDが必要ですが、「作成」のアドオンは作成したWebhookのIDをデータ項目に保存するので、今回はそれを使用します。

「Webhookを指定時間に削除する?」がfalseの場合(つまり、最初に削除を設定しなかった場合)は、削除は行わず、そのまま終了します。

 


Webhookを受信・解析する

「受信・解析」部のフロー図

「受信・解析」部の処理は、「メッセージ開始イベント(Webhook)」がWebhookによって送られてくるJSONオブジェクトを受信することで始まります。「受信・解析」部では、開始から終了まで、全ての処理が自動的に行われます

メッセージ開始イベント(Webhook)の設定

最初の「メッセージ開始イベント(Webhook)」の設定は以下のようにしましょう。

項目 設定内容
受信するHTTPリクエストのContent-Type 「application/json」にします。
リクエストボディ保存先の文字型データ項目 今回は「JSON」を使います。

また、Box からの HTTP リクエストを受信できる状態になっているかの確認も必要です。

まず、アプリの詳細画面のトップで、表示を最新バージョンのものに切り替えます。(最新)と書かれたバージョンの「詳細」をクリックしてください。

切り替わったら、下の「ワークフロー図」の中にある「メッセージ開始イベント(Webhook)」をクリックし、「リクエスト」タブにある「詳細」をクリックしてください。

クリックして表示されたページで、IP アドレス制限を確認します。

「接続が許可されているネットワーク」の部分に「0.0.0.0/0」とある場合はHTTPリクエストの受信が可能です。

受信可能な場合の設定

そうでない場合(「外部ネットワークからの接続は禁止されています。」と表示される場合など)は受信できません。受信できない場合は、こちらのページ を参考に、IP アドレス制限を緩和してください。Boxの仕様上、「すべてのIPアドレスからの通信を許可する」ことになりますが、そのように設定するのはこのアプリ(あるいはノード)限定にするほうが望ましいです。

「解析」アドオンの設定と結果

「解析」のアドオンは受信したオブジェクトを解析し、データ項目に情報を入れます。(アプリの設定によって、一部のみをデータ項目に入れるようにすることもできます)。

「解析」アドオンで設定する項目は以下のとおりです。

項目名 形式 必須 説明
I1.Webhookで送られてきたJSONオブジェクト(指定:複数行文字型データ) 複数行文字型データを指定 解析対象となるJSONオブジェクトの入っているデータ項目を指定します。今回は「JSON」を使います。
O1.イベント発生時刻(指定:日時型データ) 日時型データを指定 「イベントが発生した日時」の保存先のデータ項目を指定します。今回は「イベント発生日時」を使います。
O2.イベントを起こしたユーザ(指定:単一行文字型データ)  単一行文字型データを指定 「イベントを起こしたユーザ」の保存先のデータ項目を指定します。今回は「ユーザー名」を使います。
O3.トリガー(指定:単一行文字型データ)  単一行文字型データを指定 「トリガー」の保存先のデータ項目を指定します。今回は使いません。
O4.対象となるファイル・フォルダのID(指定:単一行文字型データ)  単一行文字型データを指定 「イベントの対象となるファイル・フォルダのID」の保存先のデータ項目を指定します。今回は「ファイルID」を使います。
O5.対象となるファイル・フォルダの名前(指定:単一行文字型データ)  単一行文字型データを指定 「イベントの対象となるファイル・フォルダの名前」の保存先のデータ項目を指定します。今回は「ファイル名」を使います。
O6.全ての上位フォルダのID(指定:複数行文字型データ) 複数行文字型データを指定 「対象ファイル・フォルダより上位のフォルダ全てのID」の保存先のデータ項目を指定します。今回は使いません。
O7.全ての上位フォルダの名前(指定:複数行文字型データ) 複数行文字型データを指定 「対象ファイル・フォルダより上位のフォルダ全ての名前」の保存先のデータ項目を指定します。今回は「上位フォルダの名前」を使います。

「解析」のアドオンでは、「I1.Webhookで送られてきたJSONオブジェクト」以外は必ずしも設定する必要はありません。その時々で必要なものを使いましょう。今回のサンプルでも「トリガー」と「全ての上位フォルダのID」は使っていません。

解析を行うと、以下のような形でデータ項目に保存されます。

解析結果が保存されたデータ項目

親フォルダ名抽出の設定

このとき、「上位フォルダに~」のものは上から階層順になっている、つまり「一番最後の行がWebhookを設定したフォルダになっている」ことを活かして、Webhookを設定したフォルダの名前を抜き出せます。

まず、「上位フォルダの名前」の行数を数えます。そしてその行数を使って、最後の行を抜き出します。この作業にはそれぞれアドオン「行数カウンター」「指定行抽出」を使います。

まず「行数カウンター」で「上位フォルダの名前」の行数を計測し、「親フォルダは何階層目か?」に格納します。

そして「指定行抽出」で、「上位フォルダの名前」から「親フォルダは何階層目か?」に格納されている番号の行(つまり、一番最後の行)を抽出し、「親フォルダの名前」に格納します。

行数カウンターアドオンの設定
指定行抽出アドオンの設定

オープンチャット投稿の設定

そして、解析によって得られた情報と、「親フォルダの名前」に入っているフォルダの名前を使って情報をオープンチャットへ投稿します(今回はEL式を使うために、古いバージョンのアドオンを使っています)。

オープンチャットに投稿するアドオンの設定画面

「A」について。「組織ID」は各組織に割り振られている固有の数字で、「1」はルート組織(参加者全体)を指します。

「B」について。EL式(「#{data[‘2’]}」などがそれです)を使うことでデータ項目に入っているデータをメッセージに挿入できます。ここで、それぞれの式に入っている数字はデータ項目の番号になっています。今回は使っているのは以下の5つです。

項目 EL式
イベント発生日時 #{data[‘2’]}
ユーザー名 #{data[‘1]}
親フォルダの名前 #{data[’11’]}
ファイル名 #{data[‘5’]}
ファイルID #{data[‘4’]}

Boxでは各ファイルのURLが「https://app.box.com/file/(ファイルID)」という形になっているので、「https://app.box.com/file/#{data[‘4’]}」という形で投稿することで、対象となるファイルのURLにすることが出来ます。ただし、このURLでアクセスできるのはファイルの所有者、ならびに招待されて閲覧権限を持っている人だけですので、実際の使用時にはその点を投稿に書いておいたほうが良いかもしれません。

このように設定すると、実際の投稿は以下のようになります。

オープンチャット投稿のサンプル

今回はアップロードのみの監視なのでこのようなメッセージですが、実際に使用する場合はセットするトリガーに応じてうまいメッセージを考えるとよいでしょう(上述した通りトリガーも解析で得られる情報の中に入っていますので、複数のトリガーを処理することもできるでしょう)。

少々長くなりましたが、今回は以上で終わりです。