Questetra BPM Suite の外からケースを開始する(GitHub 編)

この連載では、これまで「こちらから送る」側を自分で書いてきました。curl のコマンドも、Python のスクリプトも、Google Apps Script も、パラメータの名前をデータ項目のフィールド名に合わせて書けます。

外部サービスからの通知は違います。何が起きたかを知らせてくるのは相手で、送る内容の形式も相手が決めています。

この記事では、GitHub でリリースを公開したときに GitHub が送る通知 (Webhook) を受けて、告知のケースを開始します。[メッセージ開始イベント (Webhook)]でリクエストボディをそのまま受け取り、[スクリプトタスク]で解析する、という流れです。

[メッセージ開始イベント (HTTP)]では受けられない理由

[メッセージ開始イベント (HTTP)]が受け付けるのは POST で、Content-Type は application/x-www-form-urlencoded と multipart/form-data です。データ項目に値を入れるパラメータの名前は、データ項目のフィールド名そのもの(q_ で始まる名前)と決まっています。

GitHub の Webhook は、送るときの Content-Type を 2 つから選べます。

  • application/json — JSON をそのままリクエストボディとして送ります
  • application/x-www-form-urlencoded — 同じ JSON を payload という名前のパラメータの値として送ります

前者は Content-Type が合いません。後者は Content-Type は合いますが、パラメータの名前が payload の 1 つで、q_ で始まる名前にはなりません。値も JSON の文字列そのものです。名前も形も GitHub が決めているので、こちらでは変えられません。

[メッセージ開始イベント (Webhook)]は、リクエストボディを解釈せずに、そのまま 1 つのデータ項目に保存します。中身がどういう構造であっても受け取れます。

[メッセージ開始イベント (HTTP)][メッセージ開始イベント (Webhook)]
受け付ける Content-Typeapplication/x-www-form-urlencoded、multipart/form-data設定で指定する。候補として application/json、text/xml、application/x-www-form-urlencoded が表示され、それ以外を直接入力することもできる
受け付ける HTTP メソッドPOSTGET・POST・PUT・PATCH・DELETE から選ぶ
データ項目への入り方q_ で始まるパラメータごとに、対応するデータ項目へ入るリクエストボディをまるごと 1 つのデータ項目に保存する
保存された値からの取り出し不要[スクリプトタスク]で解析する
応答ケース ID をテキストで返す(固定)[HTTP レスポンスの内容]に書いた本文を返せる

送る側を自分で書けるのであれば、[メッセージ開始イベント (HTTP)]の方が手数は少なくて済みます。解析の工程が要らず、値が直接データ項目に入ります。

作るワークフローアプリ

「リリース告知」という練習用のワークフローアプリを作ります。工程は次のとおりです。

  • [メッセージ開始イベント (Webhook)]「GitHub からの通知の受信」
  • [スクリプトタスク]「通知の解析」
  • [データ更新]「件名の設定」
  • [分岐 XOR ゲートウェイ]「公開の通知かどうか」
  • [ヒューマンタスク]「告知文の作成」
  • [終了イベント]「告知済み」
  • [終了イベント]「対象外」

[分岐 XOR ゲートウェイ]「公開の通知かどうか」からは 2 本に分かれます。公開の通知であれば[ヒューマンタスク]「告知文の作成」へ、既定の[その他]の経路は[終了イベント]「対象外」へ直接つなぎます。[ヒューマンタスク]「告知文の作成」の後は[終了イベント]「告知済み」です。

終了イベントは 2 つ置きます。終了イベントにつなげられるフローは 1 本だけなので、経路が分かれたまま終わる場合は、経路ごとに終了イベントを置きます。終了イベントに経路の名前を付けておけば、どの経路で終わったかがケースの図から読めます。

データ項目は次の 8 つです。右の列は、[ヒューマンタスク]「告知文の作成」での編集の可否です。[メッセージ開始イベント (Webhook)]には、データ項目ごとに編集の可否を設定する項目がありません。

