外部システムからの連絡でケースを進めよう（準備編）

外部システムに投げた処理は、すぐ終わるものばかりではありません。時間のかかる処理には、ビルドとテスト、夜間バッチ、外部への審査依頼などがあります。数分から数日かかる処理が終わってから次の工程へ進めたい、という場面です。

Questetra BPM Suite には、トークンをその場に留めて、外部からのリクエストを待ち受ける工程があります。定期的に問い合わせて完了を確認する方法もありますが、相手が完了を知っているのであれば、その連絡を受けて進められます。

この連載では、GitHub Actions で走らせたビルドとテストの結果を受け取って、リリース申請のケースを承認の工程へ進めます。準備編では、その処理を起動できるところまでを作ります。

GitHub Actions は、リポジトリで自動処理を走らせる仕組みです。処理の定義は、.github/workflows/ に置くファイルに書きます。GitHub では、このファイルに書いた処理を「ワークフロー」と呼びます。Questetra BPM Suite のワークフローアプリと紛らわしいので、この連載では「GitHub ワークフロー」と書きます。 GitHub ワークフローにはジョブを複数定義でき、原則として並行に動作します。ジョブは順に実行されるステップの並びで、ステップは uses: で公開されているアクションを呼び出すか、run: でコマンドを実行します。

この記事で作るワークフローアプリ

ソフトウェアのリリース申請を題材にします。

• ［開始イベント］
• ヒューマンタスク「リリース申請」
• ［データ更新］「リクエストボディの作成」
• ［メッセージ送信中間イベント (HTTP)］「GitHub ワークフローの起動」
• ［終了イベント］

申請を社外から受け付ける場合は、［開始イベント］と「リリース申請」をまとめて［メッセージ開始イベント (フォーム)］に置き換える構成にもできます。この記事では社内からの申請を想定して、［開始イベント］を使います。

折り返し編では、［メッセージ送信中間イベント (HTTP)］と［終了イベント］の間に［受信タスク (HTTP)］を中心とする 3 つの工程を足して、GitHub ワークフローの実行結果を受け取ります。

［メッセージ送信中間イベント (HTTP)］の設定そのものは、連載「ワークフローから外部システムを操作しよう」で説明しています。この記事では GitHub ワークフローを起動する部分だけを取り上げます。

この記事で使うデータ項目

データ項目を 2 つ用意します。どちらもデータタイプは文字 (複数行) です。リリースの内容は件名に書く前提にしています。

• 「起動リクエストボディ」（q_dispatch_body）— GitHub ワークフローを起動するリクエストのボディを保持します
• 「起動エラー内容」（q_error）— 起動に失敗したときの応答を受け取ります

フィールド名をこの記事のとおりに付けておくと、後の回に出てくる設定やコードをそのまま使えます。データ項目は回を追うごとに増えていきます。以降の回でも、追加する箇所にその時点までの一覧を載せます。

どちらも自動処理の工程が書き込むデータ項目です。書き込まれるのは「リリース申請」を処理した後なので、このフォームには出しません。「起動エラー内容」は、起動に失敗したときにケースの詳細画面で確かめます。

GitHub 側の準備

練習用のリポジトリを 1 つ用意してください。この記事では workflow-practice という名前で説明します。連載「ワークフローから外部システムを操作しよう」を読んだ方は、そこで作ったリポジトリをそのまま使えます。用意することは 2 つです。

GitHub ワークフローの定義ファイルを main ブランチに置きます。 .github/workflows/release-check.yml を作ります。

name: release-check
on:
  workflow_dispatch:
    inputs:
      case_id:
        description: Questetra BPM Suite のケース ID
        required: true
        type: string

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: テストの実行
        run: echo "ここでビルドとテストを走らせます"

release-check に定義しているジョブは check の 1 つだけです。check には 2 つのステップがあり、先頭のステップは GitHub.com で公開されているアクション actions/checkout@v4 を参照して、リポジトリの内容をランナーに取り出します。2 つ目のステップ「テストの実行」は、run: に書いたコマンドを実行します。この連載では起動と折り返しの流れを追うことが目的なので、echo を 1 行置いているだけです。実際の運用では、ここにビルドやテストなど、リリース前に済ませたい処理のコマンドを書くことになります。

