RedmineのチケットをExcel形式でレポートしてみた

Avatar
dstn


皆さまこんにちは。アプレッソ開発部の佐々木です。

今回は、DataSpiderを使ってRedmineで管理されているチケットを読み取り、Excelファイルに出力してメール送信するスクリプトをご紹介したいと思います。

Redmineとは


Redmineとは、プロジェクト管理、進捗管理、情報共有等で利用されているオープンソースのプロジェクト管理ソフトウェアです。

Redmineは、実施するべき作業、修正するべきバグなどのタスクを「チケット」としてプロジェクトに登録します。つまり、1件のタスクは1件のチケットとして、タスクの内容・優先度・担当者・期日・進捗状況などをRedmineで管理します。
redmine_1

チケットのエクスポートをDataSpiderで自動化


チーム内でRedmineの情報を参照する場合はそのままWeb画面にアクセスすればいいですが、進捗報告や工数を集計して顧客にRedmineの情報を公開する場合、RedmineのWeb画面をそのまま見せるのではなく、ファイルに出力してから見せることがあります。

Redmineには、チケットの一覧をCSVやPDFなどの形式でエクスポートできるほか、 XLS Exportというプラグインを導入することでExcel形式でエクスポートすることも可能ですが、エクスポートされる内容はシンプルなリスト形式で履歴情報が無く、エクスポート後に集計や整形といった手間がかかったりします。

このような手間を軽減するために、チケットの取得、加工、Excelファイルへの出力、そしてExcelファイルをメールに添付して送信するという一連の処理をDataSpiderで自動化してみたいと思います。

概要


RedmineにはREST APIが公開されていますので、DataSpiderのRESTアダプタを使いRedmineのREST APIを呼び出してチケットを取得します。取得したチケットを加工(フィルタ、クレンジングなど)した後、Excelファイルに出力してメールに添付して送信するというところまでやってみます。
RedmineのチケットをExcelでレポートする

次項では、DataSpiderのスクリプトの作成について説明していきます。スクリプトの処理すべてを説明すると今回の記事ではとても書き切れないのでポイントになる処理に絞って説明していきます。

スクリプトの作成

 

テンプレートのExcelファイルを準備


今回は、以下のようなフォーマットでExcelファイルに出力します。

Noトラッカーステータス優先度題名担当者開始日期日進捗率作成日更新日履歴


チケットの[履歴]の追加と、強調したい項目(「期日」と「進捗率」)の背景色を変えて、XLS Exportとは異なるオリジナルのExcelレポートを作成してみます。

グローバルリソースを作成する


RESTアダプタのグローバルリソースでは、[URL]にRedmineのURLを入力します。
Redmine_14

Redmine REST APIの認証


Redmine REST APIの認証方式は、ユーザ/パスワードによるBasic認証とAPIアクセスキーによる認証の2つの方式がありますが、Basic認証の場合、パスワードの保存が分散されて管理が煩雑になるので、今回はAPIアクセスキーによる認証を使います。

APIアクセスキーの取得は、Redmineの画面で[管理]-[設定]-[認証]タブを開き、[ RESTによるWebサービスを有効にする]にチェックを入れます。このチェックを入れることで、APIアクセスキーによる認証が利用できるようになります。
redmine_12

APIアクセスキーは、Redmineの画面で右上にある[個人設定]を開き、画面右にある「APIアクセスキー」の「表示」ボタンを押下することで取得できます。
redmine_13

取得したAPIアクセスキーは、RESTアダプタの各処理の[ヘッダ設定]タブにある[リクエストヘッダ]に設定します。設定するリクエストヘッダの[名前]と[値]は以下の通りです。

名前
X-Redmine-API-Key <APIアクセスキー>

 

チケットの一覧を取得する


チケット一覧を取得するRedmine REST APIは以下になります。

GET /issues.[format]

[format]はレスポンスのデータ形式を指定します。「json」を指定した場合JSON形式、「xml」を指定した場合はXML形式となります。RESTアダプタは両方の形式に対応していますが、ここでは「xml」を指定します。

RESTアダプタの「GET実行」処理の設定画面は以下のようになります。

[必須設定]
redmine_3

オプションで以下のパラメータを[クエリパラメータ]で指定します。

名前
project_id 取得するチケットのプロジェクトを表すID
status_id 取得するチケットのステータス(「*」の場合すべて)
limit 一回のリクエストで取得するチケット数の上限(デフォルトは「25」、最大値は「100」)
offset 取得するチケットの開始位置



