Migration to the Cloud

Migration to the Cloud

Using an old version of Requirement Yogi?

Please head to Migrating to the Cloud (before RY Data Center 3.5). Or better: Upgrade and use the easy guide below!

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.

  • Requirements

    • As they are defined on Confluence pages, they will always be migrated, as well as their properties and dependencies.

  • External Properties.

Ready

  • Requirements links to Jira issues + relationship

Ready

  • Baselines

Ready with manual export/import.

Not within the CCMA but it is possible to manually export Baselines from Server and import them back to the Cloud.

  • Traceability Matrices

No, and we’ve stopped working on it*

  • Other RY macros on pages

  • Requirement Types

No, and we’ve stopped working on it*

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

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

  • requirement-baseline macros will not get migrated either.

*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

1

On the Server/DC side, upgrade the CCMA plugin to the latest version;

On the Server/DC side, upgrade the JCMA plugin to the latest version;

2

Upgrade Requirement Yogi for Confluence Server to the latest version (minimum 3.5.1)

Upgrade Requirement Yogi for Jira Server to the latest version (minimum 3.5.2)

3

Install Requirement Yogi on Confluence Cloud.

Install Requirement Yogi on Jira Cloud.

4

Make sure permissions are set up so we can view and create pages in your spaces:

  • More information in the FAQ.

Make sure permissions are set up so we can view and create issues in your projects:

  • More information in the FAQ.

5

Make sure pages with requirements on your Server / Data Center instance are not restricted.

  • If there are page-level restrictions, then the app will not be able to view/edit pages with requirements.

  • See possible solutions in the FAQ.

 

6

Open the migration endpoints:

  • In Confluence Cloud > Manage Apps > Requirement Yogi Administration > Support > Activate the Server / Cloud migration for this instance.

  • This enables Requirement Yogi to receive notifications from the server migration assistant. You can close it once the migration is over.

Open the migration endpoints:

  • In Jira Cloud > Manage Apps > Requirement Yogi Administration > Support > Activate the Server / Cloud migration for this instance.

  • This enables Requirement Yogi to receive notifications from the server migration assistant. You can close it once the migration is over.

7

 

If you are using multiple relationships for requirement-issue links in Server / Data Center, make sure you create the same relationships in the RY for Jira Cloud administration as well.

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.

In Jira, ensure you click “Choose what to migrate” (see screen below). In our tests, if you import everything at once, it… removes everything from the Jira instance, reimports something and forgets to install apps again, therefore Jira isn’t aware that it kicked Requirement Yogi out. In summary, select what you import, do not tick “Migrate all data”.

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

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

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

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.

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

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