DATA CENTER AND SERVER | CLOUD
Migrating the R4J tree data
- Angelica Salazar
- Bernhard Doleschel
Background
A significant change in the tree data structure is introduced at R4J version 4.7. There were performance bottlenecks in processing the tree structure with large amounts of items which caused timeouts in R4J custom JQL queries, tree rendering, and tree filtering. To resolve these, the tree data was migrated to a more optimal data model.
What to expect
After the R4J 4.7.x upgrade, not migrated projects are blocked from usage and may cause unexpected errors in R4J if not migrated.
Executing the task will:
Migrate tree structure data from the tables from AO_242870_CHILD_REQ_RELATION, AO_242870_PROJECT_TREE_ITEM, and AO_242870_PROJECT_TREE_FOLDER to AO_242870_PROJECT_TREE_STRUCT.
Other important things
You need to be a Jira Administrator to perform the steps outlined.
You should have at least browse permission on all projects.Once executed, the migration process may take several hours, depending on the amount of data in the R4J project trees.
Based on our baseline tests, a typical instance that has ~200 projects with ~10k issues each would finish migrating within ~10 hours.
We recommend proper planning of the R4J upgrade and tree data migration. If possible, the migration should take place outside of business hours.
R4J 4.7 has been verified on Jira 8.5.x to Jira 8.20.x on the following database types and versions:
SQL Server 2016
PostgreSQL-11.11-2
Oracle 19c
MySQL 5.7.33
R4J 4.7 tree data is not backward compatible with older versions of R4J as stated in our release notes.
Check out our tree loading and filtering test benchmarks: R4J 4.6.x vs 4.7.x performance benchmark results.
We highly recommend you to:
Backup your data
Plan and make the necessary preparations for the migration process
First run the migration on a test/staging system and verify the results.
If you encounter issues with earlier R4J 4.5, please reach out to us through our support portal.
Step 1: Pre-requisite - Execute R4J Integrity Checker BEFORE upgrading
In your current R4J version (4.6.x or less), run the Integrity Checker before upgrading to R4J 4.7.x.
On the admin sidebar, go to Integrity Checker
Tick the "Select all" checkbox. At the bottom of the page, click on the Check button
If all checks pass, proceed to the next step. If there is a failed result, click on the Fix button before proceeding to the next step.
On the top right of the page, under Find References of Deleted Project(s), click Check. Fix if there are invalid references found.
Step 2: Upgrade to R4J 4.7.x
Step 3: Recommended (optional step) - Execute Revision Cleanup
If you’re upgrading from 4.4.x or lower versions directly to 4.7.x up, you may have missed this step. Skipping it may cause unexpected errors in R4J.
Executing the revision cleanup process is a required upgrade step from R4J 4.5. Read more: Cleaning up the R4J revision history data.
Step 4: Migrate the tree data
Go to Manage Apps Administration > (R4J section) Tree Data Migration.
On this page, all R4J activated projects will be listed as “Not Migrated”.
At the bottom of the project list, select one or more projects or tick the checkbox "Select all projects across all pages".
Click the Migrate button at the top of the table.
Wait for all projects to finish migrating.
When the project status updates to "Migrated", all R4J operations for it will be unblocked and users can continue using this project in R4J.
Check the table for any status indicating "Migration Error".
Done!
Check the logs for any migration errors. You'll find migration logs in <JIRA_HOME>/log/r4j-migrate-logger<timestamp>.log
Do random checks on R4J activated project trees, coverage views, etc.
If you encounter issues with the migration, please reach out to us through our support portal.
Known Tips and Tricks:
If you encounter migration errors: Check permission for the project. The user executing the migration need to have a least browse permission.