フィールド名データ項目名データタイプ告知文の作成
q_webhook_body受信ボディ文字 (複数行)表示のみ
q_action通知の種類文字 (単一行)表示のみ
q_repositoryリポジトリ文字 (単一行)表示のみ
q_tag_nameタグ名文字 (単一行)表示のみ
q_release_nameリリース名文字 (単一行)表示のみ
q_release_urlリリースページ URL文字 (単一行)表示のみ
q_release_bodyリリースノート文字 (複数行)表示のみ
q_announcement告知文文字 (複数行)編集可

「受信ボディ」(q_webhook_body)は、受信したリクエストボディの書き込み先です。次の節で、工程のプロパティの[リクエストボディ保存先のデータ項目]に指定します。q_action から q_release_body までの 6 つを書き込むのは[スクリプトタスク]「通知の解析」です。「告知文」(q_announcement)は、[ヒューマンタスク]「告知文の作成」で処理担当者が入力する欄です。

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

工程のプロパティ画面で、次を設定します。

  • API キー:半角英数のみ、最大 100 文字で設定します。[キーを自動生成]でも作れます
  • 受信する HTTP リクエストのメソッド:POST
  • 受信する HTTP リクエストの Content-Type:application/json
  • リクエストボディ保存先のデータ項目:q_webhook_body

リクエストボディの保存先に指定できるのは、文字 (複数行) または文字 (Markdown) のデータ項目です。

受信 URL は、この工程のプロパティ画面に表示されます。次の形式で、API キーは URL のパスに含まれます。GitHub 側に登録するのはこの URL です。

https://(ワークフロー基盤のドメイン)/System/Event/MessageStartHttp/(アプリ ID)/(工程番号)/(API キー)/start

応答の内容

前の節と同じ[メッセージ開始イベント (Webhook)]のプロパティ画面で、GitHub へ返す本文を設定します。

  • HTTP レスポンスの Content-Type:application/json;charset=UTF-8
  • HTTP レスポンスの内容:下記
{
  "caseId": "#{processInstanceId}"
}

GitHub はこの応答の中身を使いませんが、後述する配信の記録に残ります。ケース ID を返しておくと、どの配信がどのケースになったかを突き合わせられます。

アクセス元の IP アドレス制限

受信 URL は IP アドレス制限の対象です。Questetra BPM Suite は、初期状態では[メッセージ開始イベント (Webhook)]あての HTTP リクエストを外部からすべて拒否します。許可は[システム設定]>[IPアドレス制限]で登録します。この設定を行えるのはシステム管理権限を持つアカウントです。ワークフローアプリを作成できる権限とは別なので、権限がない場合はシステム管理者に依頼します。

登録するのは[メッセージ開始イベント/受信タスク設定]の 1 行です。

  • [パスプレフィックス]— 選択肢[メッセージ開始イベント (Webhook) – 特定ノード]を選び、括弧で示された部分を受信 URL のアプリ ID と工程番号に置き換えます。許可するのはこの工程だけにし、全アプリや特定アプリの単位では許可しないでください
  • [接続が許可されているネットワーク]— 次に説明する GitHub の送信元の範囲

GitHub は Webhook の送信元 IP アドレスの範囲を API で公開していて、https://api.github.com/meta の応答に含まれる hooks がそれにあたります。IPv4 と IPv6 の両方が並んでいますが、IP アドレス制限が対応しているのは IPv4 だけなので、IPv4 の範囲を登録します。

ただし、この範囲は変わることがあります。変わったあとも古い範囲のままにしておくと、通知が拒否されるようになります。範囲を確認して更新する運用を決めておいてください。

届く通知の種類

Webhook を登録した時点で、GitHub は ping という通知を 1 回送ります。 登録できたことを知らせるためのもので、リリースの通知ではありません。この 1 件でもケースが開始されます。

公開以外の通知も届きます。 リリースの通知には action という項目があり、published(公開)のほかに created、edited、deleted、prereleased、released、unpublished があります。GitHub の設定画面で選べるのはイベントの種類([Releases])までで、action の値までは絞り込めません。

1 回の公開で、通知は 1 件ではありません。 リリースを下書きにせず直接公開すると、created、published、released の 3 件が届き、ケースも 3 件開始されます。下書きを保存してから公開した場合は、下書き保存の時点で created が届き、公開の時点で published と released の 2 件が届きます。プレリリースとして公開した場合は released の代わりに prereleased が届き、released はプレリリースを正式なリリースに変更したときに届きます。

