ワークフローから外部システムを操作しよう（更新・削除編）

前回、受け付けた要望を GitHub の課題として起票できるようになりました。しかし、起票するだけでは足りません。

ワークフローはその後も進みます。開発チームが着手し、対応が終わり、完了を確認します。それぞれの段階で、GitHub 側の課題も同じように更新したいところです。この記事では、作った課題を後から操作する方法を扱います。

前回：第 3 回 課題起票編 — JSON を組み立てて POST する

この回で作る工程

この回では、第 3 回までに作った流れの後ろに、次の工程を足します。

• ヒューマンタスク「着手の記録」— 開発チームが着手したことと、その時点の状況を書きます
• ［データ更新］— コメントの JSON を組み立てます
• ［メッセージ送信中間イベント (HTTP)］— コメントを追加します（POST）
• ヒューマンタスク「完了の確認」— 対応が終わったかを確認します
• ［データ更新］— クローズの JSON を組み立てます
• ［メッセージ送信中間イベント (HTTP)］— 課題を閉じます（PATCH）

「完了の確認」からは、差し戻しの経路を「着手の記録」に向けて引いておきます。コメントを追加する工程はこのループの内側、課題を閉じる工程は外側です。この置き方の理由は、最後の節で扱います。

第 3 回までに作ってあるヒューマンタスクは、「受け付けた要望の記録」と「重複の確認」の 2 つです。この回で足す 2 つを含め、ヒューマンタスクはどれも開発チームが処理する前提で進めます。

この回で追加するデータ項目

この回では、データ項目を 3 つ追加します。

• 「課題番号」（q_issue_number、数値）— 操作する課題を指定するための番号です
• 「進捗コメント」（q_progress_note、文字 (複数行)）— 課題に書き込む文面です
• 「コメント ID」（q_comment_id、数値）— 書き込んだコメントを後から消すときに使います

「課題番号」と「コメント ID」は、この回では処理担当者が手で入力します。GitHub から返ってきた内容にはどちらも含まれていますが、そこから自動で取り出す方法は第 5 回で扱います。まず手を動かして、更新と削除がどう動くかを確かめてください。

入力する場所は、値が分かるようになった後の工程です。課題が作られるのは「重複の確認」を通った後なので、「課題番号」は「着手の記録」のフォームに置きます。コメントが作られるのはさらにその後なので、「コメント ID」は「完了の確認」のフォームに置きます。

ここまでに用意したデータ項目と、各ヒューマンタスクでの編集の可否は次のとおりです。

工程を通る順に並べています。末尾は、通信のために使う裏方のデータ項目です。

「リクエストボディ」は［データ更新］が組み立てる中間データなので、どのフォームにも出しません。送信がうまくいかないときだけ、一時的に「表示のみ」にして中身を確かめます。

URL への課題番号の埋め込み

作った課題を操作するには、どの課題かを指定する必要があります。指定に使うのが、前回のレスポンスに入っていた number です。

手を動かしながら読むなら、GitHub の課題ページで番号を確かめて、「着手の記録」のフォームから手で入力してください。

以降の工程では、アクセス URL にこの番号を差し込みます。リポジトリの部分も、第 2 回と同じく「リポジトリ」の選択肢 ID を差し込みます。

https://api.github.com/repos/yourname/#{#q_repo?.get(0)?.value}/issues/#{#q_issue_number}

進捗コメントの書き込み

まず、着手したことを課題に書き添えてみましょう。この工程は、ヒューマンタスク「着手の記録」の直後に置きます。文字 (複数行)のデータ項目「進捗コメント」（q_progress_note）を追加し、処理担当者が入力する工程のフォームに置いてください。

コメントを追加するには、課題そのものではなく、その課題のコメント一覧を宛先にします。

https://api.github.com/repos/yourname/#{#q_repo?.get(0)?.value}/issues/#{#q_issue_number}/comments

HTTP Method は POST (リクエストボディを指定)、Content-Type は application/json です。［リクエストボディとして送信するデータ項目］には、第 3 回で作った「リクエストボディ」（q_request_body）をそのまま指定します。

その「リクエストボディ」に JSON を組み立てるのが、この工程の手前に置く［データ更新］です。前回と同じ要領で、「リクエストボディ」（q_request_body）に次の式を設定します。処理担当者が書いた内容は「進捗コメント」（q_progress_note）から取ります。

{
  "body": "#{#escaper.escapeJson(#q_progress_note)}"
}

ワークフロー側の処理担当者が書いたコメントが、そのまま GitHub の課題に追加されます。ワークフローに書いた経緯が、GitHub の課題にも残ります。

課題のクローズ

対応が完了したら、課題を閉じます。この工程は、ヒューマンタスク「完了の確認」の直後、差し戻しループの外側に置きます。課題を閉じるのは、既にあるものの一部を書き換える操作です。この場合は PATCH を使います。

アクセス URL は課題そのもの、つまり comments が付かない形です。HTTP Method には PATCH (リクエストボディを指定) を選び、Content-Type は同じく application/json。［リクエストボディとして送信するデータ項目］は、ここでも「リクエストボディ」（q_request_body）です。

この工程の手前にも［データ更新］を置き、「リクエストボディ」（q_request_body）に次の内容を設定します。値を差し込む箇所がないので、そのまま書きます。

{
  "state": "closed",
  "state_reason": "completed"
}

state_reason には completed のほかに not_planned も指定できます。要望が却下されたときの分岐では、こちらを送るとよいでしょう。GitHub の画面上でも、完了として閉じられたのか見送られたのかが区別して表示されます。

ただし、この連載で作るアプリに却下の経路はありません。not_planned を使うのは、起票した後に却下が決まる流れを自分で足したときになります。

コメントの削除

書き込んだコメントを取り消したい場合は DELETE を使います。この工程は本流には置かず、必要になったときに使う操作として説明します。宛先は課題ではなく、コメントそのものです。

https://api.github.com/repos/yourname/#{#q_repo?.get(0)?.value}/issues/comments/#{#q_comment_id}

課題番号ではなくコメントの ID を使う点に注意してください。この ID は、コメントを追加したときのレスポンスに id として入っています。「コメント ID」（q_comment_id）に保持します。

ここで試すなら、GitHub の画面でコメントの ID を確認して、「完了の確認」のフォームから手で入力してください。DELETE ではリクエストボディを送らないので、HTTP Method に DELETE を選ぶだけで設定は終わりです。

何度実行しても結果が変わらない工程と、変わる工程

ここまでで、性質の異なる 2 種類の工程が揃いました。

課題を閉じる PATCH は、何度実行しても結果が変わりません。既に閉じている課題に「閉じてください」と伝えても、閉じたままです。差し戻しで何度通過しても、GitHub 側の状態は変わりません。

一方、コメントを追加する POST は、実行するたびにコメントが増えます。これ自体は欠点ではありません。差し戻しのたびに、そのときの検討内容を書き込みたいのであれば、繰り返し通過する位置に置くのが正しい設計です。

困るのは、毎回同じ文言が書き込まれてしまう場合です。固定の文言や、差し戻しても変わらないデータ項目だけを本文にしていると、同じコメントが何度も並びます。ループの内側に置くなら、本文にそのとき入力された内容が入るようにしておきます。

工程を置く位置を決めるときは、その工程が繰り返し通過したら何が起きるかを、図を描く段階で確かめておくと、後から手戻りが減ります。

次回

ここまで、課題番号やコメントの ID は「既に入っているもの」として扱ってきました。次回は、その取り出し方を扱います。

第 5 回 レスポンス活用編 — 返ってきた JSON から値を取り出す