IM-LogicDesignerで、Redmineカスタムクエリのチケット一覧を取得する方法

このCookBookでは、IM-LogicDesignerを使用してRedmineのチケット (issues) 一覧を取得する方法を紹介します。

Redmineは、外部からチケット一覧を取得するためのREST-APIを提供しています。
IM-LogicDesignerは、REST-APIを呼び出し、返却されたデータを簡単に加工することができます。
これらを組み合わせて、Redmineのカスタムクエリに登録されているチケットの、ID・ステータス・件名・担当者を取得してみましょう。

※バージョン 2016 Winter (Olga) をベースに説明しています。これより古いバージョンの場合、一部機能が使用できない場合があります。

完成イメージ

Redmineに登録されたチケットのうち、カスタムクエリの条件に一致するチケット一覧を取得するサンプルです。

1. Redmineでチケットを登録します。
2. カスタムクエリを登録します。
3. フロー定義で、カスタムクエリの条件等を登録します。
4. フロー定義を実行します。

完成サンプル

以下の完成サンプルをダウンロードしてご活用ください。

LogicDeisngerインポートデータ： im_logicdesigner-data_im_cookbook_121274.zip

ローカル環境で表示させる場合は、上記のインポートデータをインポートしてください。
インポート画面は、「サイトマップ」→「IM-LogicDesigner」→「インポート」をクリックすると表示されます。

インポートすると、以下のデータが登録されます。
・フロー定義 … フロー定義ID： im_cookbook_121274-get_redmine_issues
・ユーザ定義 … ユーザ定義ID： im_cookbook_121274-get_redmine_issues

レシピ

RedmineのREST-APIを呼び出すユーザ定義を作成する
ユーザ定義を呼び出すための、フロー定義を作成する
チケットの詳細から、必要なデータのみを取り出す
加工したデータを集約して、出力する

1. RedmineのREST-APIを呼び出すユーザ定義を作成する

最初に、RedmineのREST-APIを呼び出すユーザ定義（REST）を作成しましょう。
「サイトマップ」→「IM-LogicDesigner」→「ユーザ定義」→「RESTユーザ定義新規作成」をクリックします。

Redmineのチケット一覧を取得するREST-APIのURLは、「ベースURL」＋ "/projects/" ＋「プロジェクトID」＋ "/issues.json" で構成されます。
例えば、ベースURLが「http://redmine.example.org」、プロジェクトIDが「foo」の場合、「http://redmine.example.org/projects/foo/issues.json」です。
実際にブラウザでアクセスすると、プロジェクト：foo に登録されているチケットのうち、最初の100件がJSONで取得されます。

これをIM-LogicDesignerで取得できるようにするためには、上記のURL構成を「エンドポイント」に入力します。

${base_url}/projects/${project_id}/issues.json

1	${base_url}/projects/${project_id}/issues.json

${base_url} はRedmineを置いているサーバの環境、${project_id} は取得するチケットの内容によって変化します。
IM-LogicDesignerのユーザ定義で設定する一部内容は、EL式で記述することで、このような動的に変わる部分を定義することができます。

このAPIは、一度に取得できるチケット数に限りがありますので、条件を変えつつ繰り返し取得する必要があります。
また、プロジェクト内のチケットが全て取得対象となりますので、後述するカスタムクエリを使用した条件付きで取得してみます。

検索条件は「リクエストパラメータ」に指定します。指定する内容は、以下の通りです。
・offset … 取得し始めるチケットの件数
・limit … 1度のリクエストで取得するチケットの最大件数
・query_id … カスタムクエリのID
・key … APIキー

これらも「パラメータ値」にはEL式が使用できます。
汎用性を高めるために、これらのパラメータ値も変数で指定できるようにしておきます。
・offset … ${offset}
・limit … ${limit}
・query_id … ${query_id}
・key … ${api_key}

ここまでに定義したEL式の変数は、「入力値」に型と一緒に定義しておきます。
定義する内容は、以下の通りです。
・${base_url} … <string>
・${api_key} … <string>
・${project_id} … <string>
・${query_id} … <integer>
・${offset} … <integer>
・${limit} … <integer>

最後に「返却値」を定義します。「返却値」には、REST-APIが返却するデータの構造を定義します。
まず、レスポンスがJSONのため、「レスポンス種別」を「json」に変更します。
変更すると、「返却値」の定義がJSON用のものになります。

実際に返却されるJSONの定義を、「body <object>」配下に登録します。
Redmineが返却するデータの構造は大きく、1つずつ定義していくと時間がかかるため、実際に返却されたJSONデータを使用して定義を作成します。

この章の最初で操作したように、RedmineのREST-APIをブラウザで実行して、JSONを入手します。
JSONが入手できたら、「返却値」の「body <object>」を選択して、「JSON入力」をクリックします。

「JSON」に入手したJSONを貼り付けて、「決定」をクリックします。
すると、入力されたJSONと同じ構造の定義が、「body <object>」配下に自動的に作成されます。

これでユーザ定義の準備は完了です。保存しておきましょう。

2. ユーザ定義を呼び出すための、フロー定義を作成する

次に、前章で作成したユーザ定義を使い、実際にRedmineのチケット一覧を取得するフロー定義を作成しましょう。
「サイトマップ」→「IM-LogicDesigner」→「フロー定義一覧」→「新規作成」をクリックします。