どの経路でも、公開の時点で published は 1 件だけ届きます。この記事で published を選り分けの条件にしているのはそのためです。

つまり、届いたリクエストの数だけケースが開始されます。 選り分けは Questetra BPM Suite 側で行います。この記事では、解析した action の値を[分岐 XOR ゲートウェイ]で見て、published 以外は[ヒューマンタスク]を通さずに[終了イベント]「対象外」へ流します。

対象外の通知でも、ケースそのものは 1 件ずつ残ります。ケース一覧で見分けられるように、「件名の設定」の節で件名を付けます。

受け取った JSON の解析

保存された JSON から値を取り出すには[スクリプトタスク]が必要です。SpEL 式には JSON を解析する機能がありません。

[スクリプトタスク]に次のスクリプトを設定します。q_webhook_body を読み、q_action から q_release_body までの 6 つのデータ項目に書き込みます。

function pick(obj, key) {
  if (obj === undefined || obj === null) {
    return '';
  }
  const value = obj[key];
  if (value === undefined || value === null) {
    return '';
  }
  return String(value);
}

const body = engine.findDataByVarName('q_webhook_body');
let json;
try {
  json = JSON.parse(body);
} catch (e) {
  json = {};
}
if (json === null || typeof json !== 'object') {
  json = {};
}

let action = pick(json, 'action');
if (action === '' && pick(json, 'zen') !== '') {
  action = 'ping';
}

engine.setDataByVarName('q_action', action);
engine.setDataByVarName('q_repository', pick(json.repository, 'full_name'));
engine.setDataByVarName('q_tag_name', pick(json.release, 'tag_name'));
engine.setDataByVarName('q_release_name', pick(json.release, 'name'));
engine.setDataByVarName('q_release_url', pick(json.release, 'html_url'));
engine.setDataByVarName('q_release_body', pick(json.release, 'body'));

キーがない場合に備えています。 ping の通知には action も release もありません。値の有無を確かめずに json.release.tag_name と書くと、release が無い時点でスクリプトの実行が止まります。止まるのはスクリプトの実行だけで、トークンはこの工程に留まらず、次の工程へ進みます。 エラーになった実行ではデータ項目への代入がひとつも反映されません。 途中まで書き込まれた状態にはならず、スクリプトが書き込む 6 つのデータ項目がすべて空のままのケースができます。「受信ボディ」(q_webhook_body)には、受信した内容がそのまま残ります。

スクリプトの先頭で定義している pick は、これを避けるための関数です。pick(json.release, 'tag_name') のように、オブジェクトとキーの名前を渡して使います。渡したオブジェクトが無い場合も、そのキーが無い場合も、空文字列を返すので、release が無い ping の通知でも実行は止まりません。

ping の通知には zen という項目があります。action が無く zen がある場合を ping とみなして、q_action に ping と入れています。

JSON.parse を try で囲んでいるのは、JSON として解釈できない内容が届いた場合に、スクリプトをエラーで終わらせないためです。この場合 q_action は空のままになり、公開の通知としては扱われません。空のリクエストボディや、オブジェクトではない JSON が届いた場合も同じです。

受信したリクエストボディは q_webhook_body にそのまま残ります。GitHub が送る内容の構造が変わって解析が合わなくなったときに、何が届いていたのかを後から確認できます。

件名の設定

[データ更新]「件名の設定」で、ケースの件名を設定します。設定対象に[件名]を選び、次の式を設定します。

#{#q_action == 'published' ? 'リリース公開' : '対象外'}(#{#q_action}) #{#q_repository} #{#q_tag_name}

published の通知であれば「リリース公開(published) yourname/your-repo v1.2.0」、ping の通知であれば「対象外(ping) yourname/your-repo」という件名になります。

処理しないケースは、件名でそれと分かるようにしておきます。 1 回の公開で複数のケースが開始されるので、件名が同じだと、どれが告知に進んだケースなのかをケース一覧から判断できません。

