Migrating Tree Data for versions prior to easeRequirements 4.7

What to expect

After the easeRequirements 4.7.x upgrade, not migrated projects are blocked from usage and may cause unexpected errors in easeRequirements 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 easeRequirements 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 easeRequirements upgrade and tree data migration. If possible, the migration should take place outside of business hours.

• easeRequirements 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

• easeRequirements 4.7 tree data is not backward compatible with older versions of easeRequirements as stated in our release notes.

• Check out our tree loading and filtering test benchmarks: easeRequirements 4.6.x vs 4.7.x performance benchmark results.

Step 1: Pre-requisite - Execute easeRequirements Integrity Checker BEFORE upgrading

In your current easeRequirements version (4.6.x or less), run the Integrity Checker before upgrading to easeRequirements 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 easeRequirements 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 easeRequirements.

Executing the revision cleanup process is a required upgrade step from easeRequirements 4.5. Read more: Cleaning up the R4J revision history data.

Step 4: Migrate the tree data

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

   • On this page, all easeRequirements 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 easeRequirements operations for it will be unblocked and users can continue using this project in easeRequirements.

   • 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/easeRequirements-migrate-logger<timestamp>.log

   • Do random checks on easeRequirements 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.