Backlog

移⾏ツール

本移⾏ツールを⽤いて、課題やWikiを別のスペースへ移⾏できます。同⼀スペースでプロジェクトを分けたいときにもご利⽤できます。

必須要件

実⾏環境の実⾏可能 jar ファイルを実⾏できる
コマンドラインで簡単なコマンドを実⾏できる
移⾏元のスペースの管理者である、もしくは移⾏元プロジェクトのプロジェクト管理者である[ プロジェクト管理者の設定 ]1. Java 8
2. Java3.
4.

https://support-ja.backlog.com/hc/ja/articles/360036147813
5.

移⾏先のスペースの管理者である

任意要件の[課題⼀覧の取得]のクエリパラメータを作ることができる（移⾏する課題を絞り込みたいときのみ必要）[ 課題⼀覧の取得 ]1. Backlog API

https://developer.nulab.com/ja/docs/backlog/api/2/get-issue-list/

ダウンロード以下から最新版の jar ファイルを、お⼿元の環境に ダウンロードしてください。
https://backlog.com/ja/backlog-migration/releases.html

以下のコマンドでヘルプが表⽰されるかお試しください。
java -jar backlog-migration-<latest version>.jar

前準備1.

移⾏先と移⾏元 両⽅のスペースで、API キーを⽣成します。
[ APIの設定 ]https://support-ja.backlog.com/hc/ja/articles/360035641754

2.

作業⽤のディレクトリ(ここではworkとします)を作成し、jar ファイルを移動します。

Mac$ mkdir work
$ cd work$ mv

ダウンロードディレクトリ/backlog-migration-[latest version].jar .

Windowsc:¥> md workc:¥> cd workc:¥work> move

ダウンロードフォルダ¥backlog-migration-[latest version].jar .

プロキシ設定を確認します。プロキシ経由で使⽤する場合はコマンドを以下のように指定します。
3.

java \-Djdk.http.auth.tunneling.disabledSchemes= \-Dhttps.proxyHost=[/IP-Dhttps.proxyPort=[] \-Dhttps.proxyUser=[] \-Dhttps.proxyPassword=[] \-jar backlog-migration-[latest version].jar ...

プロキシサーバのホスト名 アドレス] \ポート番号
プロキシユーザー名
プロキシパスワード

移⾏

移⾏先プロジェクトの作成
新しいプロジェクトに移⾏される場合は、あらかじめプロジェクトを作成してください。
[ プロジェクトの追加 ]1.

https://support-ja.backlog.com/hc/ja/articles/360036147913

初期化
init コマンドを実⾏し、マッピングファイルを準備します。本移⾏ツールでは、移⾏元のユーザーを移⾏先に追加するのではなく、マッピングファイルを⽤いて移⾏元と移⾏先のユーザーを紐付けています。

2.

java -jar backlog-migration-[latest version].jar \init \--src.key [API] \--src.url [https://ID.backlog.jp] \--dst.key [API] \--dst.url [https://ID.backlog.jp] \--projectKey [:移⾏元の キー
移⾏元のスペース
移⾏先の キー
移⾏先のスペース
移⾏元のプロジェクトキー 移⾏先のプロジェクトキー]以下のオプションは必須です。
--src.key--src.url--dst.key--dst.url--projectKey

init

前準備で作成した移⾏元のAPIキー
移⾏元のBacklog URL
前準備で作成した移⾏先のAPIキー
移⾏先のBacklog URL
移⾏元のプロジェクトキー、移⾏先のプロジェクトキーの順番でコロンを挟んで指定してください例）--projectKey SRC_PRJCT:DST_PRJCT
移⾏元と移⾏先のプロジェクトキーが⼀致する場合以下のように省略可能です。
例）--projectKey PRJCT

コマンドを実⾏すると、以下のようなディレクトリとファイルが⽣成されます。

