日本でのアトラシアン（Atlassian）製品導入No.1

こんにちは。リックソフトの大崎です。

今回の話は、ニッチかもしれませんがJiraプロジェクトを復旧・統合するときのお話をしたいと思います。
ちなみにデータ復旧のためにはバックアップがあることが前提です。バックアップは大事です。
本内容での環境は、Jira Server/DataCenterを想定しており、Jira CloudからのJira Server/DataCenterへの復旧・統合またはその逆については対象外となります。

さてJiraをしばらく利用していると、こんなことがあるかと思います。

• Jiraのあるプロジェクトの課題をアプリ（アドオン）の操作を誤って一括で削除してしまった
• Jiraを社内のいくつかの部署で使用しており、それらの環境を1つに統合してライセンスの支払い額を下げたい
• 開発プロジェクトが完了して、使用していたJiraを停止して、別のJira環境にその開発プロジェクトのデータを移行したい
• 会社が合併して、双方のJiraを1つに統合したい

など…

まずJiraの課題削除は物理削除となるため、バックアップから復旧することになります。
復旧方法としては、バックアップからプロジェクトをリストアする – アトラシアン製品ドキュメント （以降プロジェクトインポート機能とします）を使用することが一般的になっています。
プロジェクトインポート機能で使用するバックアップは、XML バックアップを指します。XML バックアップ機能は、実運用環境では停止することが推奨されていますので、別のバックアップ手段を取られているお客様が多いかと思います。
そのため、そのバックアップを本番環境とは別の環境にリストアしたうえで、XMLバックアップを手動で取得する必要があります。

プロジェクトインポート機能以外にCSV、JSONでのインポート機能もありますが、こちらも本番環境とは別の環境にリストアして、その環境から復旧したいデータのみをエクスポートして、本番環境にインポートすることになります。
CSVインポート機能では履歴がインポートされないなどのいくつか制限もありますが、今回CSVインポート機能についても触れていくと内容がぶれてしまうので別の機会に紹介したいと思います。

続いてJiraの環境を統合する場合ですが、Jiraには環境を統合する機能は存在しないため、プロジェクトインポート機能を使用してプロジェクト単位で統合します。
統合するプロジェクト数が複数の場合、インポート手順を何度か繰り返す必要があります。

プロジェクトインポート機能を使用してプロジェクト単位で復旧・統合できるのであれば、後は手順を確認すれば簡単かな？と思われたかもしれませんが…
以下にAtlassian社のドキュメント記載を一部引用しますが、それなりに難しく制限もあります。統合となると、より難易度はあがります。

バックアップからのプロジェクトの復元は簡単な作業ではありません。プロジェクトのインポートに対応するために、ターゲット Jiraインスタンスの構成を変更する必要があります。さらに、大規模なプロジェクトをインポートする場合、プロジェクトのインポートデータのマッピングは、ハードウェア上のリソースを大量に消費する可能性があり、完了するまでに長時間かかる場合があります。注：プロジェクト インポート ツールは実データのインポートの間、Jira インスタンスを閉塞させるため、ご利用のインスタンスがその間アクセスされる必要がないことを確認してください。

今回はドキュメントの内容をベースに弊社で実際に困ったときの注意点を追加して説明していきたいと思います。
必ず作業前にはドキュメントをご確認のうえ、検証を繰り替えして、本番作業の際には事前にバックアップを取得の上実施してください。
それでは具体的な作業方法に入る前に、前提条件、制限事項について説明していきます。

前提条件

１．Jiraの各環境のバージョンは同一であること、アプリ（アドオン）についても基本的には同じものが同じバージョンで導入されていること

復旧する場合は同一環境のバックアップのため、一致していないケースはないと思いますが、環境を統合する場合には対応が必要になるケースがあります。
バージョンが異なる場合、環境の新しいバージョンに合わせるまたはどちらの環境もバージョンアップして揃える必要があり、アプリ（アドオン）についても基本的には同じアプリ（アドオン）が導入されているかつ同一バージョンである必要があります。また統合元で導入しているアプリ（アドオン）を、統合先で導入していない場合、別途統合先にも導入する必要があります。環境で製品のライセンス数が異なるなどがありますと、ライセンスをアップグレードまたは別途購入する必要がございます。
ただしアプリ（アドオン）に関しては、導入しているアプリ（アドオン）によっては必ずしも揃える必要がない場合もありますのでご留意ください。基本的には、後々色々な問題が起きないように作業前に揃えておくことを推奨します。

２．プロジェクトを用意しておくこと（プロジェクトキーが衝突しないこと）

