Important migration tasks during test and after production

Still need help?

The Atlassian Community is here for you.

Ask the community

Summary

Discover what are the most important tasks to be done during your Jira and Confluence migration journey.

Overview

When migrating Jira or Confluence (Server, Data Center, Cloud) to the Atlassian Cloud, there are a number of migration tasks that may need to be completed to avoid unwanted scenarios and issues in the cloud site. 

Whether the task has to be done depends on the phase. The test phase refers to the testing done before the production migration when issues can more easily be caught and resolved. The post-migration phase refers to after the production migration is completed. It's often more difficult to resolve issues during this phase, so we always recommend testing your migration thoroughly before the final production migration. 

The scenarios are divided into post-migration and test phases. They're also labeled with being applicable to Jira or Confluence.

Sections on this page: 

Problem Report ticket support

The goal of the ticket is to investigate and address any migration errors and technical tasks directly with the Migration Support Engineers.

To create a new Problem ticket:

  1. Select the related Plan MOVE ticket from the View Requests page.

  2. Choose “Create a Problem Report” from the list of options in the upper right corner of your screen.

  3. Provide an Issue Summary, Description, and the Affected Product.

  4. Please create a support zip and attach it to the new ticket for troubleshooting and approve data access.



Test phase

Task

Product

Steps

Additional information and best practises

Documentation

Users need to change their content or access to use a different email address

Jira

Confluence

  • This can be resolved before the migration

Post migration:

  • Please open the Problem Report ticket and share the destination cloud URL

  • Please keep an eye on the Problem Report ticket as the data access might be requested

Sometimes user emails are updated but their data is still tied to the old email. When this happens, the product data has to be mapped from the old user to the new user. Then the user can use the new email to log in and will see their data. 

Pre-migration instructions:


It’s impossile to bulk delete users

Relevant Bug:

ID-8172 - Getting issue details... STATUS

Jira

Option 1: REST API(only works for managed
accounts)

  • Stop users from syncing through Identity
    Provider

  • Get a list of managed accounts

    • Get API key and Organization ID

      • Go to Atlassian Administration and
        select your organization

      • Select Settings > API keys.

      • Select Create API key in the top right.

      • Select Create to save the API key.

      • Copy the values for your Organization ID
        and API key. Make sure you store these
        values in a safe place, as we won't show
        them to you again.

      • Select Done. The key will appear in your
        list of API keys.

    • Get managed accounts list

      • Use the GET /admin/v1/orgs/{orgId}/users request.

      • Use the API key and orgId from the previous step.

      • Use the API key with Bearer Authentication.

  • Delete account

    • Use the accountId, API key and Organization ID from the previous steps to delete the user account: POST /users/{account_id}/manage/lifecycle/delete.

Option 2: BulkOps App

  • BulkOps App enables you to bulk delete users. Please note that BulkOps App is a third-party app that is neither built nor maintained by Atlassian.

  • Deleting an account is permanent. If you think you’ll need the account again, we recommend you deactivate it instead.

Delete a managed account

Not all dashboards are seen in the destination cloud site

Jira

Jira dashboard migration is not enabled in JCMA by default. Dashboards may be migrated by using a dark feature. See Enable Dark Feature in Jira for instructions
on how to use dark features

This should be the last step in the process. Executed AFTER all projects are migrated, by using a dummy project to initiate migration.

  • Navigate to URL: <Jira_URL>/secure/admin/SiteDarkFeatures!default.jspa

  • Input dark feature: com.atlassian.jira.migration.dashboard-migration.feature

  • Click Add

  • Limitations and known issues:

  • No system dashboard support means admin will not be able to migrate their system dashboards from the server to the cloud.

  • No third party gadget support yet you could get the boards themselves migrated.

  • No support for favorite board feature.

  • Crucible, Fisheye, Bubble charts, Introduction and Fisheye Recent ChangeSets gadgets are not supported.

  • Gadgets which used custom fields may not work but users can open and fix them after migration.

  • Display differences may occur but they are not blockers in operation.

  • If JCMA fails, the plan will be in INCOMPLETE status. JCMA does not show migration progress of dashboard migration.