on: workflow_dispatch は、この GitHub ワークフローを API から起動できるようにする指定です。この指定で起動できるのは、リポジトリの既定ブランチ（新しいリポジトリなら main）にあるファイルだけです。 作業ブランチに置いたままでは、起動のリクエストがエラーになります。起動のリクエストで指定するブランチも、まずは同じ main にしておきます。

inputs には、起動する側から渡してもらう値を宣言します。ここではケース ID を 1 つ受け取ります。どのケースへ折り返すのかを渡すためで、理由は折り返し編で説明します。

GitHub のアクセストークンには Actions の権限が要ります。 ここでいうアクセストークンは GitHub の認証情報で、ワークフローの工程を進むトークンとは別のものです。GitHub ワークフローを起動するには、fine-grained personal access token の Repository permissions で Actions を Read and write にします。Issue の操作だけを許可したアクセストークンでは、起動のリクエストが権限不足で失敗します。連載「ワークフローから外部システムを操作しよう」で作ったものを使う場合は、GitHub の設定画面で権限を追加してください。まだ作っていない場合は、GitHub の［Settings］＞［Developer settings］＞［Personal access tokens］＞［Fine-grained tokens］で発行します。

GitHub ワークフローを起動する

［メッセージ送信中間イベント (HTTP)］で、GitHub ワークフローの実行を開始します。

yourname はリポジトリの所有者（GitHub のユーザ名または Organization 名）に、workflow-practice は用意したリポジトリの名前に、それぞれ置き換えてください。

リクエストボディは［データ更新］で組み立て、「起動リクエストボディ」に入れます。

{
  "ref": "main",
  "inputs": {
    "case_id": "#{processInstanceId}"
  }
}

#{processInstanceId} は、そのケースの ID に置き換わる SpEL 式です。この値が、あとで折り返してもらうときの目印になります。

ブランチを選べるようにするなら、データ項目を足します。 定義ファイルが main にあれば、実際に走らせるブランチは別に選べます。「ブランチ」（q_branch、文字 (単一行)）を追加し、「リリース申請」で「編集可」にして申請者に選ばせ、"ref": "#{#escaper.escapeJson(#q_branch)}" のように差し込みます。値に引用符などが混ざっても JSON が壊れないよう、エスケープの関数を通します。

inputs の値は文字列で渡します。 workflow_dispatch の inputs で type: number などを指定していても、起動の API へは文字列として渡す必要があります。数値やブール値をそのまま書くとエラーになります。

起動に成功すると、HTTP 204 が返ります。 応答の本文はありません。実行が始まったことだけが判り、結果はここでは判りません。結果は、折り返し編で置く［受信タスク (HTTP)］で受け取ります。

実際に走ったかどうかは、GitHub のリポジトリの［Actions］タブで確かめられます。左の一覧で release-check を選ぶと、いま起動した実行が一番上に並び、起動のきっかけが workflow_dispatch と表示されます。実行を開くと、ジョブごとのログと、渡した case_id の値を確認できます。

［HTTP 認証設定］の登録手順は、連載「ワークフローから外部システムを操作しよう」と同じです。ただし、あちらで「アプリ固有の設定」として登録したものは、別のアプリからは選べません。このアプリで、認証タイプ［トークン直接指定］の設定を新しく登録し、アクセストークンの値を貼り付けて、この工程で選びます。アクセストークンそのものは、前の節で権限を足したうえで使い回せます（HTTP 認証設定について理解する）。

「起動エラー内容」には、起動に失敗したときの応答が残ります。権限不足なのかリポジトリ名の誤りなのかを切り分けられます。

連載「外部システムからの連絡でケースを進めよう」

• 準備編（この記事）
• 折り返し編（近日公開予定）
• 返答編（近日公開予定）
• 締め切り・エラー対処編（近日公開予定）

参考

• BPMNアイコン：メッセージ送信中間イベント (HTTP)
• ワークフローから外部システムを操作しよう（準備編）
• HTTP 認証設定について理解する