Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Table of Contents
minLevel1
maxLevel6
outlinefalse
styledisc
typelist
printablefalse

Introduction

For the purpose of migration it is necessary for us to make use of an external service because Atlassian currently does not currently () offer a direct migration path from the on premise version of Agile Hive to the Forge version running on Jira Cloud (for more information please refer to Migrate to Cloud).

To migrate the data we need to first transfer the data to the AHCMH (Agile Hive Cloud Migration Helper) app which is running on Atlassian Connect. The AHCMH app transforms the data into the format required by the Agile Hive Cloud Forge app and writes the data to the target Jira Cloud instance.

Obtaining the Agile Hive Cloud Migration Helper app

Aura inline button
summaryRequest AHCMH app for your migration project
paramsJTdCJTIybGFiZWwlMjIlM0ElMjJSZXF1ZXN0JTIwQUhDTUglMjBhcHAlMjBmb3IlMjB5b3VyJTIwbWlncmF0aW9uJTIwcHJvamVjdCUyMiUyQyUyMnNpemUlMjIlM0ElMjJtZWRpdW0lMjIlMkMlMjJzaGFwZSUyMiUzQSUyMmNpcmN1bGFyJTIyJTJDJTIyc3RhdGVzJTIyJTNBJTdCJTIyaWRsZSUyMiUzQSU3QiUyMmNvbG9ycyUyMiUzQSU3QiUyMmJhY2tncm91bmQlMjIlM0ElN0IlMjJsaWdodCUyMiUzQSUyMiUyMzllMDAzOSUyMiU3RCUyQyUyMmxhYmVsJTIyJTNBJTIyJTIzZmZmZmZmJTIyJTdEJTdEJTJDJTIyaG92ZXIlMjIlM0ElN0IlMjJjb2xvcnMlMjIlM0ElN0IlMjJiYWNrZ3JvdW5kJTIyJTNBJTIyJTIzZmZmZmZmJTIyJTJDJTIyb3V0bGluZSUyMiUzQSU3QiUyMmxpZ2h0JTIyJTNBJTIyJTIzOWUwMDM5JTIyJTdEJTJDJTIybGFiZWwlMjIlM0ElN0IlMjJsaWdodCUyMiUzQSUyMiUyMzllMDAzOSUyMiU3RCU3RCU3RCU3RCUyQyUyMmljb24lMjIlM0ElN0IlMjJwb3NpdGlvbiUyMiUzQSUyMmxlZnQlMjIlMkMlMjJpY29uJTIyJTNBJTIyY2lyY2xlLWFycm93LXJpZ2h0JTIyJTdEJTJDJTIybGluayUyMiUzQSU3QiUyMnR5cGUlMjIlM0ElMjJsaW5rJTIyJTJDJTIydmFsdWUlMjIlM0ElMjJodHRwcyUzQSUyRiUyRnNlaWJlcnQuYml6JTJGYWhjLWhlbHAtY2xvdWRtaWdyYXRpb24lMjIlMkMlMjJ0YXJnZXQlMjIlM0ElMjJfYmxhbmslMjIlN0QlN0Q=

...

Preparation

Before you consider migrating Agile Hive from Server or DC to Cloud, make sure to read through Atlassians https://www.atlassian.com/migration/plan/cloud-guide first.

Installation and Configuration

Prepare your Cloud instance

  1. Make sure to install the newest version of Agile Hive (see here for more information: Installation) and create necessary Jira entities in the Jira Administration of Agile Hive

  2. Request a free installation link for the the Agile Hive Cloud Migration Helper app through raising a request on our service desk: https://seibert.biz/ahc-help-cloudmigration including the following information:

    • Company: Name of your company (for partners: Company that plans to migrate)

    • Cloud Site: URL of the target Cloud site you’re migrating to

    • User: Current Jira Server / DC user tier & Cloud user tier

    • Migration Type: Sandbox or production?