件名を付ける[データ更新]「件名の設定」は[分岐 XOR ゲートウェイ]「公開の通知かどうか」より前にあり、この時点では経路がまだ分かれていません。そのため、件名の式の中でも q_action を見て、公開の通知かどうかで書き分けます。式のうち条件で分かれるのは先頭だけで、あとはデータ項目をそのまま並べています。

yourname/your-repo の部分には、リポジトリの所有者とリポジトリ名が入ります。所有者は、個人アカウントに作ったリポジトリであればユーザ名、Organization に作ったリポジトリであれば Organization 名です。

公開の通知の選り分け

[分岐 XOR ゲートウェイ]「公開の通知かどうか」で、q_action の値を見ます。[ヒューマンタスク]「告知文の作成」へ向かう経路に、q_action が published と等しい、という条件を設定します。既定の[その他]の経路は[終了イベント]「対象外」へつなぎます。

これで、ping も、published 以外のリリースの通知も、告知の工程には進みません。

GitHub 側の設定

ここまでで、ワークフローアプリ側の設定は終わりです。GitHub に登録する前に、ワークフローアプリをリリースしておきます。登録した直後に GitHub が確認の通知(「届く通知の種類」で説明した ping)を送ってくるので、その時点で受信 URL が有効になっている必要があります。

通知を送るリポジトリの[Settings]から、[Webhooks]を開いて追加します。GitHub には[Settings]がいくつもあります。ここで開くのはリポジトリの[Settings]です。Organization の[Settings]にも[Webhooks]がありますが、そちらは Organization 全体に対する設定です。追加には、そのリポジトリの管理者権限が必要です。

登録する設定項目は次のとおりです。

  • Payload URL — [メッセージ開始イベント (Webhook)]の受信 URL
  • Content type — application/json
  • Secret — 空のままにします(理由は後述)
  • Which events would you like to trigger this webhook? — [Let me select individual events]を選び、[Releases]にチェックを入れます
  • Active — チェックを入れます

[Secret]に文字列を登録すると、GitHub はリクエストの署名を X-Hub-Signature-256 という HTTP ヘッダに入れて送ります。受け取った側が、その署名で送信元を検証するためのものです。ただし[メッセージ開始イベント (Webhook)]が保存するのはリクエストボディだけで、HTTP ヘッダの値は参照できません。Secret を登録しても、署名の検証は行えません。

エンドポイントを守るのは、受信 URL に含まれる API キーと、「アクセス元の IP アドレス制限」で登録した許可範囲の 2 つです。

画面の構成は変わることがあります。画面が説明と違う場合は、GitHub の公式ドキュメントで最新の手順を確認してください。

届かないときの確認

GitHub 側には、送ったリクエストと受け取った応答の記録が残ります。リポジトリの[Settings]>[Webhooks]で対象の Webhook を開くと、[Recent Deliveries]に配信の一覧があります。リクエストのヘッダとボディ、応答のステータスコードとボディを、配信 1 件ごとに確認できます。同じ内容を送り直すこともできるので、Questetra BPM Suite 側の設定を直したあとの確認に使えます。表示されるのは直近 3 日分です。それより前の配信は確認も再送もできないので、設定を直したら早めに確かめてください。

応答のステータスコードごとの見方は、エラー対処編で説明しています。403 が返る場合は、IP アドレス制限に GitHub の範囲が登録されているかを確認してください。初期状態のままでは、GitHub からの通知はすべて 403 になります。

400 で本文に NodeDoesNotExist が返る場合は、受信 URL のどこかが違っています。API キーの誤りも、アプリ ID や工程番号の誤りも、アプリが未リリースの場合も、同じ応答が返ります。どこが違うのかは応答からは分かりません。攻撃する側に手がかりを与えないよう、原因を区別しない作りになっています。GitHub 側の[Recent Deliveries]に記録された送信先 URL と、プロパティ画面に表示される受信 URL を、1 文字ずつ突き合わせてください。

ケースは開始されているのに値が空の場合は、[スクリプトタスク]の解析が合っていません。q_webhook_body に保存された内容と、スクリプトが参照しているキーの名前を突き合わせてください。

参考