How to migrate all dashboards with the Jira Cloud Migration Assistant (JCMA)

Duplicate custom fields are showing in the custom fields menu and are appended with (migrated)

Relevant Bug:

MIG-1019 - Getting issue details... STATUS


Jira

  • Use a non-production test Cloud environment. This will allow you to test from as many servers as you'd like without polluting the content in your Cloud production instance and ending up with multiple duplicates caused by testing. This is especially critical if you have existing data in your Cloud instance since there's no way of cleaning up duplicate entries(in order to wipe the duplicates for a new test run, completely reset the site and restart migration from a new server)

  • If you need to perform a merge from multiple server instances, then one way to prevent duplicates is by merging the server instances first before migrating with JCMA.

Duplicates reasons:

  • Entities with the same name are being migrated from multiple server or Data Center instances into a single cloud site

  • Default entities that come out of the box with cloud that are also in a migration plan from server

  • Migrating data in stages, first with Jira Site Import then followed by the Jira Cloud Migration Assistant from the same server or Data Center instance

  • Custom fields could be duplicated if one of these are true:

    • different data types

    • different descriptions - even minor changes in the text will mean that fields will not match

    • different field contexts

Jira Cloud Migration Assistant duplicates and tracking entities

Permission schemes are duplicated and appended with (migrated) 

Relevant bug:

MIG-958 - Getting issue details... STATUS

Jira

Option 1: Migrate in two steps

  • First migrate all the projects of type Business (Attachment Test, Business, Migration, Test Issue Linking) followed by migration of Software project (TEST). 

  • This will create only two new permission schemes for the customer

Option 2: Modify the permission grant 

  • Update the permission grant for Manage Sprint permission in the Permission scheme to remove all the values from the Granted to section

  • Migrating all the projects in a single plan. In this case all the projects will be mapped to single permission scheme

  • Update the Manage Sprint role in the permission scheme migrated on cloud.

Permission schemes are created, for each set of "Users and roles".


Macros are not rendering correctly on Confluence pages


Confluence


All macros being used (both native and third-party) need to be tested to understand their compatibility in the cloud. 

Descriptions of the different macros and their compatibility in the cloud: 

Different macros and functionalities between Confluence Server/Data Center and Cloud


Post-migration phase

Task

Product

Steps

Additional information and best practices

Documentation

Broken link fixing: links in the cloud UI pointing to the previous server or cloud URL

Jira

Confluence

  • Confirm your production migration is complete

Use Product Links view

  • Go to admin.atlassian.com, and select your organization.

  • Go to Settings > Product links.

  • For each product that has links you want to update, select … > Update links.

  • Product links view: you need to be a site admin of the site where the product lives or an organization admin and admin of the product that has links you want to update.

  • If the issue persists please open the Problem Report ticket and share the destination cloud URL

  • Link fixing is done post migration and managed by the support team usually on Monday morning

  • Please keep an eye on the Problem Report ticket as the data access might be requested

Links broken after Server to Cloud or Cloud to Cloud migration

Changing the indexing language after migration

Jira

Confluence

  • Confirm your production migration is complete

  • Open a MOVE: Problem Report ticket with the engineering team

  • Include the following information:

    • the destination cloud URL that needs to be fixed

  • Please keep an eye on the Problem Report ticket as the data access might be requested


Attachment preview unavailable

Relevant Bug: 

JRACLOUD-81066 - Getting issue details... STATUS

Jira


  • Confirm your production migration is complete

  • Open a MOVE: Problem Report ticket and share:

    • the destination site

    • screenshot of the broken attachment

‼️ Workaround: refresh the page. Then the attachment preview will display as expected. 

  • The fix is done post migration

  • Please keep an eye on the Problem Report ticket as the data access might be requested


Projects not viewable due to permissions

