Migration details

Owned by Bob Swift
Last updated: Feb 08, 2016
5 min read

I recently migrated a large number of projects (30) from Atlassian Plugin Studio (no longer available) to Atlassian Cloud using a variety of techniques. The result is http://bobswift@atlassian.net. While I am happy with the result, getting there took much longer than expected! There were a number of problems to overcome along the way and many things I would do differently if I needed to do something similar again. The following summarizes what I would recommend for others with a similar migration to do (smile). Some of the steps could be omitted or modified for your situation. This only covers migrating Confluence and JIRA data.
 
Automation was used extensively due to the large number of projects to migrate and the need to perform all the migrations in the shortest amount of time. To demonstrate, we will use 2 projects - PA and PB. If you only have one project, you can simplify the steps to some degree and in some cases do steps manually or use simplified commands. Appfire Command Line Interface (CLI) was used extensively. Atlassian CLI 2.6.0-SNAPSHOT or above is required. Specifically, use a customized version of the atlassian.sh or atlassian.bat to make it easier. Figure out a head of time what user will be used to make the changes in the OnDemand instance. I recommend creating an automation user id (automation).
 
For Confluence, a local Confluence 3.5.13 (or equivalent) migration installation is required to enable the restoring of data to the OnDemand instance. The local instance will be upgraded to 4.1.7 after the studio data is restored. This will give us the ability to save and restored the spaces to the OnDemand instance because it is at roughly the same release level.

Customize the atlassian command for Confluence
if [ "$application" = "confluence-studio" ]; then
    string="confluence-cli-2.6.0-SNAPSHOT.jar --server https://studio.plugins.atlassian.com/wiki --user xxxx --password xxxx"
elif [ "$application" = "confluence-ondemand" ]; then
    string="confluence-cli-2.6.0-SNAPSHOT.jar --server https://xxxx.atlassian.net/wiki --user xxxx --password xxxx"
elif [ "$application" = "confluence-migration" ]; then
    string="confluence-cli-2.6.0-SNAPSHOT.jar --server https://localhost:8121 --user automation --password xxxx"
Customize the atlassian command for JIRA
if [ "$application" = "jira-studio" ]; then
    string="jira-cli-2.6.0-SNAPSHOT.jar --server https://studio.plugins.atlassian.com --user xxxx --password xxxx"
elif [ "$application" = "jira-ondemand" ]; then
    string="jira-cli-2.6.0-SNAPSHOT.jar --server https://xxxx.atlassian.net --user xxxx --password xxxx"

Steps to Prevent Changes on Studio

Once you start the migration process, you do not want changes taking place on the old system.

  1. Prevent Confluence pages from being created, updated, or commented on
    • General users don't have much permission anyway. Only administrators and a few special cases are allowed to edit - ignore that or handle manually.

    • Remove comment permission from users group

      atlassian confluence-studio -a runFromList --common "-a removePermissions --space @entry@ --group users --permissions comment" --continue --list "PA, PB"
  2. Prevent JIRA issues from being created, updated, or commented on by switching users (group) role from users to observers

    • Give Observers role to users group - no harm in doing this early

      atlassian jira-studio -a runFromList --common "-a addProjectRoleActors --project @entry@ --group users --role Observers" --continue --list "PA PB"

    • Remove Users role from users group

      atlassian jira-studio -a runFromList --common "-a removeProjectRoleActors --project @entry@ --group users --role Users" --continue --list "PA, PB"
    • The default permission scheme gives users group authority not just role authority to create, update, ... issues!!! So, you need to change all projects to use a different permission scheme that is strictly role based. Developer Relations created this specifically for this purpose (thanks Jonathan!). There is no harm in doing this change well before migration.

      1. Update all projects to the role based permission scheme

        atlassian jira-studio -a runFromList --common "-a updateProject --project @entry@ --permissionScheme \"Role based\" " --continue --list "PA, PB"

Steps to Capture Data from Studio