実⾏ディレクトリ/├ mapping/│ ├ users.csv│ └ users_list.csv└ log/├ backlog-migration-warn.log└ backlog-migration.log
mapping/users.csv

mapping/users_list.csv

log/backlog-migration-warn.log

ユーザのマッピングファイルです。下記「マッピングファ
イルの修正」で使⽤します。
設定可能なユーザの⼀覧です。下記「マッピングファイルの修正」で使⽤します。
ログファイルです。init や execute 処理で致命的ではない警告ログが出⼒されます。

log/backlog-migration.log

ログファイルです。init や execute 処理の内容が追記出⼒されます。

マッピングファイルの修正
users.csvはcsv形式で出⼒されるテキストファイルです。 Destination Backlog usernameの項⽬を、users_list.csvのName列から取得してください。すでに移⾏元のスペースから削除された等のユーザアカウントである場合は、サンプルユーザを移⾏先に登録し、移⾏作業が終わった後、そのアカウントを削除してください。
サンプル

3.

●

users_list.csv"Name","Email""user001","user001@example.com""user002","user002@example.com"●

users.csv"Source Backlog user id","Source Backlog user display name","Source Backlog useremail","Destination Backlog user name""test001","001","test001@test.com","user001""test002","002","test002@test.com","user002"

テスト
テスト

4.

移⾏

コマンドを実⾏すると、課題とWikiがインポートされます。移⾏元の課題やWikiが削除されることはありません。
execute$ java -jar backlog-migration-<latest version>.jar \execute \--src.key [API] \--src.url [https://ID.backlog.jp] \--dst.key [API] \--dst.url [https://ID.backlog.jp] \--projectKey [:移⾏元の キー
移⾏元のスペース
移⾏先の キー
移⾏先のスペース
移⾏元のプロジェクトキー 移⾏先のプロジェクトキー]以下のオプションは必須です。
--src.key--src.url--dst.key--dst.url--projectKey

前準備で作成した移⾏元のAPIキー
移⾏元のBacklog URL
前準備で作成した移⾏先のAPIキー
移⾏先のBacklog URL
移⾏元のプロジェクトキー、移⾏先のプロジェクトキーの順番でコロンを挟んで指定してください例）--projectKey SRC_PRJCT:DST_PRJCT
移⾏元と移⾏先のプロジェクトキーが⼀致する場合以下のように省略可能です。
例）--projectKey PRJCT

また、以下のオプションでカスタマイズできます。
--fitIssueKey--importOnly--exclude

可能な限り課題番号を⼀致させます。課題詳細やコメント、Wiki に課題番号を記載している場合はこのオプションを指定することで、リンク切れを回避できます。
移⾏先プロジェクトが既存のプロジェクトの場合は使⽤することはできません。
前回出⼒したファイルからインポートのみ実⾏します。
課題やWikiを移⾏しないよう制御できます。値は issue もしくは wiki です。
--exclude wiki--exclude issue--retryCount

なんらかのエラーが発⽣したときの再試⾏回数を指定します。このパラメータを指定しなかったときの再試⾏回数は20回です。

応⽤1：移⾏する課題のフィルタリング
移⾏元のプロジェクトの課題をフィルタリングして、移⾏することができます。
フィルタリングの指定⽅法は、Backlog API v2の課題⼀覧の取得APIのクエリとほぼ同じです。
[ 課題⼀覧の取得 ]https://developer.nulab.com/ja/docs/backlog/api/2/get-issue-list/

