ワークフローから外部システムを操作しよう（情報取得編）

前回は、固定した URL に GET リクエストを送り、通信が届いたことを確認しました。しかし、いつも同じ URL にリクエストを送るだけなら、ワークフローに組み込む意味はありません。

この要素では、そのケースの業務データをリクエストに含められます。この記事では、処理担当者がフォームで指定した条件を GET リクエストに反映させ、GitHub から必要な情報だけを取ってくる方法を扱います。

ここで作るのは、改善要望フローの前半部分です。要望が上がってきたとき、同じ内容が既に課題として登録されていないかを処理担当者が確認できるように、関連する Issue の一覧を自動で取得します。

前回：第 1 回 準備編 — GitHub と Questetra BPM Suite をつなぐ

この回で作る工程

第 1 回では、固定した URL で課題の一覧を取ってきました。この回では、どのリポジトリのどの課題を取ってくるかを、そのケースの内容に応じて変えられるようにします。そのうえで、取ってきた一覧を人が見て判断する工程を足します。

• ヒューマンタスク「受け付けた要望の記録」— 第 1 回で置いたものです。この回で追加するデータ項目は、このフォームに置きます
• ［メッセージ送信中間イベント (HTTP)］— 第 1 回で置いたものです。アクセス URL と［送信パラメータ］を変更します
• ヒューマンタスク「重複の確認」— この回で追加します。取ってきた課題の一覧を見て、同じ要望が既に登録されていないかを確かめます

確認が登録の手前にあるので、二重に起票する前に気づけます。重複していたケースを打ち切る経路は、この連載では作りません。必要であれば、この後ろに［分岐 XOR ゲートウェイ］と終了イベントを足してください。

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

この回で追加するデータ項目は、「リポジトリ」（q_repo）と「要望の分類」（q_request_label）の 2 つです。どちらもデータタイプは「選択」で、第 1 回で作ったアプリに追加します。

どちらも必須にしておいてください。リポジトリはアクセス URL の一部になるので、選ばれていないと宛先が壊れます。要望の分類は、この回の絞り込みだけでなく、第 3 回で起票する課題のラベルにもなります。

ここまでに用意したデータ項目は、次のとおりです。フィールド名をこの記事のとおりに付けておくと、以降の設定やコードをそのまま使えます。

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

選択型のデータ項目には、選択肢を用意しておく必要があります。選択肢は「選択肢 ID」と「表示ラベル」の組で、この記事では次のように設定した前提で進めます。

「リポジトリ」（q_repo）は、操作の対象になるリポジトリを選ぶ項目です。選択肢 ID には GitHub のリポジトリ名を、表示ラベルには処理担当者に見せたい名前を入れます。第 1 回で作った練習用のリポジトリだけなら、選択肢は 1 つで構いません。

「要望の分類」（q_request_label）は、上がってきた要望の種類を選ぶ項目です。この値は GitHub のラベル名として送るので、選択肢 ID には GitHub 側に登録されているラベル名を、表示ラベルには処理担当者に見せたい日本語を入れます。

enhancement・bug・documentation は、GitHub がリポジトリを作った時点で用意しているラベルです。自分で追加したラベルを使う場合は、GitHub 側の名前と選択肢 ID を一致させてください。

選択肢 ID と表示ラベルを分けておくと、GitHub 側のラベル名はそのままに、フォームの見え方だけを日本語にできます。どちらが URL やパラメータに差し込まれるのかは、次の節から順に出てきます。

どちらのデータ項目も、「受け付けた要望の記録」のフォームに置いてください。要望を受け付けた処理担当者が、どのリポジトリを見るのかと、その要望がどの分類にあたるのかを、この工程で選びます。選んだ内容が、次の工程から送るリクエストに反映されます。

アクセス URL への業務データの埋め込み

前回の工程では、アクセス URL にリポジトリの場所をそのまま書きました。この欄には業務データを差し込むこともできます。なお、以降の URL に出てくる yourname は、第 1 回と同じくリポジトリの所有者に読み替えてください。

リポジトリ名を選択型のデータ項目「リポジトリ」（フィールド名 q_repo）で選ばせるとします。素直に書くと次の形になりますが、これはうまくいきません。

https://api.github.com/repos/yourname/#{#q_repo}/issues

末尾の /issues は、そのリポジトリの課題の一覧を返す宛先です。第 1 回では yourname/workflow-practice を直接書いていましたが、リポジトリ名の部分を業務データに置き換えました。

この書き方で差し込まれるのは、選択肢の表示ラベルです。ここでは表示ラベルを「練習用」にしているので、GitHub 側にないリポジトリを指すことになり、404 が返ります。

URL に入れたいのは選択肢 ID のほうです。次のように書きます。

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