復旧または統合元と同じプロジェクトキーでプロジェクトをあらかじめ用意しておく必要があります。
もし同じプロジェクトキーがすでに存在する場合、プロジェクトの全課題を削除してコンポーネント、バージョンも消しておく必要があります。

プロジェクトを削除しますと、フィルター・ダッシュボードの共有設定でプロジェクトを指定している場合、その共有設定が消えますのでご注意ください（フィルター・ダッシュボード自体は消えプライベートになります）。

他にもアプリ（アドオン）によっては、プロジェクトとデータを結び付けているものがある場合、その設定が消えてしまう可能性もあります。これは、プロジェクト削除によってプロジェクトのIDが変わってしまうためです。
プロジェクトキーは変更可能なため、設定やアプリ（アドオン）では、ユニークなプロジェクトIDで保持しています。

課題キー（例：PJ-1234）は復旧前と変わりません。

もしプロジェクトの課題が復旧時点よりも進んでいて全課題が削除できなく、一部課題だけを復旧したいという場合ですと
バックアップを本番環境とは別の環境にリストアしたうえで、プロジェクトキーを変更するか、一時的なプロジェクトを作成してそこに対象課題を移動して、XMLバックアップを取得して
本番環境にも一時的なプロジェクトを作成して復旧して、本来のプロジェクトに課題を移動するといった手順になります。この手順の場合、課題キーは復旧前と違うものになりますのでご注意ください。

また統合の場合、統合先と統合元でプロジェクトキーがもし衝突した場合は、統合時に別のプロジェクトキーに変更するか、違うプロジェクトに課題を移動して統合する必要があります。

３．ユーザー、グループが揃っていること

復旧する場合は、同一環境のため影響はほぼないと思いますが、統合するときは考慮が必要な部分です。
プロジェクトインポート機能は、プロジェクトに関連付けられているユーザーが欠落している場合、そのユーザーを作成しようとします。
これは一見便利に見えるのですが、統合する場合、同一人物が各環境にすでに存在するが命名規則が異なりユーザー名が異なるケースがあったりします。
あちらの環境ではユーザー名がメールアドレスだが、こちらの環境ではログインIDなどのケースがあります。
その場合、事前に名寄せが必要になります。

名寄せをしないと、ユーザーが勝手に作られてしまいデータによって関連しているユーザー情報が異なる現象になります。
最悪の場合は同一人物で2ユーザー以上あるなど、ライセンスが無駄に消費されてしまうことにもなります。
名寄せの方法としては、ユーザーマッピング表を作成したうえで、バックアップを本番環境とは別の環境にリストアしたうえで、ユーザー名を変更して、XMLバックアップを取得して作業する必要があります。
ユーザー名の変更方法は基本的に管理画面から実施ですが、ユーザーが多い場合はREST API、アプリ（アドオン）などを使用することもあります。

ユーザー名を変更したときの影響としては、フィルターのJQLにおいてassigneeやreporterなどにユーザー名が指定されている場合、ユーザー名の変更が反映されないため検索エラーとなる可能性があります。
またコメントや説明などで過去メンションをしていた場合、ユーザー名を変更後に、変更前のユーザー名としてテキスト表示されてしまいます。

さらにグループですが、通知、権限、ワークフロー、カスタムフィールドの値などで使用していることもあり、事前に用意しておく必要があります。
統合する場合、統合元と統合先でグループ名が重複しており、お互いの権限付与者が異なる場合、異なるグループとしてグループ名の置換が必要になる場合があります。
たとえば、統合元と統合先で grp-hr というのが同じグループ名が存在しており、片方の環境ではHRという名前のプロジェクトのメンバーが入っており、片方の環境では人事部メンバーだとすると
単純にグループの設定を統合してしまうとHRプロジェクトのメンバーが、人事部の情報にまでアクセスができてしまう（逆もしかり）ことになる可能性もあります。

グループ名の置換方法ですが、グループ名の変更は製品の機能上できないため、残念ながら公式の手順はありません。手動で対応できる範囲であれば手動で設定修正、最悪DB操作などで対応する必要があります。

４．カスタムフィールドが揃っていること

カスタムフィールド名、カスタムフィールドタイプを合わせる必要があります。
復旧する場合は、同一環境のため影響はほぼないと思いますが、統合するときは考慮が必要な部分です。
統合先と統合元で同じカスタムフィールド名で違うカスタムフィールドタイプであった場合は、統合元で事前にカスタムフィールド名を変更しておく必要があります。
また環境の中でカスタムフィールド名が重複している場合は、インポート時にはフィールド名でチェックするため、事前にユニークになるようにカスタムフィールド名を変更しておく必要があります。

