ワークフローから外部システムを操作しよう（レスポンス活用編）

前回まで、課題番号やコメントの ID は既に業務データに入っているものとして話を進めてきました。この記事では、その取り出し方を扱います。

この回では［スクリプトタスク］を使います。第 1 回で説明したとおり、この連載は Professional エディションが前提で、［スクリプトタスク］も同じエディションの機能です。ここまで試せていれば、追加の準備は要りません。

JSON を組み立てるほうは、第 3 回で説明したとおり［データ更新］だけで完結しました。読むほうは、設定だけでは完結しません。返ってきた文字列の中から目当ての値を取り出す仕組みが用意されていないので、数行のスクリプトで取り出します。

前回：第 4 回 更新・削除編 — 作った課題を後から操作する

この回で作る工程

この回では、ヒューマンタスクは増えません。ここまでに置いた［メッセージ送信中間イベント (HTTP)］のうち 3 つについて、その直後に［スクリプトタスク］を足します。いずれも、次のヒューマンタスクで使える形に値を整えるためのものです。

• ［スクリプトタスク］— 第 2 回で置いた［メッセージ送信中間イベント (HTTP)］（課題の一覧を取得）の直後、ヒューマンタスク「重複の確認」の直前に置きます。一覧を読みやすい形に整えます
• ［スクリプトタスク］— 第 3 回で置いた［メッセージ送信中間イベント (HTTP)］（課題の起票）の直後、ヒューマンタスク「着手の記録」の直前に置きます。レスポンスから課題番号と課題の URL を取り出します
• ［スクリプトタスク］— 第 4 回で置いた［メッセージ送信中間イベント (HTTP)］（コメントの追加）の直後、ヒューマンタスク「完了の確認」の直前に置きます。レスポンスからコメントの ID を取り出します

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

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

• 「課題 URL」（q_issue_url、文字 (単一行)）— 起票した課題へのリンクです
• 「関連する課題」（q_related_issues、文字 (Markdown)）— 取ってきた課題の一覧を、読みやすく整えたものです

これで、連載で使うデータ項目はすべて揃いました。

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

第 4 回で「着手の記録」と「完了の確認」のフォームに置いた「課題番号」と「コメント ID」は、この回で自動的に入るようになります。手で入力する必要がなくなるので、編集可から表示のみに変えました。

「関連する課題」は「重複の確認」のフォームに置きます。第 2 回では「レスポンス」をそのまま表示していましたが、確認にはこちらを見れば足ります。「レスポンス」は、想定と違う結果になったときに中身を確かめられるよう、表示のみのまま残しています。

文字列として保存されるレスポンス

第 3 回で、課題を起票したときのレスポンスを思い出してください。

{
  "number": 2,
  "title": "検索結果の表示件数を増やしたい",
  "state": "open",
  "html_url": "https://github.com/yourname/workflow-practice/issues/2",
  ...
}

これは「文字 (複数行)」のデータ項目に、そのままの文字列として入っています。Questetra BPM Suite 側は、この時点では 1 つの長い文字列として保持しているだけです。number が 2 であることは、まだ業務データになっていません。

値の取り出し

課題を起票する［メッセージ送信中間イベント (HTTP)］の直後に［スクリプトタスク］を置きます。

スクリプトは次のようになります。

const responseText = engine.findDataByVarName("q_response");
const issue = JSON.parse(responseText);

engine.setDataByVarName("q_issue_number", new java.math.BigDecimal(String(issue.number)));
engine.setDataByVarName("q_issue_url", issue.html_url);

やっていることは 3 つです。レスポンスのデータ項目から文字列を読み、JSON.parse で構造として解釈し、必要な値を業務データに書き戻しています。

数値のデータ項目に値を入れるときは java.math.BigDecimal で包みます。JSON.parse が返すのは JavaScript の数値なので、String() でいったん文字列にしてから渡してください。文字のデータ項目は、そのまま渡せます。

引用するデータ項目の名前は、ご自身のアプリのフィールド名に読み替えてください。

取り出した値の活用

課題番号が業務データに入れば、第 4 回で扱った操作がすべて動き出します。アクセス URL に番号を差し込んでコメントを書き込み、完了時に課題を閉じる。一連の流れがつながります。第 4 回で手入力していた課題番号も、これで要らなくなります。

課題 URL のほうは、人に見せるために使います。

たとえば、要望を出した人に結果を知らせるメールに、課題へのリンクを載せる。あるいは［データ更新］で件名を組み替えて、ケースの一覧からそのまま GitHub に飛べるようにする。ワークフローと GitHub のあいだを人が行き来しやすくなります。

一覧を受け取ったとき

第 2 回で扱った Issue の一覧のように、レスポンスが配列で返る場合もあります。この場合も考え方は同じです。取り出した結果は「関連する課題」（q_related_issues）に入れます。

const responseText = engine.findDataByVarName("q_response");
const issues = JSON.parse(responseText);

const lines = issues.map(i => "- [" + i.title + "](" + i.html_url + ")");
engine.setDataByVarName("q_related_issues", lines.join("\n"));

配列を人が読める形に整えてから、データ項目「関連する課題」（q_related_issues）に入れています。この項目を文字 (Markdown)で作っておけば、フォーム上でリンクとして表示されます。似た課題が既にあるかどうかを処理担当者が確認する場面では、この形が扱いやすいでしょう。

コメント ID の取り出し

第 4 回でコメントを追加した工程の直後にも、同じ要領で［スクリプトタスク］を置きます。レスポンスは追加された 1 件のコメントの情報なので、そこから id を取り出して「コメント ID」（q_comment_id）に書き戻します。

const responseText = engine.findDataByVarName("q_response");
const comment = JSON.parse(responseText);

engine.setDataByVarName("q_comment_id", new java.math.BigDecimal(String(comment.id)));

これで、第 4 回で手入力していたコメント ID も要らなくなります。

想定と違うものが返ってきたとき

JSON.parse は、渡された文字列が JSON として成立していないと失敗します。通信そのものが失敗していた場合、レスポンスのデータ項目には JSON ではない内容が入っていることがあります。

そのまま解釈しようとすると、スクリプトタスクがエラーで止まります。何が起きたのか分からないまま、ケースが進まなくなります。

そうならないための備えは、次回に扱います。

次回

最終回です。うまくいかないときに何が起きているのかを読み取り、ワークフローとして破綻させない作り方を扱います。

第 6 回 エラー対処・デバッグ編 — 失敗しても止まらないアプリにする