コマンドでオプション--filterを指定してください。(initコマンドでは使⽤できませんのでご注意ください。) 例として、⽐較的よく使われそうなフィルタリングオプションを以下の表に⽰します。詳細は上記の「課題⼀覧の取得」ページをご確認ください。
オプション指定例型
内容--filter "issueTypeId[]=1&
数値 種別のIDでフィルタリングします。ID がわからない
issueTypeId[]=2"
場合は、Backlog をブラウザで開き、プロジェクト設定＞種別の⼀覧画⾯で、種別名にカーソルを合わせるとEditIssueType.action?issueType.id=xとリンクが表⽰されます。issueType.idの値を指定してください。
複数指定したい場合は、オプション指定例のように、複数のissueTypeId[] を&で連結してください。
--filter
数値 カテゴリーのIDでフィルタリングします。ID がわか"categoryId[]=99&categoryId[らない場合は、Backlog をブラウザで開き、プロ]=98"
ジェクト設定＞カテゴリーの⼀覧画⾯で、カテゴ
リー名にカーソルを合わせるとEditComponent.action?component.id=xとリンクが表⽰されますcomponent.idの値を指定してください。
--filter "id[]=123&id[]=456"
数値 課題のIDでフィルタリングします。
移⾏に失敗した課題が明確な場合、その課題の移⾏のみをリトライしたい時に指定すると便利です。
--filter "offset=1000"
数値 課題のオフセットです。
移⾏する課題が⼤量にある場合、時間を要するため、このオプションで分割して移⾏されることをお勧めします。
--filter countと組み合わせてご利⽤ください。
例）1件⽬から100件移⾏したい場合
execute--filter “offset=0&count=100”

例）1001件⽬から100件移⾏したい場合--filter “offset=1000&count=100”--filter "count=100"

数値

課題の移⾏最⼤数です。
--filter offsetと組み合わせてご利⽤ください。

再移⾏時の重複チェック「課題を登録したユーザID」、「課題の登録時間」、「課題の件名」が全て⼀致する場合は、すでに移⾏された課題として、重複して移⾏されることはありません。何らかのエラーで移⾏が途中で終了し、再度 execute が必要なとき等に有益な重複チェックです。
「Wikiのページ名」が⼀致する場合は、すでに移⾏されたWikiとして、重複して移⾏されることはありません。再度 execute する際に有益な重複チェックです。

ログファイル
本移⾏ツールのディレクトリ構造は以下の通りです。ログファイルはlogディレクトリ内に⽣成されます。
実⾏ディレクトリ/├ mapping/│ ├ users.csv│ └ users_list.csv└ log/├ backlog-migration-warn.log└ backlog-migration.log

制限事項
親課題を変更後にプロジェクトキーを変えた場合、移⾏元では親課題の変更を反映できません。
2. 過去に存在した課題種別は移⾏中に⾃動作成されます。移⾏完了後、必要に応じて⼿動で削除してください。
3. 課題やwikiに付けられたスターは移⾏されません。
4. 数値のカスタム属性に単位を設定している場合、コメントの変更履歴にある単位は移⾏されません。
5. 移⾏元と移⾏先が同⼀プロジェクトは移⾏できません。
6. fitissuekeyとfilterオプションは同時に使⽤できません。
7. 移⾏元と移⾏先に同名のカスタム属性が存在する場合、移⾏先のデータに不整合が発⽣する可能性があります。実⾏する前に事前のチェックをお願いします。
8. グローバル検索のインデックスは移⾏されません。
9. ASPからエンタープライズには移⾏できません。
10. 2020/12 現在、M1プロセッサ搭載のMacBookでは動作未検証のため動作を保証できません。
11. 移⾏元もしくは移⾏先がフリープランの場合はAPIのレート制限により移⾏できません。
12. 本移⾏ツールの並列実⾏は、APIのレート制限を超える可能性があるため動作を保証できません。
13. 別のスペースに移⾏する際、Wiki の画像表⽰ダグをIDで表⽰している場合は画像は表⽰されません。
14. 「状態を追加」「状態名の変更」を9回以上おこなったプロジェクトは移⾏できません。
1.

下位プランへの移⾏の際の注意点
下位プランへの移⾏の際、プロジェクト数、ユーザー数、添付できるファイルの数、添付できるファイルのサイズなどプランによる制限があります。Backlog移⾏ツールはこちらの制限を超えて移⾏することはできませんのでご注意ください。
プランごとのファイルに関する制限