５．プロジェクトに設定する各種スキームなどの設定が揃っていること

プロジェクトに設定する以下の設定も揃えていく必要があります。復旧する場合は、同一環境のため影響はほぼないと思いますが、統合するときは場合によってはかなり面倒な部分です。

• 課題タイプスキームの設定
• 課題タイプ
• ステータス
• セキュリティレベル
• 優先度
• 解決状況
• 課題リンクタイプ
• プロジェクトロール
• ワークフロー・ワークフロースキーム各種設定
• カスタムフィールド・フィールド設定スキーム各種設定
• 権限・権限スキーム各種設定
• 画面・課題タイプスキーム各種設定
• 通知スキーム各種設定

統合の場合、課題タイプ、ステータス、解決状況、課題リンクなどを新規で作成するか、統合先に寄せるかなどを事前に検討しておく必要があります。
そのまま統合すると似たようなものが沢山作成されてしまいユーザーの利用に混乱をきたす場合があるためです。
ワークフローも基本的には同じ設定であることを推奨します。これはインポート時に各種ステータスなどの条件が一致している必要があるためです。
更に課題作成時の事後処理がトリガーされるため、課題作成時に何か特殊な事後処理を設定している場合はどの挙動が期待する結果であるか確認の上、設定をする必要があります。

ちなみにワークフローのXMLなどのインポート/エクスポート機能はありますが、こちらの機能も完全にインポートされるわけではないのでご注意ください。

ここまで設定出来たら、あとはプロジェクトインポート機能でインポートするだけと思いますが、プロジェクトインポート機能でも復旧・統合できない制限事項があります。

制限事項

この制限事項は環境や利用状況によってケースバイケースです。制限事項として足りていない場合もあると思いますので、あらためて検証の上ご利用の環境でどのような影響があるかチェックをしてください。

1. アプリ（アドオン）のデータは基本的に復旧、移行されません

基本的にアプリ（アドオン）のデータは復旧・移行できません。
ただし導入しているアプリ（アドオン）や設定状況などによっても異なり一概に制限に該当しないこともありますのであらためてご確認ください。
たとえばカスタムフィールドのアドオンで課題に値が設定されている場合、アプリ（アドオン）のデータの持ち方次第ですが復旧・移行されます。

2. プロジェクト インポート機能は、製品標準の使用している一部データがインポートされません

• インポートされるデータ：Jira Software のスプリント データやランキング データ
• インポートされないデータ：Jira Software のボード設定データおよび Service Desk カスタマーポータル

3. プロジェクトインポート機能の通り、ユーザーに紐づく設定（プロフィール設定、アイコン設定など）、ダッシュボード設定、フィルター設定、フィルター配信設定、ボード（カンバン、スクラム）設定 は移行できません

同一環境での復旧の場合は、基本的に設定が残っているためこの制限には該当しませんが、プロジェクトインポート機能はプロジェクトの課題情報（添付ファイルを含む）のみを復旧します。
フィルターやダッシュボードについて、統合先で統合作業のために課題タイプやカスタムフィールド名などを変更したりしますと、フィルターなどで指定しているJQLの検索が機能しなくなる場合（指定していた課題タイプ名が存在しないなどのエラー）がありますのでご留意ください。

４. Confluence、Bitbucket、Bambooなどアプリケーションリンクの連携設定

同一環境での復旧の場合は、プロジェクトを削除しない限り基本的に設定が残っているためこの制限には該当しません。
環境統合の場合、Jiraと連携している製品の設定情報などは復旧されませんので、統合元の連携を維持したい場合、統合先でも連携設定をする必要があります。
ちなみにConfluenceのWikiリンクはプロジェクトインポート機能で復旧されますが、もしConfluenceも同様に統合するなどで環境を移行した場合、リンクが表示されるもののページIDが変わりリンク切れになってしまう場合がありますのでご注意ください。
Bitbucket、Bambooについては、課題キーで連携しているため、プロジェクトキーを変更しなければ基本的には復旧・統合されます。

5. 統合先と統合元でサーバー・データベースのタイムゾーンが異なる場合、時間情報が正しく統合されません

同一環境での復旧の場合は影響ありませんが、統合先と統合元でサーバー・データベースのタイムゾーンが異なる場合、XMLバックアップではタイムゾーンを保持していないため、時間情報が正しく移行されない場合があります。

さて文字だけで疲れてきましたが、制限事項もクリアしたら、あとはプロジェクトインポート機能でインポートします。