As part of the migration, it is important to migrate user ids as well (especially for JIRA!) in order to preserve who created issues or content. This will enable the original user to retain ownership as much as possible. This can be done easily with Confluence but is significantly more difficult for JIRA. JIRA limitations make it impossible to retain certain information using an external migration approach. In our case, the limitations were acceptable.

  1. Confluence data

    1. Export participants data (userId, full name, email)
      This allowed user ids to be exported.

      This can take time for larger spaces or a large number of spaces/projects
      atlassian confluence-studio -a runFromList --common "-a exportData --space @entry@ --file participants-confluence.txt --append" --list "PA, PB"

    2. Export space

      atlassian confluence-studio -a runFromList --common "-a exportSpace --space @entry@ --file @entry@-space.zip" --list "pa, pb"
  2. JIRA data

    1. Export participants data (userId, full name, email) - only need to do this once for all projects

      This can take time for larger projects or a large number of projects
      atlassian jira-studio -a exportData --exportType participants --file participants.txt --search "project in (PA, PB)"

      Incomplete

      Unfortunately, studio prevents access to the email address for users (JIRA only, Confluence works ok!). You will need help from Developer relations to get the email addresses for your JIRA participants.

    2. Export project data - versions and components

      atlassian jira-studio -a runFromList --common "-a exportData --project @entry@ --file @entry@.txt" --list "pa, pb"

    3. Get issues

      atlassian jira-studio -a runFromList --common "-a getIssueList --project @entry@ --file @entry@-issues.txt --list "pa, pb"

    4. Get comments

      Run for each project
      atlassian jira-studio -a runFromIssueList --project pa --common "-a getCommentList --issue @issue@ --outputFormat 2 --append --file pa-comments.txt"

    5. Get voters

      Run for each project
      atlassian jira-studio -a runFromIssueList --project pa --common "-a getVoterList --issue @issue@ --outputFormat 2 --append --file pa-voters.txt"

    6. Get watchers

      atlassian jira-studio -a runFromIssueList --project pa --common "-a getWatchersList --issue @issue@ --outputFormat 2 --append --file pa-watchers.txt"
    7. Attachments
      Attachments will be handled by script by retrieving them one at a time and adding them to the migrated issue directly

Steps to Restore Data to OnDemand instance

Script is used to do most of this for each project in parallel.

  1. Add users - important to retain JIRA reporters and comment authors for both JIRA and Confluence

    atlassian jira-ondemand -a run --file participants.txt
atlassian jira-ondemand -a run --file participants-confluence.txt
  2. Confluence spaces
    1. Copy *.zip to Confluence home/restore directory of a local Confluence 3.5.13 instance

    2. Restore exports to local instance

      atlassian confluence-migration -a runFromList --common "-a restoreExport --file @entry@-space.zip" --continue --list "pa, pb"
    3. Upgrade Confluence 3.5.13 to Confluence version <= 4.1.7 (OnDemand level)

    4. Export spaces (now in OnDemand compatible release format)

      atlassian confluence-migration -a runFromList --common "-a exportSpace --space @entry@ --file @entry@-space-41.zip
    5. restore spaces to OnDemand instance using UI (on demand has unique restore support)
      • link the space to the existing JIRA project with the same key (this didn't seem to work though - OnDemand bug ?)

  3. JIRA projects - create project and add versions and components

    atlassian jira-ondemand -a runFromList --common "-a run --file @entry@.txt" --continue --list "pa, pb"

  4. Restrict notifications - no notifications while JIRA data is being recreated. Create a No notification notification scheme to use for your on demand instance.

    atlassian jira-ondemand -a runFromList --common "-a updateProject --project @entry@ --notificationScheme \"No notifications\" " --continue --list "pa, pb"
  5. JIRA issues
    • run issue create script
    • match JIRA keys
    • progress issues to correct state
  6. JIRA comments
    • run comment create script
  7. JIRA voters
    • run comment create script
  8. JIRA watchers
    • run comment create script
  9. JIRA attachments
    • run attachment copy script

  10. Restore notifications

    atlassian jira-ondemand -a runFromList --common "-a updateProject --project @entry@ --notificationScheme \"Default Notification Scheme\"" --continue --list "pa, pb"

Steps to Redirect Users

As a service to your users, you can redirect users from the old information to the new information.

  1. Update Studio Confluence pages with redirect link

    For each space
    atlassian confluence-studio -a runFromPageList --space pa --common "-a updatePage --space @space@ --title @title@ --content "... redirect macro ..."

  2. Add a comment to Studio JIRA issues with link to equivalent issue

    atlassian jira-studio -a runFromIssueList --project pa --common "-a addComment --issue @issue@ --comment "Issue migrated to [@issue@|bobswift@atlassian.com]"


Find answers from the community.

Ask a question to the community.

Log a request with our support team.

Confluence®, Jira®, Atlassian Bamboo®, Bitbucket®, Fisheye®, and Atlassian Crucible® are registered trademarks of Atlassian®
Copyright © 2005 - 2024 Appfire | All rights reserved. Appfire™, the 'Apps for makers™' slogan and Bob Swift Atlassian Apps™ are all trademarks of Appfire Technologies, LLC.