ワークフローの途中で、外部のシステムを操作したくなることがあります。受け付けた要望を開発チームの課題管理に登録したい、在庫システムに引き当てを掛けたい、社内の別サービスに通知したい、といった場面です。［メッセージ送信中間イベント (HTTP)］は、こうした場面で外部へ HTTP リクエストを送るモデリング要素です。
この連載では全 6 回かけて、この要素の使い方を一通り学びます。題材には GitHub を使います。無料のアカウントで誰でも試せて、API の仕様も安定しているためです。最終的には「社内から上がってきた改善要望を受け付け、同じ課題が既にないかを確かめてから GitHub の Issue（課題）として自動起票し、対応が終わったら Questetra BPM Suite 側からクローズする」というワークフローアプリを組み上げます。
なお、［メッセージ送信中間イベント (HTTP)］は Professional エディションの機能です。この連載は全 6 回とも、Professional エディションが前提になります。
第 1 回のこの記事では、アプリの動きを作り込むことはしません。GitHub と Questetra BPM Suite をつなぐ準備を整え、通信が届いたことを確認するところまで進めます。
練習用リポジトリの用意
GitHub にログインし、練習用のリポジトリを 1 つ作成してください。名前は何でも構いませんが、この記事では workflow-practice という名前で説明します。公開・非公開のどちらでも動作します。
あわせて、そのリポジトリに練習用の課題を 1 件登録しておいてください。件名は何でも構いません。ラベルには enhancement を付け、登録したままクローズしないでおいてください。enhancement は、新しいリポジトリに既定で用意されているラベルです。
この回では、この課題が取ってこられることで通信の成功を確かめます。
アクセストークンの発行
Questetra BPM Suite から GitHub を操作するには、あなたの代理であることを GitHub に示す必要があります。そのために使うのがアクセストークンです。
発行するのは Fine-grained personal access token です。GitHub のトークンには従来からの classic のものもありますが、リポジトリ単位・権限単位で絞り込めるのは Fine-grained のほうです。
トークンは、アカウントの［Settings］から発行します。その中の［Developer settings］＞［Personal access tokens］＞［Fine-grained tokens］です。リポジトリの画面にも［Settings］がありますが、そちらではありません。
発行の画面では、次の 3 つを決めます。
- 有効期限（Expiration）— 既定では短い期間が入っています。期限が切れると、それまで動いていたアプリが突然 401 で失敗するようになるので、いつまで有効かは控えておいてください
- 対象のリポジトリ（Repository access）— 先ほど作った練習用リポジトリだけに絞ります
- 権限（Permissions）— リポジトリの権限から Issues を選び、読み書きの両方を許可します。Metadata の読み取りは自動で付きます
発行されたトークンは、この画面を離れると二度と表示されません。次の手順ですぐ使うので、コピーしたまま Questetra BPM Suite のタブへ移ってください。
なお、Organization が持つリポジトリを対象にする場合は、Organization 側の承認が必要なことがあります。
GitHub の設定画面の構成は変わることがあります。画面が説明と違う場合は、GitHub の公式ドキュメントで最新の手順を確認してください。
練習用アプリの作成
Questetra BPM Suite 側で、新しいワークフローアプリを 1 つ作ってください。工程はまだ置かなくて構いません。
先にアプリを作るのは、次の手順で登録する HTTP 認証設定が、アプリごとに保持されるものだからです。アプリがないと登録する先がありません。
HTTP 認証設定の登録
コピーしたトークンを、いま作ったアプリに登録します。［▼アプリ］＞［HTTP 認証設定］をクリックすると、認証タイプごとに分かれたタブが並んでいます。「トークン直接指定」のタブに移ってから、「アプリ固有の設定」の［追加］をクリックします。あとから工程のプロパティを開いているときは、［ヘッダ］タブの［設定はこちらから］からも同じ画面に移れます。
同じ画面には「全アプリで共有される設定」もありますが、こちらはシステム管理者しか編集できません。自分のアプリで試すぶんには「アプリ固有の設定」で構いません。
名前は、後で工程のプロパティから選ぶときの目印になります。「GitHub 練習用」のように分かりやすく付けておきましょう。トークン欄には、先ほどコピーした文字列をそのまま貼り付けます。
この設定は、登録しただけでは働きません。［メッセージ送信中間イベント (HTTP)］の［ヘッダ］タブから参照して、はじめて効き始めます。参照すると、送信する HTTP リクエストの Authorization ヘッダに、Bearer に続けて登録した文字列が自動的に付与されます。GitHub が求めている形式そのものです。参照する手順は、次の節で扱います。
なお Authorization ヘッダは、［ヘッダ］タブでカスタムヘッダとして自分で書き足すことはできません。必ずこの認証設定から与えます。
この回で作る工程
先ほど作ったアプリを開き、開始イベントの後ろに次の 2 つを置きます。
- ヒューマンタスク「受け付けた要望の記録」— 受け取った改善要望を書き留める工程です。この回ではフォームに置く項目がないので、件名だけが表示されるフォームになります。項目は第 2 回と第 3 回で足していきます
- ［メッセージ送信中間イベント (HTTP)］— GitHub から、リポジトリに登録されている課題の一覧を取ってきます
開始イベントの直後に置けるのはヒューマンタスクだけです。自動的に処理される工程は、その後ろに並べます。
この 2 つは、以降の回でも使い続けます。この回では固定した URL で課題の一覧を取りますが、第 2 回では、どのリポジトリのどの課題を取ってくるかを、そのケースの内容に応じて変えられるようにします。
この連載では、ヒューマンタスクはどれも開発チームが処理する前提で進めます。誰がどの工程を担当するかは主題ではないので、深追いしません。
この回で追加するデータ項目
データ項目を 2 つ用意します。どちらもデータタイプは「文字 (複数行)」です。
- 「レスポンス」（q_response）— GitHub から返ってきた内容を受け取ります
- 「エラー内容」（q_error）— 通信に失敗したときの理由を受け取ります
フィールド名をこの記事のとおりに付けておくと、後の回に出てくる設定やコードをそのまま使えます。データ項目は回を追うごとに増えていきます。以降の回でも、追加する箇所にその時点までの一覧を載せます。
| フィールド名 | データ項目名 | データタイプ | 追加した回 | 受け付けた要望の記録 |
|---|---|---|---|---|
| q_response | レスポンス | 文字 (複数行) | 第 1 回 | 表示なし |
| q_error | エラー内容 | 文字 (複数行) | 第 1 回 | 表示なし |
どちらも自動工程が書き込むデータ項目です。書き込まれるのは「受け付けた要望の記録」を処理した後なので、このフォームには出しません。中身は、工程を通過した後にケースの詳細画面で確かめます。
工程の設定
工程のプロパティを開き、［通信設定］タブでアクセス URL に次の値を設定します。yourname の部分は、リポジトリの所有者に読み替えてください。自分のアカウントに作ったならご自身の GitHub ユーザ名、Organization に作ったなら Organization 名が入ります。
https://api.github.com/repos/yourname/workflow-practice/issues
HTTP Method には GET を選びます。［レスポンスを保存するデータ項目］には「レスポンス」を、［エラー内容を保存するデータ項目］には「エラー内容」を指定します。
続いて［ヘッダ］タブです。［Authorization ヘッダを指定する］にチェックを入れ、［使用する認証設定］で先ほど登録した「GitHub 練習用」を選びます。さらに、ヘッダを 2 つ追加します。
- ヘッダ名 Accept に、値 application/vnd.github+json
- ヘッダ名 X-GitHub-Api-Version に、値 2022-11-28
Accept は「JSON 形式で返してください」、X-GitHub-Api-Version は「このバージョンの仕様で解釈してください」という指定です。GitHub の API では、この 2 つを明示しておくと将来の仕様変更の影響を受けにくくなります。
動作の確認
アプリを保存してリリースし、ケースを 1 件開始します。開発中のバージョンのままではケースを開始できません。「受け付けた要望の記録」を処理すると［メッセージ送信中間イベント (HTTP)］に進みます。工程を通過すると、「レスポンス」のデータ項目に次のような内容が入っているはずです。
[
{
"number": 1,
"title": "練習用の課題",
"state": "open",
"html_url": "https://github.com/yourname/workflow-practice/issues/1",
...
}
]これが見えていれば、Questetra BPM Suite から GitHub まで通信が届き、認証も通っています。「エラー内容」のデータ項目は、正常に処理できた場合は空のままです。
うまくいかないとき
「エラー内容」のデータ項目を見てください。よくあるのは次の 2 つです。
401 が返る場合は、トークンが誤っているか、有効期限が切れています。HTTP 認証設定に貼り付けた文字列を見直してください。
404 が返る場合は、アクセス URL のアカウント名やリポジトリ名が違うか、トークンにそのリポジトリを扱う権限がありません。GitHub では、権限が足りないときも「存在しない」として 404 を返すことがあります。URL に間違いがないのに 404 が返るなら、トークンの権限を疑ってください。
このほか、システム管理者が［HTTP 接続先制限］を設定している場合は、api.github.com への接続を許可してもらう必要があります。
次回
次回は、この GET リクエストに業務データを乗せます。処理担当者がフォームに入力した条件で Issue を絞り込み、その一覧を取ってくるところまで進めます。