設定画面のoffsetパラメータの値が ${offset}になっていますが、これは「offset」というスクリプト変数を参照していることを表します。チケット一覧の取得では、一回のリクエストで取得できるチケットの上限はlimitの値に依存します。対象のプロジェクトがlimitの値よりも多く存在する場合、チケット一覧の取得処理を複数回に分けて行う必要になります。このとき、取得したチケットの数をoffsetに記録しておくことで、それまで取得したチケットをスキップしてチケット一覧取得処理を開始することが可能になります。

上記設定で「GET実行」処理を実行すると、レスポンスは以下のようなXMLデータになります。

<issues total_count="11" offset="0" limit="100" type="array">
<issue>
<id>31</id>
・・・
</issue>
<issue>
<id>30</id>
・・・
</issue>
・・・
</issues>

issuesの子要素であるissue要素は、取得したチケットの数分出現します。このデータを、後続の分割繰り返し処理でissue要素ごとに分割し、チケットを一件ずつ処理します。

チケットを取得する


チケットを取得するRedmine REST APIは以下になります。

GET /issues/[チケットID].[format]

issue要素ごとに分割し、その中でチケットのIDを取得します。そして、取得したチケットIDをスクリプト変数に代入して、後続のRESTアダプタの「GET実行」処理の[パス]でスクリプト変数を参照します。

RESTアダプタの「GET実行」処理の設定画面は以下のようになります。

[必須設定]
redmine_4

今回は、チケットの履歴を取得するので、[クエリパラメータ]で「 include=journals」を指定します。

上記設定で「GET実行」処理を実行すると、レスポンスは以下のXMLデータになります。

<issue>
<id>21</id>
・・・
<journals type="array">
<journal id="63">
<user id="3" name="佐々木 健二"/>
<notes/>
<created_on>2014-03-25T05:38:07Z</created_on>
<details type="array">
<detail property="attr" name="done_ratio">
<old_value>0</old_value>
<new_value>20</new_value>
</detail>
・・・
</details>
</journal>
・・・
</journals>
</issue>

1つのjournal要素が1つの履歴を表しており、journals要素の子要素として履歴の数分出現します。journal要素の主な子要素、属性の説明は以下のとおりです。

要素・属性名説明
user 履歴の作成者
notes 履歴作成時に追記されたコメント
created_on 履歴作成日時
detailes/detail 変更した項目の詳細
detailes/detail@name 変更した項目の名前
detailes/detail/old_value 変更前の値
detailes/detail/new_value 変更後の値

 

取得したチケットをExcelファイルに書き込む


Excelアダプタの「書き込み」処理で、1件ずつ分割されたチケットデータを挿入します。書き込み先のExcelファイルは、予め作成したテンプレートのExcelファイルをコピーしたものになります。

Excelアダプタの「書き込み」処理の設定画面は以下のようになります。

[必須設定]
redmine_5

[書き込み設定]
redmine_6

Excelファイルをメールで送信する


一覧取得したすべてのケットをExcelファイルに書き込んだら、次の処理でメールに添付して送信します。メール送信にはメールアダプタの「1通メール送信」処理を使います。

作成したファイルをメール送信処理で添付するというパターンはDataSpiderでは数多く採用されています。 DataSpiderデザインパターンβ 第8回 設計パターン 「Mail&Excel Data Integration」でもご紹介していますので、そちらの記事もご一読いただければと思います。

メールアダプタの「1通メール送信」処理の設定は以下のようになります。

[必須設定]
redmine_10

[メッセージ]
redmine_8

[添付ファイル]
redmine_9

スクリプトの完成イメージは以下のようになります。
redmine_7

スクリプトを実行する


スクリプトを実行し処理が成功すると、メールアダプタの「1通メール送信」処理で指定した宛先に「redmine_issues.xls」というファイルが添付されます。添付されたファイルの内容は以下のようになります。
redmine_11

このスクリプトを日次スケジュールトリガーで実行することで、Redmineからのレポートが1日1回自動でメール送信されるということも可能になります。

まとめ


RESTアダプタを使うことでRedmineのデータを取得することができました。

今回利用したRedmineのREST APIはGETのみでしたが、チケットの登録や更新といったPOSTの処理も提供されているので、Redmineと別のシステムとの相互連携もDataSpiderで実現可能だと考えます。

もし、すでにDataSpiderを使ってRedmineと連携している方がいましたら、是非コメントを残していただけると幸いです。また、Redmineでこんな連携ができるともっと便利なんだけど、みたいなご意見もお待ちしております!

コメント

ログインしてコメントを残してください。

Powered by Zendesk