Migrating the R4J tree data

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.

Datasets sizes were selected based on received customer information.

Benchmark per Project Tree

Total Items in Project Tree

Total Time to Migrate

Total Items in Project Tree

Total Time to Migrate

1.000

~30 Seconds

10.000

~4 minutes

100.000

~20 minutes

200.000

~50 minutes

Benchmark per Instance

Total Number of Projects

Total Items per Project Tree

Total time to migrate

Total Number of Projects

Total Items per Project Tree

Total time to migrate

200

10.000

~10 hours

1.000

10.000

~2 days

10.000

1.000

~1 day

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.

  1. On the admin sidebar, go to Integrity Checker

  2. Tick the "Select all" checkbox. At the bottom of the page, click on the Check button

  3. 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.

  4. 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

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: https://easesolutions.atlassian.net/wiki/spaces/REQ4J/pages/1418690692.

Step 4: Migrate the tree data

  1. Go to Manage Apps Administration > (R4J section) Tree Data Migration.

    • On this page, all R4J activated projects will be listed as “Not Migrated”.

  2. At the bottom of the project list, select one or more projects or tick the checkbox "Select all projects across all pages".

  3. Click the Migrate button at the top of the table.

  4. 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". 

  5. 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.