Jira Cloud Migration Assistant attachment migration with site import

Still need help?

The Atlassian Community is here for you.

Ask the community

IMPORTANT: This feature should only be used only with site import

Platform notice: Server and Data Center only. This article only applies to Atlassian products on the Server and Data Center platforms.

Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.

*Except Fisheye and Crucible

Purpose

The Jira Cloud Migration Assistant's (JCMA) attachment and project avatar migration compatibility with site import is now available. This allows for site import to ‘pre-load’ attachments.

Only supported in JCMA version 1.7.7 and later.

IMPORTANT: Support, CMMs, and customers should be aware that feature flags are experimental. We’ll do our best to offer support if these feature flags break migrations. However, we can't guarantee fixes or incident responses. Feature flags don’t cover all edge cases. If using these feature flags is your only option, test your migrations thoroughly with the feature flags enabled. You should consider manual workarounds when facing issues with feature flags.

Summary

Previously, attachments and project avatars could be uploaded using JCMA and once Jira project data was migrated with Site Import, JCMA was used to perform ‘Attachment linking'. This made sure all the attachments and project avatars are visible and available in the cloud site. The new process still allows for attachments and project avatars to be uploaded before or after Site Import, however, after the site import archive is generated it is ‘enriched’ with attachment linking information. There is no longer any JCMA linking step to be run after site import. Further, attachment linking using the enricher is faster and more reliable than the old JCMA attachment linking process.

For example:

  • run JCMA attachments only for all projects to be migrated (usually everything)

    • If you want to migrate project avatars, enable com.atlassian.jira.migration.avatar-migration.feature FF before running the attachments only migration.

      Enabling this FF will only migrate project avatars. User Avatar migration is not supported.


  • generate the site import zip archive

  • run the enricher to embed attachment linking information on the site import zip archive

  • run site import

Solution

Enriching the site import archive with attachment linking information is implemented as a Dark Feature and not enabled in JCMA by default. See Enable Dark Feature in Jira for instructions on how to use dark features

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

  2. Input dark feature: com.atlassian.jira.migration.enable.site-import-enricher

  3. Click Add

  4. If you want to migrate project avatars, input dark feature: com.atlassian.jira.migration.avatar-migration.feature

  5. Click Add

Attachments can be uploaded before site import, after site import, or both

Option 1: Uploading attachments before site import

  1. create new migration plan(s)

    1. select “Attachments only” in the project selection

    2. run the plan(s)

  2. generate and enrich a site import zip

  3. run site import

Option 2: Uploading attachments after site import

  1. generate and enrich a site import zip

  2. run site import

  3. create new migration plan(s)

    1. select “Attachments upload” in the project selection

Data or attachments and project avatars that are modified or added after the site import backup is made will not be able to be migrated

Backup Jira data to generate site import zip

This process will look for the latest zip file in $JIRA_HOME/export and use that to enrich with attachment linking information.

Run enricher

The enricher has to be run for the desired cloud ID associated with the Jira cloud instance you are migrating to. Using a different cloud ID will cause attachments to not be visible after migration.

To find your Jira cloud ID:

  1. Navigate to admin.atlassian.com

  2. Select the cloud instance from the list of available clouds.

  3. Click on the “Products” in the top main menu.

  4. Select “Manage access” for the desired Jira Software cloud site

  5. The URL will have the cloud ID in the form

    https://admin.atlassian.com/o/abc123/products/jira-software/<cloud ID>

OR

Use the following query to get the cloud Id or if there are more than one, select the one you want to migrate the data to.

select "CLOUD_URL", "CLOUD_ID" from "AO_6FF49D_CLOUD_SITE";

Navigate to URL: <Jira_URL>/rest/migration/latest/enricher/job/new/<cloud ID>

This will display:

  • "new job created" if a job has been created

  • "rerunning job" if a job has been previously run and finished for the same cloud ID

  • "another job is already active - {cloudId}" if there is an active job

Get the status of an enricher job

Navigate to URL: <Jira_URL>/rest/migration/latest/enricher/job/<cloud ID>

This will display:

  • "job is active" if it's still in progress - consider checking the logs for further details

  • "no job found" if there is no record of a job with that cloud id

  • "Done - {filepath}" if the job completed successfully with the path of the enriched zip file

  • "Failed to run job: {error}" if the job did not complete successfully

The enriched zip has the timestamp and cloud host associated with the cloud id in the file name

Get active jobs

Navigate to URL: <Jira_URL>/rest/migration/latest/enricher/job/active

This will display:

  • Cloud ID of an active job if there is one

  • "no active jobs" if there isn’t

Troubleshooting

Cloud id not found

You may face an error stating that the CloudID is not found:


This process will look in the AO_6FF49D_CLOUD_SITE table for details. This table will be populated when "Choose cloud site" has been completed.

Client must be authenticated

These operation can only be performed by an administrator. By logging in, the browser will store your session cookie. Using a new tab in that same browser will make sure you are authorised to perform the above operations.

General Debugging

The enricher process will create a copy of the Site Import Zip archive and add two csv files: attachments.csv and avatars.csv.

Before copying these two csv files to the site import archive, the enricher process will create the files in the export directory. The files will be prefixed with a timestamp and the cloud domain name, for example: 20230806-230209-mpt-test.atlassian.net-attachments.csv.

These files may be manually copied into Site Import Zip archive. Note that if doing so, the csv files must be renamed to attachments.csv and avatars.csv, removing the prefix.

The final structure of the enriched Site Import Zip should be the following (note that the zip file can be of any name):

20230806-230209-mpt-test.atlassian.net-import-enriched.zip
├── activeobjects.xml
├── attachments.csv
├── avatars.csv
└── entities.xml

Last modified on Aug 6, 2023

Was this helpful?

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