Questetra BPM Suite に待ち受ける工程を置くと、ケースの進み方が外部システムに委ねられます。相手が動かなければ、ケースは止まったままです。しかも待ち受けている状態は誰のタスクにも現れないので、放置されていることに気づきにくくなります。
この記事では、連絡が来ないケースの扱いと、リクエストが届いても受信が失敗する場合の原因の切り分け方を説明します。
この記事は連載「外部システムからの連絡でケースを進めよう」（全 4 回）の第 4 回です。
前回：返答編
待ち受けの締め切り
［受信タスク (HTTP)］と［受信タスク (Webhook)］には、工程のプロパティ画面の［締め切り］で、待ち受けの締め切りを設定できます。基点の決め方は 2 通りです。
| 基点 | 使う場面 |
|---|---|
| ［トークンが到達した時］または［ケース開始日時］ | 「3 日待って連絡が来なければ」のように、待ち始めからの経過で決める |
| 日付型・日時型データ項目の値 | 申請時に決めた期限や、契約上の期日で決める |
どの基点でも、そこからずらす幅を数値と単位で選びます。単位は分後・時間後・日後・箇月後の 4 つ、数値は 1 から 9999 までです。データ項目を基点にしたときだけ、「前」にずらすことも、ずらさずにその日時をそのまま使うこともできます。
基点の選択で表せない条件は、［締め切り］欄の下にある［式］のスイッチをオンにして、SpEL 式で直接書きます。
この連載のアプリでは、［トークンが到達した時］を基点にします。日付型・日時型のデータ項目を持たせていないので、データ項目を基点にする指定は選べません。
設定する値は、折り返し編の［受信タスク (HTTP)］「ビルド結果の受信」が［トークンが到達した時］の 1 時間後、返答編の［受信タスク (Webhook)］「リリース情報の問い合わせの受信」が［トークンが到達した時］の 10 分後です。 ビルド結果の折り返しは、練習用のリポジトリなら数秒、実際のビルドでも数分から数十分で届きます。問い合わせの方は、折り返しの直後に来るので数秒です。正常なら届く時間より長く、放置に気づけるより短くという幅で決めます。
締め切りに達すると、受信タスクは異常終了し、トークンは工程に付いた［タイマー境界イベント］へ移ります。 締め切りを過ぎたケースが本線をそのまま先へ進むことはありません。連絡が来ないケースの扱いは、［タイマー境界イベント］から先の経路に書きます。締め切りを設定すると、［タイマー境界イベント］は工程に自動で付きます。ケースログには「受信タスク 強制終了 締切到達による」と記録されます。ケースログは、ケースの詳細画面で［管理者モード］をオンにすると開ける記録です。開き方と必要な権限は、後の「ケースログの確認」で説明します。
自動で付いた［タイマー境界イベント］は、担当者に確認を促すヒューマンタスクへつなぎます。受信できたケースは本線を進み、連絡が来なかったケースは境界イベントから確認の工程へ、と図の上で経路が分かれます。「ビルド結果」の値で判別する仕掛けは要りません。2 つの受信タスクの境界イベントは、同じ確認の工程にまとめて構いません。
連絡が来なかったケースが放置されないよう、確認の工程の担当者を決めておいてください。
確認の工程には、原因を調べるのに使う値を表示のみで並べておきます。折り返し編で説明した saveOnly=true で途中経過を書き込んでいれば、折り返しが届かなかったケースでも、そこまでに書き込まれた値は残っています。
確認したあとの経路は 2 通りあります。そのまま終了へつなぐか、起動からやり直せるようにするかです。やり直せるようにする場合は、確認の工程から起動側へ戻す線を引き、戻り先の手前に［統合 XOR ゲートウェイ］を置きます。
受信が失敗する理由
リクエストを送ったのに工程が進まないときは、症状から原因を切り分けます。受信タスク自身が返すエラーはすべてステータスコード 400 で、本文は［受信タスク (HTTP)］が XML、［受信タスク (Webhook)］が JSON です。それ以外の応答が返るときは、受信タスクより手前で止められています。404 は URL のパスの誤りです。405 は HTTP メソッドの誤りで、［受信タスク (HTTP)］の受信が POST 以外、受信可否確認 API が GET 以外のときに返ります。［受信タスク (Webhook)］は工程に設定したメソッド以外のリクエストも受け付けたうえで、400 を返します。
403 が返るとき
受信タスクより手前、［IPアドレス制限］で止められています。このとき本文は空で、［受信タスク (HTTP)］の XML も［受信タスク (Webhook)］の JSON も返りません。403 で本文が空なら、［IPアドレス制限］で止められたと判断してください。
送信元の IP アドレスが許可されていません。工程のプロパティ画面の［受信パラメータ、IP アドレス制限］（［受信タスク (Webhook)］では［IP アドレス制限、自動処理ログ］）を押すと開く画面の［接続が許可されているネットワーク］で、その URL に許可されている範囲を確認します。「外部ネットワークからの接続は禁止されています。」と表示されていれば未設定です。システム管理者への依頼の仕方は、後の「IPアドレス制限」で説明します。
400 が返るとき
受信タスクまでは届いていて、受信の処理で失敗しています。トークンは工程に留まったままです。原因は 2 種類に分かれます。
待ち受け中の工程を特定できなかった場合。 URL・API キー・processInstanceId の誤りか、その工程にトークンが居ない（まだ到達していない、すでに通過した、締め切りで終了した）場合です。本文からは、URL・API キー・processInstanceId のどれが誤っているかまでは判りません。ケースログにも残りません（例外は、［受信タスク (Webhook)］で待ち受け中のケースに誤った API キーを送った場合で、これだけは記録されます）。送っている URL とパラメータを、工程のプロパティ画面の URL と突き合わせてください。通過済みの 2 回目については「二重に送られてきたとき」も参照してください。
待ち受け中の工程は特定できたが、受信の内容で失敗した場合。 本文に原因が書かれ、ケースログに「受信タスク 処理失敗 終了せず」と記録されます。この連載の GitHub ワークフローは curl に --fail-with-body を付けているので、本文は GitHub Actions の実行ログに出ます。まずそれを読んでください。原因は主に次のとおりです。
- 必須の設定になっているデータ項目が埋まらない（パラメータ名の打ち間違いを含む）。
saveOnly=trueを付けた途中経過の送信では必須はチェックされず、最後の送信で検出される - 値がデータ項目の制約（［最大文字数］、単一行、正規表現）や文字型の上限（1,000,000 文字）に合わない
- ［受信タスク (Webhook)］で、HTTP メソッドや Content-Type が工程の設定と合わない
200 が返るのに進まないとき
［受信タスク (HTTP)］で saveOnly=true が付いています。値の保存だけが行われ、トークンは工程に留まります。ケースログには「受信タスク 処理成功 終了せず」と記録されます。送っているパラメータを確認してください。
saveOnly は［受信タスク (HTTP)］だけのパラメータです。［受信タスク (Webhook)］にはなく、受信に成功すると必ずトークンが進みます。
200 が返って工程も進むのに、データ項目が空のとき
［受信タスク (HTTP)］は、この工程で「編集可」にしたデータ項目のフィールド名と一致した名前の値だけを書き込みます。名前が合わないパラメータや、q_ で始まらないパラメータは黙って捨てられ、エラーにも警告にもならず、ケースログにも残りません。工程のプロパティ画面の［受信パラメータ、IP アドレス制限］を押すと開く画面の［受信パラメータ］の表にある［受信パラメータ名］と、送っている名前を突き合わせてください。
IPアドレス制限
［システム設定］＞［IPアドレス制限］の設定にはシステム管理権限が要ります。依頼するときは、許可したい送信元のネットワーク範囲（CIDR 表記、IPv4 のみ）と、対象の受信 URL を伝えます。
何を登録するかは、折り返し編（［受信タスク (HTTP)］の工程を 0.0.0.0/0 に開く）と返答編（［受信タスク (Webhook)］の工程の行を別に足す）で説明しています。
ケースログの確認
受信の失敗や、締め切りによる強制終了は、ケースログに記録されます。
ケースログは、ケースの詳細画面で［管理者モード］をオンにすると開けます。開けるのは、そのアプリのコントロール権限を持つユーザだけです。 アプリ管理権限やシステム管理権限を持っていても、コントロール権限が付いていなければ表示されません。処理担当者の権限だけでは開けないので、待ち受けが進まないという申し出を受けたら、コントロール権限を持つユーザが代わりに確認することになります。
二重に送られてきたとき
外部システムからの通知は、同じ内容が 2 回届くことがあります。通信の失敗を送信側が再試行した場合などです。
［受信タスク (HTTP)］も［受信タスク (Webhook)］も、トークンが工程に留まっている間だけリクエストを受け付けます。そのため、1 回目で工程を通過したあとの 2 回目は受け付けられず、400 のエラーになります。ケースが二重に進むことはありません。ただし送信する側では失敗として扱われますので、相手が再試行を繰り返す設計になっていないかを確認してください。
2 回目が 400 になるのは正常な挙動です。送信する側を自分で書けるなら、400 は再試行しても成功しない応答として扱い、再試行は接続の失敗や 5xx に限ってください。折り返し編と返答編で使った受信可否確認 API は「まだ受け取れないか」を待つためのもので、通過済みかどうかの判定には使えません。相手が外部サービスで組み込めない場合は、送信側の再試行の設定で調整することになります。
連載・参考
連載「外部システムからの連絡でケースを進めよう」
参考