We’ll then provide you with a customized installation link that can be used to install AHCMH in your Cloud target site.

Installation

...

  1. Install the Agile Hive Cloud Migration Helper

    1. As a Jira administrator, navigate to “Manage apps” in the “Apps” section of Jira Administration

    2. Scroll to the bottom of the list of installed apps and click on

...

    1. “Settings”

    2. In the modal window, activate the checkbox for

...

    1. “Enable private

...

    1. listings”

...

    1. image-20240314-105005.pngImage Added

...

    1. Refresh the page in your browser by performing a reload. After the page has reloaded, click the new button

...

    1. “Upload app” right next to

...

    1. “Build a new

...

    1. app” in the table header

...

...

    1. Screenshot 2024-12-05 at 12.58.38.pngImage Added
    2. In the modal window, enter the URL you received from the Agile Hive team. Then click ‘Upload’ to install the AHCMH app

...

Prepare your Server / DC instance

Note

Unfortunately, it is currently (as of ) necessary to use a Dark feature flag in Jira to enable Agile Hive migration.

To enable the Dark feature please follow these steps in your Jira Server / Data Center site:

...

, due to the private listing of the separate AHCMH app.

  1. Install the newest version of the https://marketplace.atlassian.com/apps/1222010/jira-cloud-migration-assistant?hosting=datacenter&tab=overview

  2. Enable the “migration dev mode” dark feature

    1. Determine your Jira base URL in the system settings under “Base URL”

    2. Navigate to <Jira_Base_URL>/secure/SiteDarkFeatures!default.jspa

    3. Enter migration-assistant.app-migration.dev-mode into the input field

    4. Click “Add” or “Submit”

    5. (You can disable the feature after migrating by

...

    1. deleting the migration-assistant.app-migration.dev-mode key

...

Information on processing of data

Here are the most important points in regards to what data is used in what way and which data is stored persistently on an external database:

...

Persistently stored data on an external database

  • the Atlassian Connect framework automatically tracks the Cloud-ID and instance url. This is not controllable on our side

  • we additionally persist the Cloud-ID and the transaction IDs that Atlassian attaches to migration requests to allow better status tracking for debugging as well as continuous operations for larger instances.

  • this is necessary to handle possible duplicate requests and cancellation requests

  • the transaction ID for a migration is deleted once the migration is successfully completed

...

Other customer generated data is non-persistently stored on external services only for the duration of the migration

  • issue data is loaded via a JQL query to specifically identify issues which have a Agile Hive hierarchy issue-link

  • this data is only non-persistently stored in RAM

  • this is necessary for the AHCMH app to transform the data from the on premise format to our Cloud app format and store it in the target Jira Cloud instance

  • this data is only ever accessed when migration requests from the Jira Cloud Migration Platform are sent to the ACHMH App

Some meta data is persistently logged for troubleshooting

...

total number of issues to migrate

...

number of issues migrated

...

IDs of migrated issues

...

error information from requests to the Jira Cloud instance

...

this data allows us to identify the scope and possible cause of issues that occurred during migration

...

    1. again)

  1. Make sure to have have the newest version of Agile Hive on your Server / DC instance

    1. you need at least version 3.64.3 to initiate a migration in general

    2. version 3.72.1 enables the migration of more data, like e.g. custom fields

Migration execution

General migration guidelines / advice

To ensure a smooth migration, it is advisable to consider the following guidelines:

  1. Don’t migrate all projects at once. It is better to migrate projects in the organization by subtrees from top to bottom. This means to first migrate a Portfolio, after that corresponding Solutions, followed by subordinated ARTs and associated Teams. Then migrate the next portfolio with the same approach until the whole organization is migrated.

  2. Try to migrate parts of your organization with reasonable sizes, e.g. < 50k issues for all projects to migrate in one batch. Even though the migration helper app is built to handle a large amount of data, predictability, stability and migration speed will be better with reasonable sizes. Potential performance or stability issues do not depend on Jira entities alone, but on the amount of app data entities like custom field values in issues.

  3. If you have already planned future PIs on your Server / DC instance, it is advised to first migrate Solutions and ARTs, then recreate the PIs on your Cloud site in the PI & Iteration Management and then migrate your Team projects. After you migrated the Team projects, you can go to the Agile Hive Project Settings of each Team to the section “Boards & Sprints” and map the automatically migrated sprints to the iterations.

