Web APIで繋がる Questetra / Backlog 連携

みなさん、こんにちは。カスタマー・サポート課のマツシタです。
以前に千葉が業務の見える化を目的に導入しているQuestetra BPM Suite(以下Questetra)とTrello、Slackの連携を紹介させていただきました。

　Web APIで繋がる Questetra / Trello / Slack 連携

今度はQuestetraとヌーラボ Backlog(以下Backlog)を連携してみたいと思います。Backlogはとても多くの機能がありますので、主要な機能である「課題管理」で一般的によく行われるオペレーションの「課題の追加」、「課題情報の更新（マイルストーン）」、「課題コメントの追加」に特化して紹介します。

はじめに

Questetraワークフローを整備して業務を見える化に成功しました。その結果がこんな感じです。 que2backlog_16109 実にキレイにタスクが整理されました。それぞれのタスクの中に手順が書いてあり、そのタスクが回ってきたら書いてある通りにやれば良い。今までは、一人の担当者が仕掛かると最後までやりきらないと引き継げなかったジョブをタスクという小さな単位に分割し、且つ、その進捗をQuestetraで管理できているので途中でインタラプトされてもタスクが終わるところまでやれば、そのままにして問題ないです。きっと、別の人がまた、続きを引き継ぎなく再開できる。非常に便利になりました。

「さぁ、私もタスクを処理しようか」
que2backlog_16107 「Backlog課題を起票してください」というタスクが回ってきました。ここからBacklogにログインして、あとは、コピペ、コピペ、そして、ポチポチポチ・・・。「これってもっと楽にならないのか？API使えば自動化できるんじゃないか？」始まりはここでした。

事前準備

BacklogでAPIキーを用意します。Backlogにログインし、個人設定>>APIでキー発行ができます。このキーを発行したユーザーとしてすべてAPIが実行されますので、個人ユーザーのキーではなく、APIユーザーを用意しておくといいかもしれません。 que2backlog_161010

課題を追加してみよう

まずは「課題の追加」を行いたい場合には次のように「メッセージ送信中間イベント（http）」を設定します。

通信設定

URL	https://<スペースID>.backlog.jp/api/v2/issues
メソッド	POST

que2backlog_16101 アクセスURLとHTTP Methodを設定します。エラー発生時にエラー内容を格納するパラメータの設定は必須ではありませんが、デバッグのために設定することを推奨します。

送信パラメータ

*apiKey	APIキー
*projectId	プロジェクトID（例：SERVERWOKSとか）
*summary	件名
description	詳細（＝課題の本文にあたる情報）
*issueTypeId	課題種別ID
*priorityId	優先度ID
assigneeId	担当者ID
dueDate	締切日（YYYY−MM−DD）
categoryId[]	カテゴリーID

que2backlog_16102 パラメータ名（変数名）と値を設定します。値は内部変数名と固定値を設定できます。
que2backlog_16105 descriptionは課題の本文にあたる部分の情報を格納します。入力フォームから入力させる場合には特に意識は不要かもしれませんが、ワークフローの中で文章を作成したい場合には、「サービスタスク（データ設定）」を使ってデータを格納した方が簡単です。

レスポンス

戻り値	チェック（有効にする）

que2backlog_16103 レスポンスで実行結果の返り値を受け取るように設定しましょう。JSON形式の情報を受け取ることになります。これを「スクリプトタスク」を使ってパースし、必要な情報を抽出します。例えば、課題キーを取得したい場合には次のようなスクリプトで抽出します。

サンプルコード
var str=JSON.parse(data.get(“1”));retVal.put(“2”, str["issueKey"]);
*1, 2はノード番号を指すので設定によって変更してください。

ここであげた送信パラメータはAPI操作できる部分の一部です。他にも同時に設定できる項目が多数あります。詳しくは以下で確認できます。

　API 課題の追加

課題情報を更新してみよう

では次に「課題情報の更新」のうちで「マイルストーン」を更新したい場合には次のように「メッセージ送信中間イベント（http）」を設定します。

通信設定

URL	https://<スペースID>.backlog.jp/api/v2/issues/<課題ID>
メソッド	PATCH

アクセスURLとHTTP Methodを設定します。エラー発生時にエラー内容を格納するパラメータの設定は必須ではありませんが、デバッグのために設定することを推奨します。

送信パラメータ

*apiKey	APIキー
milestoneId[]	マイルストーンID

マイルストーンをIDで設定することが必要です。マイルストーンIDがわからない場合は以下にアクセスするとJASON形式の返り値が取得できます。「name」と紐付いた「id」がマイルストーンのラベルに紐付いたマイルストーンIDです。

https://<スペースID>.backlog.jp/api/v2/projects/OPERATION/versions?apiKey=<APIキー>

詳しくは以下で確認できます。

　課題情報の更新

課題コメントを追加してみよう

最後に「課題コメントの追加」を行いたい場合には次のように「メッセージ送信中間イベント（http）」を設定します。

通信設定

URL	https://<スペースID>.backlog.jp/api/v2/issues/<課題ID>/comments
メソット	POST

送信パラメータ

*apiKey	APIキー
content	コメント

contentにコメントを格納します。入力フォームからの入力ではない場合には「サービスタスク（データ設定）」が便利です。

Backlog課題機能においてよく使われる3つの操作に特化して紹介しました。手順化されたジョブの中で、定型化された処理をBacklog課題に行う場合にはQuestetraから操作するのがミスなく一定の処理ができるのでオススメします。ここで紹介した3つのAPIを含む、すべてのAPIの詳細な情報は以下にまとめられています。

　nulab Developers Backlog APIとは

詳しくは以下で確認できます。

　課題コメントの追加

もうちょっと楽をしたい！

BacklogをQuestetraで操作する際に、もう一つお勧めしたことがあります。Backlog操作用のQuestetraワークフローを作る方法です。理由は2つあります。

que2backlog_16108

1つ目は、APIでは2つの処理を同時に行えないからです。Backlogを操作する際に、コメントを入力して、マイルストーンと状態（ステータス）を変更するような操作は一般的に行います。これをAPIで行うと、「コメント追加」「マイルストーン変更」「状態変更」という2つ処理が必要なので、Questetraワークフローの中では2つの「メッセージ送信中間イベント（http）」のアイコンが必須です。処理がもっと増えれば、タスクとしては1つなのに、「メッセージ送信中間イベント（http）」が3、4つを増えてきます。これをまとめて一度のhttp送信で処理できるようにするにはBacklog操作用のQuestetraワークフローを作る方法が有効です。

2つ目は、マイルストーンや担当者を操作する際には視認性の高いマイルストーンのラベルや担当者名をAPIの送信パラメーターに指定して操作することができないからです。メンテナンス性や同じようなBacklogを操作するワークフローを作ることを想定すると、Backlog操作用のQuestetraワークフローを作る方法が有効です。

que2backlog_16106

pieCeサービスに新しいお客様がお申し込みいただきました際に、サーバーワークスのサポート窓口が業務委託先であるスカイ３６５社にAWSアカウント単位で業務委託をBacklog課題で行う手続きになっています。Questetraで課題登録を自動化することで業務効率が大幅に上がりました。皆さんもQuestetraで業務効率化を推進しませんか！

Questetra BPM Suiteを使ってみたい皆さん、Questetra認定パートナーのサーバーワークスまで是非、ご相談ください。