1.はじめに
フリー版 vs. プロ版
説明の中で (プロ版) と表示されているものは、プロ版でのみ利用可能な機能です。設定画面上では次のようなアイコンが表示されます。Upgradeをクリックすると、マーケットプレースのOptroのサイトが開きます。
アイコン表記
画面上の各項目に次のアイコンが表示される場合があります。
🔒プロ版で利用可能 (現在フリー版のためロック中)
⛔RedmineとのインタフェースにJSONPが選択されているため利用不可
メニューアクセス
操作の中で次のようなRedSyncのメニューにアクセスします。ただし構成内容によって一部のメニューのみ表示される場合もあります。
2.ガイドマップ
ユーザーのタイプと、タイプごとの作業について下図に示します。
タイプごとにユーザーガイドを提供しています。
- システム管理者ガイド
- プロジェクト管理者ガイド
- プロジェクトメンバーガイド
3.システム管理者ガイド
Redmineの構成
RedSyncとRedmineを連携するために、Redmineとのインタフェースに関して幾つかの設定が必要になります。設定内容は連携の範囲によって異なります。
| 連携方式 | REST | JSONP | RedSync Proxy |
| プロトコル | HTTPS | ||
| CORSのサポート | 必要 | 不要 | |
| Redmineへのアクセス | REST | REST + JSONP | Proxy + REST |
| 連携範囲 | |||
| Redmine -> Trello | ○ | ○ | ○ |
| Trello -> Redmine | ○ | – | ○ |
プロトコル
RedSyncからRedmineへのアクセスは、常にHTTPSのサポートが必要です。
CORSのサポート
CORS (Cross-Origin Resource Sharing) は、Webブラウザのスクリプト (RedSync) から、スクリプトのサーバーとは別のサーバー (Redmine) にアクセスために必要なプロトコルです。標準構成のRedmineのインストールではサポートされておらず、追加の構成が必要になります。(こちらを参照)
代替方法として、次のRedSync ProxyまたはJSONPを使用することができます。
Redmineへのアクセス
- RedSync Proxy
CORS非対応のRedmineにアクセスするための代理サーバーです。データの読み取りと書き込みの両方ができます。RESTとの組み合わせで使用します。 - JSONP
JSONPは、RedmineによってサポートされているAPIのひとつです。データの読み取りに限定されますが、CORSのサポートが無くてもRedmineにアクセスすることができます。 - REST
RESTは、RedmineによってサポートされているAPIのひとつです。JSONPと違いデータの読み取りと書き込みの両方ができます。ただしRedSyncからのアクセスには、CORSのサポートまたはRedSync Proxyとの組み合わせが必要になります。
Redmine -> Trelloの同期
チケットからのカードの作成など、主にフリー版で提供される機能です。(こちらを参照)
Trello -> Redmineの同期
カードからのステータスや進捗報告など、主にプロ版で提供される機能です。(こちらを参照)
JSONPによるインタフェースには、CSRF (Cross-Site Request Forgery) と呼ばれるセキュリティリスクが知られています。この対策としてRedmineの場合は、APIキーを使うことでJSONPへのアクセスを保護しています。このためAPIキーを秘匿することが重要になります。より高度な安全性を求めるには、CORSの利用が推奨されています。
RedSync Proxyについて
RedSync Proxyは、RedmineサーバーにCORSサポートが無くても、Trelloとの連携を可能にします。
RedSync Proxyの実態は、AWS (Amazon Web Services) 上で稼働するサーバーです。このためお使いのRedmineは、インターネットからアクセスできる必要があります。イントラネットのみで運用しているRedmineにはアクセスできません。
RedSync Proxyは、Redmineへのアクセスをログします。URLに含まれるサーバー名、パス、パラメータなどが記録されます。ただしやり取りされるデータの内容は記録されません。
RedSync Proxyを通すことで、パフォーマンスに影響がでる場合があります。
可能であればCORSの使用を推奨します。
RedSync Power-Upの追加
メニューから、次の手順に従ってPower-Upを追加します。
メニュー -> Power-Up -> Power-Upの追加
アカウントリンクのメニューが追加されます。
RedmineのAPIを有効にする
RedmineのAPIを、次の手順に従って有効にします。
管理 -> 設定 -> API
連携方式にしたがって、次のAPIを有効にします。
- REST: RESTによるWebサービス
- JSONP: RESTによるWebサービス + JSONP
必ず「RESTによるWebサービス」も有効にしてください。これによりAPIキーによる保護が有効になります。 - RedSync Proxy: RESTによるWebサービス
プロ版への移行
RedSyncにはプロ版とフリー版があります。
プロ版はマーケットプレースのOptroから提供されています。
4.プロジェクト管理者ガイド
4.1.アカウント認証
次の手順に従ってアカウントを認証します。
メニュ -> Power-Up -> RedSync Settings -> アカウントを認証 -> 認証-> 許可
4.2.設定
このセクションで行う設定には下記が必要になります。
- RedSyncをインストールしたボードの管理者権限
次の手順に従って設定を開始します。
メニュー -> Power-Up -> RedSync Settings -> Power-Upの設定を編集
設定画面が表示されます。上部のタブで基本設定と拡張設定を選択します。
基本設定
Redmineの設定
サーバー
RedmineサーバーのURLを指定します。 (HTTPS必須)
JSONPでアクセスする
RedmineにアクセスするAPIとしてJSONPを使います。CORSに未対応のRedmineサーバーでもTrelloと連携できます。ただしTrelloからRedmineへの更新はできません。該当する設定項目が選択できなくなり、⛔が表示されます。
Proxy経由でアクセスする (プロ版)
RedSync Proxy経由でアクセスします。CORSに未対応のRedmineサーバーでもTrelloと連携できます。RedmineにアクセスするAPIとしてRESTを使います。
APIキー
RedmineのAPIキーを登録します。
ここで登録したAPIキーは、Redmineと同期で、カードとチケットの同期に使われます。このため、チケットの内容を更新できる権限を持っている必要があります。(例: プロジェクトにDeveloperやManagerのロールでアサイン)
検証ボタンを押すことで、APIキーに紐づいたアカウントの氏名が表示されます。
APIキーの取得については、次を参照してください。
参照: Redmine APIキーの取得
プロジェクト
Trelloと連携するプロジェクトを選択します。
編集*
上記のフィールドを変更するためにクリックします。
* 状況に応じて表示されます。一度サーバーとプロジェクトを設定すると、RedSyncはそれらの編集をロックします。変更するには、編集ボタンを押してロックを解除します。
プロジェクトが変更されると、RedSyncは、同期済みのカードをアーカイブまたは指定されたリストに移動し、新たに指定したプロジェクトのチケットからカードを作成します。
サーバーを変更する際には、事前に同期済みのカードを削除しておく必要があります。これは新しいサーバーに、同じIDを持つプロジェクトやチケットが存在する場合があり、同期処理が正しく行われないためです。
タイムゾーン
Redmineサーバーのタイムゾーンを選択します。
開始時間
チケットの開始日に適用する時間を選択します。
終了時間
チケットの期日に適用する時間を選択します。
Redmineは、開始日及び期日に時間を含まず、タイムゾーンを持ちません。一方、Trelloは、開始日および期日に時間を含み、タイムゾーンを持ちます。RedSyncは、Redmineの開始日・期日をTrelloの開始日・期日に変換する際に、上記のタイムゾーンと時間の設定を使用します。
Redmineと同期の設定
メニューのRedmineと同期を実行するための設定を行います。
新規カードの作成先リスト
新しいカードを作成するリストを選択します。作成されたカードは、他のリストに移動できます。
接続を解除されたカード
カードと同期したチケットが見つからない場合、またはチケットがプライベートの場合、RedSyncはカードとチケットの接続が解除されたと見なします。この場合、次の何れかの処理を行います。
アーカイブ: チェックした場合、対象のカードをアーカイブします。
リストに移動: チェックした場合、対象のカードを選択したリストに移動します。移動後は、リストメニューから一括してアーカイブすることができます。
RedSyncは、アーカイブされたカードを削除するためのツールを提供しています。
参照: アーカイブ管理
終了したチケットのカードをアーカイブ (又はリストに移動)
チェックした場合、RedSyncは終了したチケットをアーカイブ (またはリストに移動) します。
他のプロジェクト管理者がRedmineの同期を実行できる
チェックした場合、この設定を行った管理者以外の管理者も、メニューからRedmineと同期を実行できます。チェックしない場合は、他の管理者による同期は実行できません。
複数のユーザーが、Redmineと同期を同時に実行すると、同期が正しく行われない可能性があります。このためデフォルトでは、Redmineと同期を実行できるユーザーを、設定を行った管理者に限定しています。他の管理者による実行を許可することもできますが、実行時には他に同期を実行しているユーザーがいないことを確認するように求められます。
カードのタイトルにチケット番号を含める
チェックした場合、カードのタイトルの前にチケットの番号を付加します。この設定と、次のRedmineと同期でカードからチケットに同期の題名の設定は、排他的な関係になります (どちらか一方のみがチェック可能です)。
Redmineと同期でカードからチケットに同期
- 題名
- 説明
チェックした場合、RedSyncは対象の項目をカードからチケットに同期します。チェックしない場合、チケットからカードに同期します。どちらの場合も、もし同期先で変更が行われていた場合は上書きされます。
カードの同期の設定
カード上でRedmineとデータを同期するカードの同期に関する設定を行います。
共有APIキー
Redmineから取得したAPIキーを指定します。
共有APIキーは、RedSyncからRedmineのAPIにアクセスする際に、アカウントリンクに個別APIキーが設定されていない場合に使用されます。APIキーの取得方法、個別APIキーと共有APIキーの違いについては、次を参照してください。
参照:
APIキーの取得方法
個別APIキーと共有APIキーの違い
カード上で編集可能 (プロ版)
チェックした場合、対象の項目をカード上で更新できます。それ以外の項目は、読み取りのみ可能となります。
- ステータス
- 進捗
- トラッカー
- 優先度
- カテゴリー
これらの項目は、Redmineのワークフロー及びロールと権限による制約を受けます。上記の設定で編集可能になっていても、Redmineは変更を拒否する場合があります。
拡張設定
スタンダードフィールド
Redmineのチケットに標準で定義されている属性と、Trelloのカスタムフィールド間の同期を定義します。同期方向はRedmineからTrelloになります。
| Redmineの標準属性 | Trelloのカスタムフィールドの種類 |
| status tracker progress priority category id (チケット番号) assignee | Text |
RedSyncは、デフォルトでもスタンダードフィールドを、カードのRedmineデータに表示します。しかしRedmineデータに表示されたスタンダードフィールドは、Trelloからは認識されません。このため絞り込み、ワークフローのトリガー、リスト上の表示といった目的には使えません。カスタムフィールドとマッピングすれば、Trelloから認識され、上記のような目的に使えるようになります。
カスタムフィールド – RedmineからTrello
RedmineのカスタムフィールドからTrelloのカスタムフィールドへの同期を定義します。
| Redmineのカスタムフィールドの種類 | Trelloのカスタムフィールドの種類 |
| Link | Text |
| User | Text |
| List | Text |
| Key Value | Text |
| Long Text | Text |
| Text | Text |
| Bool | Text | Checkbox |
| Date | Text | Date |
| File | Text |
| Float | Text | Number |
| Integer | Text | Number |
| Version | N/A |
ドロップダウンには、Redmineのカスタムフィールドのうち、チケットに紐付けられたものが表示されます。ドロップダウンには、現在のプロジェクトに紐付けられていないものも表示されるため、注意が必要です。(RedmineのAPIの制約のため)
カスタムフィールド – TrelloからRedmine (プロ版)
| Trelloのカスタムフィールドの種類 | Redmineのカスタムフィールドの種類 |
| Text | Text |
| Dropdown | Text |
| Number | Text |
| Checkbox | Text | Bool |
| Date | Text | Date |
ドロップダウンには、Redmineのカスタムフィールドのうち、チケットに紐付けられたものが表示されます。ドロップダウンには、現在のプロジェクトに紐付けられていないものも表示されるため、注意が必要です。(RedmineのAPIの制約のため)
4.3.Redmineと同期
プロジェクト管理者は、カードとチケットの同期を、次の手順に従って開始します。
メニュー -> Redmineと同期
RedSyncは同期を実行し、その経過を表示します。
同期中に、RedSyncは次のような操作を行います。
- Redmineに新規のチケットがある場合、新しいカードを作成
- カードとチケットの同期が解除されている場合、Redmineと同期の設定により
- アーカイブが選択されていた場合はアーカイブ
- リストに移動が選択されていた場合は、指定されたリストに移動
- 開始日/期日
- 常にチケットからカードに同期
- 名前 / 説明
- Redmineと同期の設定により
- カードからチケットに同期がチェックされている場合、カードからチケットに同期
- チェックされていない場合、チケットからカードに同期
- Redmineと同期の設定により
プロジェクト管理者は、次の条件を満たす場合に、この操作を実行できます。
- ボードの管理者である、かつ
- 設定を行った本人である、または他のプロジェクト管理者がRedmineと同期を実行できるがチェックされているとき
設定を行ったプロジェクト管理者と、Redmineと同期の実行者が異なる場合は、RedSyncは「もし複数の同期が同時に実行された場合、カードとチケットの内容に不整合が生じる恐れがある」との警告をだします。プロジェクト管理者が、他に同期処理が行われていないことを知っている場合は、同期処理を実行できます。
4.4.制約事項
カードの数
ボードあたりのカードの数は5,000個に制限されています (アーカイブされたものは除く)。もしRedmineのプロジェクトに、5,000個を超えるチケットが存在する場合、Redmineと同期の処理が失敗する場合があります。その場合は、次の対策を検討してください。
- 設定で、終了したチケットのカードをアーカイブをチェックする。(これにより終了状態のチケットに対しても、新しいカードが作成されないようになります)
- プロジェクトをサブプロジェクトに分割し、それぞれのサブプロジェクトを別のボードに同期する。
チケットの関連の数
チケットには他のチケットとの関連 (先行、後継、ブロック、子供、…) を定義できます。この関連の最大数は、チケットごとに30個以下に収めてください。
5.プロジェクトメンバーガイド
5.1.アカウントリンク
プロジェクトメンバーは、RedmineのAPIキーを登録する必要があります。ただし、Redmineのアカウントを持っていない場合は、この処理はスキップできます。(プロジェクト管理者にスキップして良いかどうか確認してください)
次の手順に従ってアカウントリンクの入力を開始します。
メニュー -> アカウントリンク
アカウントリンクの登録画面が表示されます。
ここで登録したAPIキーは、カードの同期でRemineデータセクションの項目を、読み取ったり更新したりするために使われます。チケットの読み取りや更新に対する、適切な権限を持っている必要があります。
検証ボタンを押すことで、APIキーに紐づいたアカウントの氏名が表示されます。
APIキーの取得については、次を参照してください。
5.2.カードの同期
RedSyncはTrelloのカード上に、Redmineデータセクションを表示します。
このセクションには、Redmineのチケットから取得された次の情報が表示されます。
- トラッカー
- ステータス
- 優先度
- カテゴリー
- 進捗
設定によって、これらの項目は更新可能になります。ただし、APIキーに紐づいたRedmineのワークフロー、ロールと権限の設定によって、変更が禁止されている場合があります。そのような場合、変更は拒絶され変更前の値に戻ります。
このセクションは次のリンクも含みます。リンクはRedmineのチケット間に定義されたものです。定義によってリンクが存在しない場合もあります。
- 親チケット – 親チケットのカードを開きます
- 子チケット – 子チケットのカードを開きます
- 関連チケット – 関連するチケットのカードを開きます
- チケット – このカードに対応するチケットをRedmineで開きます
また次の項目についてもカード上は変更が可能です。しかしRedmineと同期を実行した時に、設定によってチケットの内容で上書きされる場合があります。
- カードの名前 (タイトル) – 設定によりカードを上書き、又はチケットを更新
- 説明 – 設定によりカードを上書き、又はチケットを更新
- 開始日 – 常にカードを上書き
- 期日 – 常にカードを上書き
5.3.リストの並べ替え
リストのカードを優先度によって並べ替えることができます。
5.4.作業時間の報告
プロジェクトメンバーは、カードから作業時間を報告することができます。
- プロ版 – 作業時間の作成、変更、表示、削除ができます。ただしRedmineのユーザーとしての権限によっては、これらの操作が許されない場合があります。
- フリー版 – 作業時間の表示ができます。
作業時間を報告するには、カードのメニューから時間を記録をクリックします。
次のようなダイアローグが表示されます。
変更をクリックすると次のような編集画面が表示されます。
6.システム要求
Redmine
バージョン: 4.1, 4.2, 5.0
プロトコル:
- HTTPS (必須)
- CORS (Cross-Origin Resource Sharing) (オプション) (こちらを参照)
Redmineサーバーは、利用環境のブラウザからアクセスできる必要があります。(RedmineのWebインタフェースを使える必要はありませんが、RedSyncがブラウザ内からRedmineサーバーにアクセスできる必要があります。)
RedmineのHTTPSやCORS対応については、下記の記事もご参照ください。
ブラウザ
テスト済み: Chrome, Firefox, Safari, Edge
7.サポート
RedSync Power-Upは「現状のまま (as-is) 」での提供とさせて頂きます。
質問、不具合などはGuithub上でご連絡頂ければ、可能な範囲で対応させて頂きます。
ご要望についても上記でお知らせ頂けると幸いです。
8.付録
8.1.Redmine APIキーの取得
次の手順に従ってRedmineのAPIキーを取得します。
個人設定 -> APIアクセスキー -> 表示
8.3.アーカイブ管理
通常、アーカイブされたカードを削除する必要はありません。Trelloはアーカイブされたカードを保持できる十分な容量を提供しています。ただし、アーカイブしたカードを回復したくない場合など、カードを削除したい場合もあるかも知れません。
アーカイブ管理は、アーカイブされたカードを、一括で削除します。
アーカイブ管理を使用するには、次の手順でアーカイブ管理を有効化します。
メニュー -> Power-Ups -> RedSync Settings -> Power-Up設定の編集
表示された設定画面の下部に、メンテナンススイッチが表示されるので、オンにします。
これによりメニューにアーカイブ管理メニューが表示されます。
メニューからアーカイブ管理を起動して、カードを削除します。削除できるのは、RedSyncにより作成されたカードのみです。
8.4.Redmineと同期 vs. カードの同期
RedSyncは、TrellのカードとRedmineのチケットを同期します。この同期にはRedmineと同期とカードの同期の２種類があります。
- Redmineと同期 – メニューから実行します。バッチ処理になります。
- カードと同期 – カード上でリアルタイムに同期します。カードを開いた状態で編集した場合になります。
それぞれの同期処理で同期される項目を下記に示します。
| 項目 | Redmineと同期 | カードの同期 |
| カード | ||
| カードの作成 | ○ | |
| カードのアーカイブ | ○ | |
| カードの項目 | ||
| スケジュール | ○ | |
| 完了フラグ | ○ | |
| 名称 | ○ | |
| 説明 | ○ | |
| Redmineデータ (カード上のセクション) | ||
| トラッカー | ○ | |
| ステータス | ○ | |
| 進捗率 | ○ | |
| 優先度 | ○ | |
| カテゴリー | ○ | |
| 親チケット | ○ | |
| 子チケット | ○ | |
| 関連チケット | ○ | |
