JootoからBacklogへの移行ツール

本移行ツールを用いて、Jootoのデータを、Backlogのプロジェクトに移行できます。

移行ができるデータ
必須要件
- 移行時に必要な情報
移行ツールのダウンロード
- Windows の場合
- macOS の場合
移行の手順
移行するデータ量が多い場合
- 一部のデータを移行対象から除外する
チェックリストを課題の詳細に書くか、子課題にするか
移行後にどうデータが置き換わるか
オプション
JootoのAPIレート制限
うまくいかないとき
エラーが発生し、移行ができないときは

移行ができるデータ

タスク
- 担当者
- タスクの件名、詳細
- 開始日、期限日
- 予定時間、実績時間
リスト
コメント
ラベル
チェックリスト
添付ファイル

必須要件

コマンドラインで簡単なコマンドを実行できる
Jootoの有料プランを利用している
移行先のBacklogスペースの管理者、またはプロジェクト管理者である

移行時に必要な情報

JootoのAPIキー

「組織」>「設定」>「その他」の項目にあるAPIキーの設定で設定ページから発行できます。Jooto APIは有料プランでのみ利用できます。

プロジェクト（ボード）のID

ボードのURLに含まれている数字です。

例：boardsに続く#の後ろの番号が、ボードのIDです。

https://app.jooto.com/boards#XXXXXX?organization_id=zzzzzz

管理者の権限を持つユーザーが発行したBacklogのAPIキー

移行先のプロジェクトを新規に作成する場合は、管理者の権限が必要です。
移行先のプロジェクトを既存のプロジェクトから指定する場合は、管理者、またはプロジェクト管理者ができます。BacklogのAPIキーの発行方法は新しいAPIキーを発行するを参照してください。

移行ツールのダウンロード

以下から、最新版の移行ツールをお手元の環境に併せてダウンロードしてください。

ダウンロード	対象	Java
backlog-migration-jooto-macos-aarch64.zip	Appleシリコン（M1以降）のmacOS	同梱
backlog-migration-jooto-windows.zip	Windows	同梱

Windows の場合

backlog-migration-jooto-0.1.0-windows.zip をダウンロードし、そのZipファイルを展開して

ください。

展開後、ターミナル内にて展開したフォルダまで移動してください。

cd backlog-migration-jooto-0.1.0
bin./backlog-migration-jooto.bat --help

Windows 11 の場合

展開したフォルダ内に移動します。

※展開時に使ったアプリケーションによって同じフォルダ名が入れ子になっていることが

あるので、その際は再度同名フォルダ内へ移動します

次に、ウィンドウ内の何もないところで右クリックをするとメニューが展開されるので、その

中から「ターミナルで開く」を実行します。

Windows 10 の場合

デスクトップ左下の検索バーをクリック、“cmd”と入力し、検索結果に表示される「コマンド

プロンプト」をクリックして起動します。

上記展開したフォルダまで移動します。

binフォルダーにあるbacklog-migration-jooto.batを実行し、ヘルプが表示されるかお試しください。

macOS の場合

backlog-migration-jooto-0.1.0-macos-aarch64.zip をダウンロードし、そのZipファイル

を展開してください。

展開後、Terminal.app ターミナル内にて展開したフォルダまで移動してください。

※展開時に使ったアプリケーションによって同じディレクトリ名が入れ子になっていることがあります。その際は再度同名ディレクトリ内へ移動してください。

ターミナルにて以下のコマンドでヘルプが表示されるかお試しください。

cd backlog-migration-jooto-0.1.0
bin/backlog-migration-jooto --help

なお、このツールは実行したディレクトリにbacklog/、mapping/、log/が作成されます。

移行の手順

0. ユーザーをBacklogに招待する

移行ツールを実行する前に、Backlogにユーザーを招待しましょう。

移行を進めるため、CSV で一括でユーザーを招待する方法をお勧めします。招待が完了したら、その際、移行先のプロジェクトにユーザーを追加するために「チーム機能」を利用しましょう。