選択型のデータ項目は、選ばれた選択肢のリストとして扱われます。そのため #{#q_repo.value} のようには書けず、get(0) で先頭の選択肢を取り出してから value を読みます。先頭の ? は、まだ何も選ばれていない場合に備えるものです。

書式を覚えていなくても、アクセス URL 欄の右端にあるボタン（［参照を挿入する…］）から、ケース ID や件名、各データ項目を選べば、対応する記述が挿入されます。ただし選択型のデータ項目について挿入されるのは #{#q_repo} の形までです。選択肢 ID を使う書き方は、挿入されたものに手を加えてください。

送信パラメータによる条件の絞り込み

この URL のままでは、そのリポジトリの課題がすべて返ってきます。しかし処理担当者に見せたいのは、いま上がってきた要望と関係のありそうな課題だけです。無関係なものまで並ぶと、同じ要望が既に登録されているかどうかが、かえって判断しづらくなります。

そこで、取ってくる課題を絞り込みます。絞り込み条件は URL の本体ではなく、［送信パラメータ］タブで指定します。パラメータ名と値の組を並べていくと、GET リクエストではクエリ文字列として URL の末尾に付加されます。

この記事では、次の 3 つを設定します。［パラメータの値］の列は、ダイアログでの選び方をそのまま書いています。

値は固定値だけでなく、データ項目の値も選べます。labels に渡すのが、処理担当者がフォームで選んだ「要望の分類」（q_request_label）です。

この値を labels に渡すと、同じ分類が付いた既存の課題だけが返ってきます。機能改善の要望を受け付けたケースなら enhancement の課題だけ、不具合の報告なら bug の課題だけ、という具合です。確認すべき範囲が、そのケースで選ばれた分類に応じて自動的に変わります。

もっとも、ここで取ってくる一覧は、同じ要望を確実に見つけるためのものではありません。分類が同じ課題が並ぶだけです。この記事であえてこの形にしているのは、処理担当者がフォームで選んだ内容に応じて送るリクエストが変わることを、実際に動かして確かめるためです。

ここで渡したいのは GitHub のラベル名、つまり選択肢 ID のほうです。［パラメータの値］で「要望の分類」を選ぶと、その下に［選択肢ラベル］か［選択肢ID］かを選ぶ欄が現れます。既定は［選択肢ラベル］なので、［選択肢ID］に変えてください。表示ラベルのままでは、「機能改善」というラベルは GitHub 側に存在しないので、絞り込みが空振りして何も返ってきません。

データ項目が空の場合、そのパラメータ自体が付きません。「要望の分類」を必須にしておくのは、絞り込みの条件が黙って外れるのを防ぐためでもあります。

フォームタイプがチェックボックスのデータ項目を指定した場合は（選択型で複数選べるのはチェックボックスだけです）、同じ名前のパラメータが、選択された数だけ繰り返されます。GitHub の labels はカンマ区切りの 1 つの値を受け取る仕様なので、この形では意図どおりに絞り込めません。この項目は単一選択にしておいてください。

自分で URL に組み立てて書く方法との違いは、記号や空白、日本語が含まれる場合の扱いです。送信パラメータとして渡した値は適切に処理されるので、条件が利用者の入力に左右される場合はこちらを使うほうが安全です。

なお、ラベルではなく文言で探したい場合は、検索用の別のエンドポイント（/search/issues）があります。この記事では扱いません。

返ってきた内容の確認

ケースを開始して工程を通過させると、「レスポンス」のデータ項目に課題の配列が入ります。

[
  {
    "number": 1,
    "title": "練習用の課題",
    "state": "open",
    "html_url": "https://github.com/yourname/workflow-practice/issues/1",
    "labels": [ { "name": "enhancement" } ]
  },
  ...
]

第 1 回で登録した課題には enhancement を付けています。そのため、要望の分類に enhancement を選べばこの課題が返り、bug や documentation を選べば何も返りません。分類を変えて 2 回流してみると、選んだ内容に応じてリクエストが変わっていることが確かめられます。

この内容を人が見られるように、ヒューマンタスク「重複の確認」を［メッセージ送信中間イベント (HTTP)］の後ろに置き、そのフォームに「レスポンス」を表示専用で置きます。処理担当者は、ここに並んだ課題を見て、同じ要望が既に登録されていないかを判断します。

このままでは読みづらい形ですが、まずはこれで確認できます。整形して業務データに取り込む方法は、第 5 回で扱います。

なお、GitHub のこのエンドポイントは、課題だけでなくプルリクエストも一緒に返します。課題だけを見たい場合は、返ってきた内容に pull_request という項目が含まれるかどうかで見分けます。意図しないものが混ざっていると感じたら、まずここを疑ってください。

次回

ここまではすべて GET、つまり読み取りだけでした。次回はいよいよ書き込みに進みます。受け付けた要望を、GitHub の課題として自動で起票します。

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