This page describes how to migrate Requirement Yogi Data Center to Confluence and Jira Cloud, using the official CCMA (Confluence Cloud Migration Assistant) and JCMA (Jira Cloud Migration Assistant).

Basically, you mostly need to trigger the CCMA / JMCA migrations and see what happens. This document is mostly a checklist to ensure the task will be successful.

Follow each steps

1. Before the Migration

2. Starting the migration

3. Ending the migration

4. Troubleshooting

What will be migrated?

Due to technical difficulties with the APIs, we have only just published the Phase 1 and 2 of CCMA. It will allow you to migrate requirements, external properties and Jira links.

*We’ve stopped working on the migration of reports, despite the demand for it, because it was outstandingly difficult and it was draining the resources of the company.

Overview of the migration process

1. Perform the prerequisite steps,

2. Open up the migration endpoint in Requirement Yogi Cloud (both Confluence and Jira),

3. Migrate the Confluence data,

4. Check and acknowledge the warnings and errors in Requirement Yogi for Confluence Cloud,

5. Migrate the Jira data,

6. Check and acknowledge the warnings and errors in Requirement Yogi for Jira Cloud,

7. The migration is done.

Required steps before migrating

4.1 Make sure permissions are correctly set up on Confluence Cloud

On the cloud, if you install an app, an “app user" is automatically created. This user is called Requirement Yogi for Confluence Cloud. Here are the steps to check the user can view and create pages in your spaces:

1. In Confluence Cloud → Settings → Security → Global Permissions:

   • Requirement Yogi for Confluence Cloud is expected to be in a user group in the User groups tab,

   • Requirement Yogi for Confluence Cloud is expected to be listed in the Apps tab,

   • If you need help, see the screenshots below.

2. In Confluence Cloud → Settings → Security → Space Permissions:

   • The user group assigned to Requirement Yogi is expected to be listed in the Default Space Permissions, with permissions to view and add Pages (Confluence doesn’t distinguish between add and edit permissions).

   • Individual spaces where you want to use Requirement Yogi are not expected to override the default space permissions for the RY user group.

   • If you need help, see the screenshots below.

4.2 Make sure permissions are correctly set up on Jira Cloud

The app automatically creates a Requirement Yogi user. Here are the steps to check the user can view and create pages in your spaces:

1. In Confluence Cloud → Settings → Security → Global Permissions:

   • Requirement Yogi for Confluence Cloud is expected to be in a user group in the User groups tab,

   • Requirement Yogi for Confluence Cloud is expected to be listed in the Apps tab,

   • If you need help, see the screenshots in Section 1.

2. In Confluence Cloud → Settings → Security → Space Permissions:

   • The user group assigned to Requirement Yogi is expected to be listed in the Default Space Permissions, with permissions to view and add Pages (Confluence doesn’t distinguish between add and edit permissions).

   • Individual spaces where you want to use Requirement Yogi are not expected to override the default space permissions for the RY user group.

   • If you need help, see the screenshots in Section 2.

4.2 Check page restrictions

Check page restrictions. Two solutions:

1. Either you manually include Requirement Yogi in those page restrictions to edit those pages, but that requires that you edit each page restriction,

2. Either you just let the migration fail, then use our Pages tab, searching for type=page AND macro=requirement AND ryc_isMigrated != true in CQL, and migrate all those pages manually in the future.

NB: We only need to edit pages during the migration. Once the migration is over, you can remove the pages permission for the app. Requirement Yogi uses the user’s permissions to transform the pages in the Transformation Wizard.

7. Open the migration endpoint:

In Confluence Cloud → Requirement Yogi configuration, in the Support tab, you should open up the migration endpoint. This enables Requirement Yogi to receive notifications from the server migration assistant. You can close it once the migration is over.

8. Do it again for the Jira part.

   1. If you are using multiple relationships for requirement-issue links in Server, make sure you create the same relationships in the RY for Jira Cloud administration as well. (See docs for more information: https://requirementyogi.atlassian.net/wiki/spaces/RYC/pages/1804764144/Requirement+Yogi+for+Jira#Administrate-Requirement-Issue-relationships )

Starting the migration

If you have both Jira and Confluence, you will have to start both migrations. We recommend doing the Confluence migration first. We will still create links to requirements that were not yet migrated, but show a warning that the requirement was not found.

In Confluence server, under General Configuration > Migration Assistant

• Mark Requirement Yogi as “Needed in cloud” (App assessment approval by Atlassian pending)

  

• Proceed to the rest of the migration steps required by Atlassian.

• Wait for the migration to complete.

  

App migration can take a long time to run, especially if you have thousands of pages. On our test instance, the migration took 20s per 1000 requirements (1h30 for a sample of 220k requirements spread on 2000 pages).

Check and acknowledge the warnings and errors in Requirement Yogi Cloud

You can check the migration notifications in the cloud by:

• Clicking on the link in the app migration details in CCMA (Confluence Server),

• Or in the cloud, in Requirement Yogi configuration:

  • By clicking the link in the support tab,

  • By going in the queue tab and clicking on the migration job,

  • 

Errors and warnings are listed on the notification page (Admin access required). Errors on pages have a link to the page that generated an error. You can go to the page and verify that the migration worked as planned, or manually edit the page yourself and mark the notification as “Resolved”

Please do feel free to open a ticket to notify us of errors generated by the migration tool by raising a support ticket.

End the migration

In the end, ensure you acknowledge the Requirement Yogi migration task on the Cloud side. It is important, so that the migration task on the server side knows that Requirement Yogi is done.

See typical warnings in the Troubleshooting page.

Limitations

• On the Cloud, pages containing requirements must be migrated to the new editor experience, since we only have transformers for the new JSON/ADF storage backend, and not for the XML one. The migration will be triggered when we apply the transformation.

• This “Phase 1 and 2” doesn’t import the RY Property, test macros, baselines, existing reports, and report macros to the Cloud.