Summary

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.

Overview

Previously, JCMA was used to upload attachments and project avatars, and after migrating Jira project data with Site Import, it was utilized for 'Attachment linking'. This ensured the visibility and availability of all attachments and project avatars in the cloud site. The new process maintains the capability to upload attachments and project avatars before or after Site Import. However, once the site import archive is generated, it is 'enriched' with attachment linking information. There is no longer a need for a separate JCMA linking step post-site import. Moreover, the enricher-based attachment linking significantly enhances speed and reliability compared to 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 Dark Feature before running the attachments-only migration.

    Enabling this DarkFeature 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 enable 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

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

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

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

This 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