作業方法

1. 復元・統合元環境：XMLバックアップを取得する

作業の前にカスタムフィールド名の変更、ユーザー名の名寄せなど事前に作業が必要な場合、XMLバックアップ取得前にあらかじめ実施しておきます。

Jira管理者権限のユーザーで 管理画面 > システム > システムをバックアップ にアクセスして、バックアップファイル名を指定して、「バックアップ」をクリックします。
大規模な環境ではこのバックアップに時間（数十分）がかかる場合がありますのでご注意ください。

無事取得が完了しますと、 (Jira ホームディレクトリ)/export/ファイル名.zip にXMLバックアップファイルが作成されます。

２．復旧・統合先環境：XMLバックアップと添付ファイルを復元・統合元環境からコピーする

必要な操作としては、 (Jiraホームディレクトリ)/import/ 以下に 1で取得したXMLバックアップを配置します。
加えて、(Jiraホームディレクトリ)/import/attachments/ に、 (Jiraホームディレクトリ)/data/attachments/ 以下にあるプロジェクトの添付ファイルをすべてコピーすることになります。
コピーする方法はいくつかあると思いますが、Linux環境でお互いの環境が直接通信できるのであればシンプルにrsyncなどで復旧・統合環境からコピーすればよいかと思います。
それぞれJira実行ユーザーがファイルを参照できる必要がありますので、ディレクトリ・ファイルの権限にはご注意ください。

$ rsync -avz  復元・統合元環境:(Jiraホームディレクトリ)/export/(ファイル名).zip  (Jiraホームディレクトリ)/import/
$ rsync -avz  復元・統合元環境:(Jiraホームディレクトリ)/data/attachments/ (Jiraホームディレクトリ)/import/attachments/

３．復旧・統合先環境：プロジェクトのインポート画面でXMLバックアップファイルを指定する

Jira管理者権限のユーザーで 管理画面 > システム > プロジェクトのインポート にアクセスして、ファイル名を指定し、「次へ」をクリックします。
この後インポートチェックが始まります、大規模な環境でこのチェックに時間（数十分）がかかる場合がありますのでご注意ください。

4．復旧・統合先環境：インポートするプロジェクトを選択して、マッピングチェックに問題がないかチェックをする

「バックアップからのプロジェクト」で復旧・統合したいプロジェクトを指定して、「次へ」をクリックします。

プロジェクトのデータマッピングをチェックします。もしエラーがある場合、以下のようなエラーが表示されます。

• は、マッピングに問題がないことを示しています。
• は、プロジェクトをインポートする前にデータ マッピングで確認すべき問題がありますがプロジェクトはインポートできることを示します。これには、見つからないユーザーがいて、それをプロジェクト インポート ツールで自動的に作成できない場合などがあります。
• は、プロジェクトをインポートする前に修正しなければならないデータ マッピングの問題があることを示しています。たとえば、バックアップ プロジェクトで使用されている課題タイプが対象 Jira インスタンスにないなど。

データマッピングに問題がないと「インポート（Import）」ボタンがクリック可能になります。「インポート（Import）」ボタンをクリックすると実際に課題インポートが開始します。

5．復旧・統合先環境：インポート結果を確認して、実際の課題を確認して情報が正しく復旧されているか確認します

インポート中画面。

インポート後の結果画面。

インポート手順としては以上です。インポート作業自体はウィザード形式で進められるので簡単です。
プロジェクトインポート機能を使う上で大変なことは、ユーザーやカスタムフィールドのマッピングなどでエラーにならないように、事前に設定をきれいに揃えておく部分になります。

便利なアプリ（アドオン）のご紹介

プロジェクトの復旧だけであれば標準のプロジェクトインポート機能でも事足りることもありますが、統合では環境間の差分確認や影響確認をしておく必要があり確認やユーザーへの事前説明などに時間を要します。
私たちが統合作業を実際に実施する場合は、作業を補助する以下のようなアプリ（アドオン）をご紹介することがあります。

• Configuration Manager for JIRA
• Project Configurator for Jira

上記アプリ（アドオン）は、設定の部分の差分確認や反映、標準のプロジェクトインポート機能ではできないダッシュボード、フィルター、ボードの移行も出来たりする部分があり非常に便利です。
便利ではありますが、アプリ（アドオン）にも色々と制限やリスクはありますので、必ず評価・検証の上導入のご検討をお願いします。

お問い合わせ

最後に繰り替えしになりますが、バックアップは大事です。保持期間も含めて検討していただければと思います。