手順としては、以下のとおりです。

1. ボードを読み込む

以下のコマンドを実行してください。

以下の内容は、お客さまの情報に置き換えて実行ください。

<YOUR_JOOTO_API_KEY>
<YOUR_JOOTO_BOARD_ID>
<YOUR_BACKLOG_SPACE>
<YOUR_BACKLOG_API_KEY>
<YOUR_BACKLOG_PROJECT_KEY>

Windows

bin./backlog-migration-jooto export ^
  --jooto.key     <YOUR_JOOTO_API_KEY> ^
  --jooto.boardId <YOUR_JOOTO_BOARD_ID> ^
  --backlog.url   https://<YOUR_BACKLOG_SPACE>.backlog.com ^
  --backlog.key   <YOUR_BACKLOG_API_KEY> ^
  --projectKey    <YOUR_BACKLOG_PROJECT_KEY>

Mac

bin/backlog-migration-jooto export \
  --jooto.key     <YOUR_JOOTO_API_KEY> \
  --jooto.boardId <YOUR_JOOTO_BOARD_ID> \
  --backlog.url   https://<YOUR_BACKLOG_SPACE>.backlog.com \
  --backlog.key   <YOUR_BACKLOG_API_KEY> \
  --projectKey    <YOUR_BACKLOG_PROJECT_KEY>

Jootoのプロジェクトと、Backlogのプロジェクトを紐づけるため、4つのcsvファイルが出力されます。

mapping/users_list.csv
mapping/users.csv
mapping/statuses_list.csv
mapping/statuses.csv

2. マッピングファイルを記入する

1の手順で出力された2つのマッピングファイルに、それぞれ以下を記載します。

mapping/users.csv

jootoのユーザーとBacklogのユーザーを紐づける作業です。BacklogユーザーIDの列を必ず記入する必要があります。BacklogユーザーIDに指定する値は「mapping/users_list.csv」から指定してください。

指定方法

users_list.csv内の「Name」の記載を、users.csvの「Backlog user id」に紐づけます。

例

Jootoの登録ユーザーであるAさんを、Backlogの登録ユーザーであるBさんと紐付ける

users_list.csv

Name,Email
*XXXXXXXXX,b@nulab.com

users.csv

Jooto user id,Jooto user name,Jooto user email,Backlog user id
507191,a,a@nulab.com,*XXXXXXXXX

Jooto上で削除したユーザーは「退会したユーザー」という名称でusers.csvに出力されます。そのため、すでにJooto上には存在しないユーザーについても、データを移行するために紐づけるユーザーを設定してください。

mapping/statuses.csv

Jootoで利用していたリストと、Backlogの「状態」を紐づける作業です。csv内の「Backlog status name」に、紐付けたいBacklogの「状態」の名称を記載してください。デフォルトでは、Jootoで使用していたリスト名と同じ「状態」が作成され指定されています。以下のBacklogのデフォルトの状態に置き換えることも可能です。

未対応
処理中
処理済み
完了

置き換え先として指定する値は「mapping/statuses_list.csv」から指定してください。

例

Jootoで利用していた「リスト」という名称のリストに、Backlogの「未対応」の状態を紐付ける。

statuses_list.csv

Name
未対応
処理中
処理済み
リスト

statuses.csv

Jooto list id,Jooto list name,Backlog status name
xxxxxx,リスト,未対応

・Backlogのプロジェクトで追加できる「状態」の上限は8個です。デフォルトの状態は削除できません。
・リストが多い場合、リスト名をまとめる必要があります。対処方法については、状態が多すぎて入らないを参照してください。

3. Backlogに書き込む

以下のコマンドを実行し、Backlogにデータの移行を開始します。

以下の内容は、お客さまの情報に置き換えて実行ください。

<YOUR_JOOTO_API_KEY>
<YOUR_JOOTO_BOARD_ID>
<YOUR_BACKLOG_SPACE>
<YOUR_BACKLOG_API_KEY>
<YOUR_BACKLOG_PROJECT_KEY>

