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 that all the macros correctly retrieve the Jira information.

In order to access this feature, a Confluence administrator can click on 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 prior to 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 keys factors about the repair function:

• The feature will update the existing application link, used by the macros to locate to 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 ID's containing Jira Macros are identified and stored as pending during the Space import of a migration. These IDs are retrieved when the Macro repair is started. Once completed, the IDs are marked as done, unless they are updated by a new migration of the space.

Once Jira Macro Repair completes with the message 'All done!', it has updated all the pages that were pending. Rerunning the process will not change an 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. Tap 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. Tap the Click here to fix button.
5. Tap the Select an Application Link dropdown to select the new application link name. System Jira is the default link . This gets 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 tap 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 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 cannot 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 on the timings and outcomes
• Run after a production migration, even if some manual updates are required.
  • The macro repair has good performance and will reduce the number of pages needing manual intervention