Migration guide

  1. Go to “System” and under “Import and Export” go to “Migrate to cloud”

  2. Under “Assess” click “Begin assessing” and make sure to select “Needed in cloud” for Agile Hive Suite

  3. Under “Prepare” click “Begin preparing” and then “Choose cloud site”

  4. For “Migrate from” enter you base URL of the server instance and choose the destination cloud site in “Migrate to”

  5. Check the “Allow Atlassian to access migrations data to perform your migration” checkbox and click “Confirm”

  6. Back in the previous screen in “Connect to cloud”, choose the authorized cloud site from the dropdown menu and click “Continue”

  7. Under “Install” Agile Hive may not appear as a required app for cloud (because as of Atlassian cannot handle privately listed apps, see this issue https://jira.atlassian.com/browse/MIG-1787), so just click “Continue” again

  8. Under “Agree” Agile Hive should show up and the policy needs to be agreed

  9. Click “Done”

  10. Assess and prepare users and email domains according your needs, and maybe migrate your users in advance

  11. Create a new migration

  12. Provide a unique name for the migration, choose migration stage (Production or Testing) and make sure your target cloud site is selected

  13. In the next step, select “Choose what to migrate” and select Projects according to https://agilehive.atlassian.net/wiki/spaces/CLOUD/pages/614268930/Agile+Hive+Migration+Guideline#General-migration-guidelines-%2F-advice

  14. For “Advanced Roadmap plans”, “Dashboards, boards and filters” and “Users and groups” select options according your needs (data related to the project should be sufficient)

  15. Make sure to select Agile Hive (or the option “All”) under “Apps” and click “Run pre-migration checks”

  16. Fix potential errors in the list and click “Review migration” afterwards click “Run”

  17. Back in the migrations dashboard, you can click on “View details” to examine the progress of the migration even further.

Post migration steps

After a successful migration run (for a part of your organization), you need to follow these manual steps to recreate all possible data from your Server / DC instance, as not all Agile Hive data gets migrated automatically (yet):

  1. Go to “My organization” and resemble the project hierarchy to match your Server / DC instance (see My Organization for more information)

  2. Check and update hierarchical links via ‘SAFe® Hierarchy’ panel in Jira Issue Detail View for individual issues as needed.

  3. Adjust your project configuration of Screens, Screen Schemes, and Issue Type Screen Schemes to the Agile Hive default or adjust as needed (see Configure Jira Projects For Use With Agile Hive for additional information on recommended / minimum required configuration).

    1. The “Milestone Date” custom field gets migrated automatically, but is not included in the Screens from Agile Hive Cloud. You can add the migrated field to the desired screens (where the Cloud version of the field should already exist), rename the Cloud field to something else and make sure that your migrated field is called “Milestone Date” (without any “migrated”-suffix). Now the Milestones should also appear in Agile Hive views like the Roadmap or in Reports

  4. To maintain your set dependencies from Server / DC, go to the Agile Hive Administration and select the Issue Link Type that you used before, and click “Save”.

  5. Create your PIs as you need for the future

    • If you already had PIs planned for the future on you Server/DC instance, you can recreate the PIs with the same dates in the Cloud Solution Train and/or ART and go to each corresponding team’s Agile Hive project settings to map the iterations created in Cloud with the sprints, that were migrated from Server/DC. You can delete the newly created sprints from Cloud again afterwards

...

Link to this page: https://seibert.biz/ahc-migrationdocumentation

...