Windows

bin./backlog-migration-jooto import ^
  --backlog.url  https://<YOUR_BACKLOG_SPACE>.backlog.com ^
  --backlog.key  <YOUR_BACKLOG_API_KEY> ^
  --projectKey   <YOUR_BACKLOG_PROJECT_KEY>

Mac

bin/backlog-migration-jooto import \
  --backlog.url  https://<YOUR_BACKLOG_SPACE>.backlog.com \
  --backlog.key  <YOUR_BACKLOG_API_KEY> \
  --projectKey   <YOUR_BACKLOG_PROJECT_KEY>

移行するデータの確認が求められるため、承認してください。

承認するとプロジェクトが作成され、データの移行が開始されます。

移行するデータ量が多い場合

データ量が多い場合や、移行する必要がないデータがある場合、移行対象のデータを除外することをご検討ください。また、データ量が多い場合、移行に時間がかかる可能性もあります。あらかじめご留意ください。

一部のデータを移行対象から除外する

--excludeコマンドを利用して、移行対象からデータを除外することができます。除外対象として指定できるデータは以下のとおりです。

コメント (comment)
チェックリスト (checklist)
添付ファイル (attachment)
アーカイブしたタスク (archived)

例

--exclude comment

項目を「,」で区切ることで、複数指定することもできます。

アーカイブしたタスクに関して

Backlogにはjootoのアーカイブと同じ機能がありません。そのため、アーカイブ済みのJootoタスクを除外せずに移行した場合、以下の内容でタスクが移行されます。Jootoでアーカイブしたリストに含まれているタスクも同様です。

「状態」：完了
「カテゴリー」：アーカイブ

チェックリストを課題の詳細に書くか、子課題にするか

Backlogにはjootoのチェックリストと同じ利用が可能な機能がありません。そのため、課題の詳細にチェックリスト記法で記載するか、チェックリストに記載されていた内容を子課題で登録するかを--checklistで指定します。

--checklist description   # 既定値
--checklist childIssue

課題の詳細にチェックリスト記法で記載する場合

descriptionを使用します。項目のチェックは引き継がれ、項目ごとの担当者と日付も同じ行に書き出されます。タスクは1つの課題のままです。

子課題に移行する場合

childIssueを使用します。チェック済みの項目は完了の「状態」が指定された状態で作成されます。チェックリストの項目分、課題が作成されることをご認識の上実行してください。

移行後にどうデータが置き換わるか

Jootoで利用していた各データがBacklogのどこに移行されるかは、以下の表で確認してください。

Jooto	Backlog
プロジェクト（ボード）	プロジェクト
リスト	状態（手順2で割り当てたもの）
タスク	課題
コメント	コメント（登録者と投稿時刻を保持）
ラベル	カテゴリー
チェックリスト	詳細のテキスト、または項目ごとの子課題
添付ファイル	添付ファイル ※同じ名前の添付ファイルが同じタスクやコメントにある場合、2つ目以降は image (2).png のように番号付きの名前で移行されます。大文字と小文字だけが違う名前も同じ名前として扱われます。
担当者	課題の詳細に担当者全員が記載されて移行されます。データを出力した際にデータ内に表示されている順番に@メンション付きで記載されます。最初に記載されている担当者が課題の担当者に設定されます。

移行するデータについて、以下ご了承ください。

作成日時と作成者は保持された状態で移行されます
課題の番号は引き継がれません。
Jootoにない設定項目である「課題種別」や「優先度」は自動で設定されます。
Jootoのデフォルトのラベルは、移行ツールを実施したマシンの言語設定により翻訳された名称で移行されます。
リストの変更履歴は引き継がれません。
Jootoでメンションを利用して行った通知は、Backlogに引き継がれます。そのため移行時に、紐づけたユーザーにメンションによる通知が送られます。もし通知を送りたくない場合は、テスト用のプロジェクトなどで移行を試してください。
子課題にするよう指定した場合を除き、親子関係はつきません。
見積時間と実績時間は、予定時間と実績時間として移行されます。

