Migration to the Cloud

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. Migrate the Confluence data,

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

4. Migrate the Jira data,

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

6. The migration is done.

1. Required steps before migrating

2. Starting the migration

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

Open

Go to the Migration Assistant

In your Confluence Server / Data Center instance, go to the General Configuration > Migration Assistant.

• In the section ‘Assess your apps’, mark Requirement Yogi as “Needed in cloud”

  Open

  

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

• Keep track of the progress of the migration and wait for it to be complete.

  Open

  

💡 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).

3. Ending the Migration

How to check progress of the migration?

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 > Support > View the migration notifications.

How to check and acknowledge the warnings and errors?

• Errors and warnings are listed on the Requirement Yogi Migration Notification page (Admin access is required).

• Errors on pages have a link to the page that generated an error. You can navigate to said page and manually verify if the migration was a success. If the migration wasn’t successful (ex: Requirement Yogi macros are shown as ‘Unknown macros’), you can manually transform those macros 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.

Acknowledge the migration task

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.

Open

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.

Frequently Asked Questions

What is included in the RY for Confluence migration ?

The migration of our Confluence app only includes External Properties, and a transformation of requirement definition and requirement link macros from Server / Data Center to Cloud format.

What is not included in the Requirement Yogi migration ?

1. Some RY macros are not migrated and cannot be transformed with the migration / transformation wizard:

   1. For reports (requirement-report, requirement-report-pages), you’ll have to remove old macros and replace them manually with the RY Report.

   2. Requirement-property, you’ll have to remove those macros, and use the RY Configuration instead.

   3. requirement-baseline macros will not get migrated because we do not have an equivalent on the cloud.

2. Traceability Matrices and Requirement Types are also not migrated.

3. Baselines are not migrated within the CCMA, but they can be manually exported and reimported if necessary. Please find the documentation for more information.

What is included in the RY for Jira migration ?

The migration of our Jira app includes requirement links to Jira issues, also applying the relationships.

How to make sure permissions are correct in 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 your Confluence Cloud instance (not Atlassian admin) → 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 in the previous step is expected to be listed in the Default Space Permissions, with permissions to view and add pages.

   • Personal spaces where you want to use Requirement Yogi may not include the Default space permissions. You can make sure the permissions are correct by clicking on 'Manage access'.

   • If you need help, see the screenshots below.

How to make sure permissions are correct in Jira Cloud?

How do I make sure RY has the correct permissions for restricted pages?

If some pages are restricted, here are the possible solutions:

1. On Server / Data Center, remove all page restrictions by going into the Space Settings > Permissions > Restricted pages.

2. On the Cloud, you can manually include the Requirement Yogi app user for edit permissions. This requires that you edit each page restriction, and it can take some time if you have many.

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

How can I find non-migrated pages?

Most of the time, migration errors are caused by restricted pages, which prevent us from applying the transformation from Server / Data Center macros to Cloud format.

1. Using CQL

To find pages where the migration has failed navigate to Requirements > Pages tab. Use the search (advanced CQL) and use this query: type=page AND macro=requirement AND ryc_isMigrated != true. Note that it is possible to. migrate all those pages manually in the future with the Transformation Wizard.

2. Using the Rest API

You can use the Rest API to do a search on the whole space using this query: https://your-domain.atlassian.net/wiki/rest/api/content/search?cql=type=page AND macro=requirement AND ryc_isMigrated !=true

See more information here: Advanced searching using CQL