Jira Cloud Migration Assistant attachment migration with site import
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.
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.featureFF 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
Navigate to URL: <Jira_URL>/secure/admin/SiteDarkFeatures!default.jspa
Input dark feature: com.atlassian.jira.migration.enable.site-import-enricher
Click Add
If you want to migrate project avatars, input dark feature: com.atlassian.jira.migration.avatar-migration.feature
Click Add
Attachments can be uploaded before site import, after site import, or both
Option 1: Uploading attachments before site import
create new migration plan(s)
select “Attachments only” in the project selection
run the plan(s)
generate and enrich a site import zip
run site import
Option 2: Uploading attachments after site import
generate and enrich a site import zip
run site import
create new migration plan(s)
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:
Navigate to admin.atlassian.com
Select the cloud instance from the list of available clouds.
Click on the “Products” in the top main menu.
Select “Manage access” for the desired Jira Software cloud site
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.