Box Webhookを使ってフォルダへのアップロードを監視する

今回は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を管理」のチェックボックスをオンにする。

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

Questetra側の設定

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

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

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

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

アドオンのインポート

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

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

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

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

サンプルアプリ

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

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

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

processInstanceStartDatetime.addDays(1)

Webhookを作成・削除する

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

「作成」アドオンの設定

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

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

XOR ゲートウェイの設定

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

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

「削除」部分の設定

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

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

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

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

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

Webhookを受信・解析する

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

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

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

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

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

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

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

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

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

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

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

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

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

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

親フォルダ名抽出の設定

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

まず、「上位フォルダの名前」の行数を数えます。そしてその行数を使って、最後の行を抜き出します。この作業にはそれぞれアドオン「複数行文字列, 行数の取得」「複数行文字列, 特定行の取得」を使います。

まず「複数行文字列, 行数の取得」で「上位フォルダの名前」の行数を計測し、「親フォルダは何階層目か？」に格納します。

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

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

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

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

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

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

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

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

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