オプション

コマンドの実行に利用するオプションについて説明します。

オプション	コマンド	必須項目	用途
--jooto.key	export	必須	JootoのAPIキー。
--jooto.boardId	export	必須	ボードのURLに含まれる数字。
--jooto.url	export		Jooto APIのURL。既定はhttps://api.jooto.comです。テスト環境以外では指定不要。
--backlog.url	export import	必須	Backlogのスペース。https://YOUR_SPACE.backlog.comのような形式。
--backlog.key	export import	必須	BacklogのAPIキー。
--projectKey	export import	必須	作成するプロジェクトキー。半角英大文字、数字、アンダースコアが使えます。
--exclude	export		移行しないもの: comment、checklist、attachment、archived。
--checklist	export		チェックリストの移行方法: description（既定）またはchildIssue。
--retryCount	import		Backlogへの呼び出しが失敗したときの再試行回数。既定は3。
--disableSslVerify	export import		TLSサーバー証明書の検証を無効にします。下記参照。
--help、--version	export import		ヘルプまたはバージョンを表示して終了します。 export --help 、 import -- help はコマンドごとのオプションを表示します。

プロキシ環境では、JootoとBacklogの両方について、通常のhttps.proxyHostとhttps.proxyPortのシステムプロパティが使われます。

Windows

bin./backlog-migration-jooto ^
  -Dhttps.proxyHost=proxy.example.com ^
  -Dhttps.proxyPort=8080 ^
  export ...

Mac

bin/backlog-migration-jooto \
  -Dhttps.proxyHost=proxy.example.com \
  -Dhttps.proxyPort=8080 \
  export ...

--disableSslVerifyは、Javaが信頼していない証明書でTLSを終端するプロキシのためのオプションです。両方のサービスについて証明書の検証を完全に無効にするため、APIキーが検証されていない経路を通ることになります。正しい対処は、プロキシのCA証明書をJavaに登録することです。それができない場合にのみ、このオプションを使ってください。

JootoのAPIレート制限

スタータープランでAPIを利用する際に設けられている、1か月あたりのレート上限は緩和されていますが、データ量により時間がかかる可能性があります。レート制限により実行が難しい場合は、一部のデータを移行対象から除外するを参照して移行するデータ量を減らしてください。

うまくいかないとき

月間の上限に達して停止してしまった

上限に達してリクエストが停止した場合、Backlogへのデータ移行は行われていないため、リクエスト数が戻るまでお待ちください。

もしくは、一部のデータを移行対象から除外するを参照して移行するデータ量を減らしてください。

すでに登録済みのデータとして移行対象から除外された

登録済みの課題と同様の課題と判断された場合、以下のエラーが表示され、移行対象から除外されます。

課題 [JOOTO-XXXX]は、すでに登録されているため読み飛ばします。

同様の課題かどうかは、以下の内容をもとに判断されます。

件名が同じ
タスクの作成者が同じ
作成日時(秒単位）が同じ

もし登録したい課題が、上記のエラーで移行できない場合、新しいプロジェクトにあらためて移行してください。

状態が多すぎて登録ができない

Backlogの1つのプロジェクトに追加ができる「状態」の上限は8個です。mapping/statuses.csvで12個より多い状態が指定されている場合、データの処理は中止されます。

作成される「状態」の数が8個以内に収まるようファイルを編集してください。一部のJootoのリストを、Backlogのデフォルトの「状態（未対応、処理中、処理済み、完了）」に割り当てるか、複数のリストを同じ「状態」に割り当てることで、登録数を抑えることができます。

エラーが発生し、移行ができないときは

処理に失敗した場合は、エラーが返ります。移行ツールで返されるエラーについてはBacklog移行ツールでエラーが発生するを参照してください。

お問い合わせの際は以下を添えてご連絡ください。

log/backlog-migration-warn.log
log/backlog-migration.log
実行したコマンド（APIキーはマスキングしてください）