フロー定義の処理の流れは、以下の通りです。
1. 初期化 (「Initialize variables」タスク)
2. offsetを設定 (「Set offset」タスク)
3. チケット一覧を取得 (「Get issues of redmine」タスク)
4. 必要なデータを取り出す (「Loop start」～「Loop end」タスク)
5. 取得したチケットの件数を集約する (「Set number of getted issues」タスク)
6. 全件取得が完了していなければ、2.へ戻る (「Getted all issues?」タスク)
7. データを返却して終了 (「End」タスク)

フロー定義の全体像は、以下の通りです。

まずは、Redmineから取得したチケット情報のうち、必要なものを抜粋します。
このCookBookでは、以下のデータを取得することを目的とします。
・チケット番号
・チケットのステータス (名称)
・チケットの件名
・チケットの担当者 (名称)

必要なデータが定義できたので、フロー定義の「出力」を設定します。
ツールバーの「入出力設定」をクリックして、「出力」に以下を定義します。
・issues … <object[]>
・id … <integer>
・status … <string>
・subject … <string>
・assigned-to … <string>

後述するチケットのデータを抜粋する処理で使用するため、同じ構造を変数に用意しておきます。
ツールバーの「変数設定」をクリックして、「変数設定」に以下を定義します。
・redmine … <object>
・offset … <integer>
・count … <integer>
・issues … <object[]> (中身は出力の issues 配下と同じ)
・temporary … <object>
・issue … <object> (中身は出力の issues 配下と同じ)

次の章で、チケットのデータから必要なものを抜粋する手順を説明します。

3. チケットの詳細から、必要なデータのみを取り出す

ユーザ定義で定義した「返却値」は、チケットの全データが格納されているため、数が膨大です。
この中から、必要なデータのみを取り出してみます。

データを取り出すために、「Loop start」タスクで、1件ずつチケットを回します。
次に「Set detail of issue」タスクで、一時領域として定義した変数に、抜粋したデータを格納します。
「Set detail of issue」タスクのマッピング設定は、以下の通りです。
・「loop_start - item - id」→「変数 - temporary - issue - id」
・「loop_start - item - status - name」→「変数 - temporary - issue - status」
・「loop_start - item - subject」→「変数 - temporary - issue - subject」
・「loop_start - item - assigned_to - name」→「変数 - temporary - issue - assigned_to」

次に「Add to issues list」タスクで、抜粋したデータを、変数のチケット一覧に追加します。
「Add to issues list」タスクのマッピング設定は、以下の通りです。
・「変数 - redmine - issues」→「push」関数の「array」
・「変数 - temporary - issue」→「push」関数の「value」
・「push」関数の「out」→「変数 - redmine - issues」

最後に、Redmineのサーバ情報とカスタムクエリ等の情報を設定します。
ツールバーの「定数設定」をクリックして、「定数設定」に以下を定義します。
・REDMINE_API_KEY … RedmineのREST-APIを実行するためのキー
・REDMINE_BASE_URL … RedmineのベースURL
・REDMINE_ISSUES_LIMIT … 1度に取得するチケットの件数 (100)
・REDMINE_PROJECT_ID … チケットが登録されているRedmineのプロジェクトID
・REDMINE_QUERY_ID … RedmineのカスタムクエリID
・ZERO … 数値の0 (初期化で使用)

これらの定数は、「Initialize variables」タスク、および、「Get issues of redmine」タスクの入力値として使用します。
「Initialize variables」タスクのマッピング設定は、以下の通りです。
・「定数 - ZERO」→「変数 - redmine - count」

「Get issues of redmine」タスクのマッピング設定は、以下の通りです。
・「定数 - REDMINE_API_KEY」→「get_issues - api_key」
・「定数 - REDMINE_BASE_URL」→「get_issues - base_url」
・「定数 - REDMINE_ISSUES_LIMIT」→「get_issues - limit」
・「定数 - REDMINE_PROJECT_ID」→「get_issues - project_id」
・「定数 - REDMINE_QUERY_ID」→「get_issues - query_id」
・「変数 - redmine - offset」→「get_issues - offset」

※上記以外のタスクのマッピング設定は、サンプルデータをご参照ください。

4. 加工したデータを集約して、出力する

「End」タスクで、変数に格納したチケットのデータを、フロー定義の「出力」にマッピングして、フロー実行時の出力値を返却します。
「End」タスクのマッピング設定は、以下の通りです。
・「変数 - redmine - issues」→「出力 - issues」

これでフロー定義の準備は完了です。保存しておきましょう。

次に、実際にフロー定義を実行して、チケット情報が取得できるかを確認しましょう。
保存したフロー定義を開き、ツールバーの「デバッグ」をクリックします。
「フロー定義のデバッグ」ウィンドウが開いたら、「実行」をクリックします。
入力はありませんので、すぐに確認ダイアログが表示されます。「決定」をクリックすると、フローの実行が始まります。

正常にチケットのデータが取得できた場合、「フローの実行が正常終了しました。」メッセージが表示されます。

画面右側の「フロー定義の変数情報」の「出力」を確認すると、取得されたチケットのデータが表示されます。
チケットのID、ステータス、件名、担当者名が設定されている場合、それらも表示されます。

このように、IM-LogicDesignerを使用すると、他サービスのデータを取り出し・抜粋し・新しい形に置き換えて出力するロジックを、ノンコーディングで実現できます。
他にもREST-APIを提供するさまざまなサービスとの接続、データの加工が簡単になりますので、ぜひお試しください。