Summary

As part of migrating Confluence Spaces to a Confluence Cloud Tenant, either:

• using the Confluence Cloud Migration Assistant (CCMA) to migrate from a Server instance, or
• using Copy Product Data to migrate from another Cloud instance,

the Jira Macro Repair feature will be used to properly map the Jira issues macro to the correct application link, ensuring all the macros correctly retrieve the Jira information.

To access this feature, a Confluence administrator can select the site's administration cog icon  (at the top right) and then select Data Management > Jira Macro Repair.

Understanding the Jira Macro Repair

Understanding the Jira Macro Repair is crucial before its usage since it will perform changes to the existing content, and those can't be converted unless the space gets re-imported. Here are the key factors about the repair function:

• The feature will update the existing application link, used by the macros to locate the original Jira instance, to reference the new application link connecting the target|destination Confluence and Jira migration destinations.
• All content, such as issue key, project, and columns to be displayed, will not change.

• The left side (Existing Jira instance link) will correspond to the application link's name from the Source Confluence instance, connecting to the original Jira instance.
• The right side (New Jira instance link) will correspond to the existing application links configured in the target/current Confluence instance to which the Space content has been imported.

Using the Jira Macro Repair

Page IDs containing Jira Macros are identified and stored as pending during a migration's Space import. These IDs are retrieved when the Macro repair is started. Once completed, the IDs are marked as done unless a new space migration updates them.

When you see the 'All done!' message, all pending pages have been updated. Rerunning the process will not change the outcome.

To do this:

1. Go to Confluence's administration cog icon  (at the top right) and then select Data Management > Jira Macro Repair.
    
   
2. Select the Start button
3. When the list of IDs is retrieved, a pop-up will be displayed stating "We've found some broken Jira issue macros on your instance.":
   
4. Select Click here to fix.
5. Select the dropdown below New Jira Instance link to choose the new application link name. System Jira is the default link. This link is commonly created between Confluence and Jira on the same tenant, and is commonly used.
   1. If Jira is located on another tenant, follow these steps to create a new link.
6. Select the required name and select Finish.
   

Features

Jira Macro repair has the following features:

• Supports Phased Migrations
  • It can be run after each phase
• Repeatable after test (re-)migrations of the same space(s)
  • Rerun after each migration. Each migration of a space refreshes the page info held for that space
• Jira Migration is not necessary to update the macros
  • The Jira projects don't need to be migrated to update the Confluence content
  • Macros will show no results returned until the projects are migrated
• Page histories are updated
  • Restoring an earlier version of a page will show the macro correctly
• Confluence cloud-to-cloud migrations using 'Copy Product Data' are supported

Limitations

• Federated Jira Projects are not supported
  • If Jira projects are spread across multiple sites, the Macro Repair can't update them
• Confluence CSV imports are not supported

Best Practices

• Run Jira Macro Repair after each migration
• Run during test phases to get more insight into the timings and outcomes
• Run after a production migration, even if manual updates are required.
  • The macro repair has good performance and will reduce the number of pages needing manual intervention