Jira


  • Go to  Configuration and Projects

  • Identify the affected project and at the end of the project line, click on Project Settings

  • On the left panel, click on Permissions.

  • Choose Browse Projects permission and identify what is the Group that has this privilege.

  • From the Administration dashboard, assign your user to that specific Group.

  • If Browse Projects it’s assigned to Role only(click on the Project’s People tab and add yourself or a group to the desired Role in that project)

  • If permissions are associated with Project Roles, make sure the Project Roles have groups or specific users associated with them:

Issues cannot be seen in a project after migration

Boards not viewable due to the specific permissions or/and filters granted to the respective users roles, or groups

Jira


Make sure that these sanity checks are adhered while migrating boards and filters

  1. Boards must be associated with valid filters

  2. Board columns must be associated with valid statuses

  3. Invalid JQL in the Quick Filter must be fixed

  4. Personal data, such as email addresses, must be removed from any filters

  5. Shared permissions settings must refer to valid groups

  6. Boards/filters owned/created by inactive/deleted users must be assigned to valid owners.

  • If the issue persists please open the Problem Report ticket and share the destination cloud URL

  • Please keep an eye on the Problem Report ticket as the data access might be requested

How to migrate all boards and filters with the Jira Cloud Migration Assistant (JCMA)

"Migrated on…" text is appearing with migrated objects such as permission scheme and custom field descriptions

Jira


Text updated in bulk open a MOVE: Problem Report ticket and share:

  • the destination site

Give users the option to remove the migrated text from fields when using JCMA

Workflow UI status positioning is changed in the diagram view

Jira

There are no known workarounds or fixes other than to fix this manually.


MIG-217 - Getting issue details... STATUS

Broken Jira macros in Confluence. Example error: Error rendering macro 'jira'






Relevant Bug:

CONFCLOUD-76136 - Getting issue details... STATUS

Confluence

  • Go to Confluence's administration and select Jira Macro Repair

  • Tap the Start button

  • Pop-up will be displayed, stating that "We've found some broken Jira issue macros on your instance"

  • Tap the Click here to fix button.

  • If you have only a single application link, tap the Finish button to perform the repair. If there are different application links connected, tap the Select an Application Link dropdown in order to confirm the correct one and tap Finish.

  • If the Jira content has not been imported, the Jira issues will not be located at the target's Jira instance linked to Confluence, meaning that they can be only "repaired" if an application link is created to the source where the Confluence import came from and then, the remap would be performed.

  • If the issue persists please open the Problem Report ticket and share the destination cloud URL

  • Please keep an eye on the Problem Report ticket as the data access might be requested

Using the Jira Macro Repair

Broken Team Calendar macros

Relevant Bug: MIG-124 - Getting issue details... STATUS


Confluence

  • Use the team-calendars migration script

  • Please see the README for details on supported and unsupported calendar events. For instance, Jira Project Events are not migrated.

Script to migrate Confluence team calendars from server to cloud

Not all space content is viewable to users due to permissions migration

Confluence

Recover permissions to the site:

  • Select the gear icon in the top nav(top right) to go to product settings.

  • Select Space Permissions.

  • Locate the space in the Individual Spaces list and select Recover Permissions.

  • If you're an admin in the space, you'll see Manage Permissions.

  • Selecting Recover Permissions will be recorded in the Confluence audit log.  

This may present as:

  • the space is not listed in the Spaces dropdown

  • the space cannot be found in View All Spaces or the space directory

  • space content cannot be searched or used as a filter in search

Space pages and content cannot be seen after migration

Pages are not displaying correctly due to being migrated with the old editor

Confluence

When page conversion is turned, you'll get a banner notification at the top of the first page and you’ll see a notification at the lower left of the page. Before clicking convert, you have a chance to see how the page will look in the new editing experience.

  • Click Preview page.  More detailed information is presented about the process.

  • Click Convert page.  Page refreshes, and the content appears in the new editor.

  • Click Publish… to save the new editor version of the page.

  • The New editor: Includes Publish… or Update and Close buttons in the top menu and the emoji icon

  • The Legacy editor: Has earlier versions of text-color picker and page formatting

Convert pages to the new editor

Last modified on Apr 5, 2024

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.