| Tip |
|---|
This page describes how to migrate Requirement Yogi data to Confluence and Jira Cloud, using the official CCMA* and JCMA**. * CCMA: Confluence Cloud Migration Assistant |
| Info |
|---|
Using an old version of Requirement Yogi? Please head to Migrating to the Cloud (before RY 3.5). Or better: Upgrade and use the easy guide below! |
It’s quite simple!
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.
What you will be able to migrate
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 on pages |
|
Requirements links on Jira issues |
|
Baselines |
|
Other entities (reports, etc.) |
|
Ready
No, and we’ve stopped working on it*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.
*We’ve stopped working on the migration of baselines and other 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
Perform the prerequisite steps,
Open up the migration endpoint in Requirement Yogi Cloud (both Confluence and Jira),
Migrate the Confluence data,
Check and acknowledge the warnings and errors in Requirement Yogi for Confluence Cloud,
Migrate the Jira data,
Check and acknowledge the warnings and errors in Requirement Yogi for Jira Cloud,
The migration is done.
Before migrating
You need to:
On the Server/DC side, upgrade the CCMA plugin to the latest version: https://marketplace.atlassian.com/apps/1219672/confluence-cloud-migration-assistant?hosting=datacenter&tab=overview
Same for the JCMA plugin in Jira,
Update Requirement Yogi to the latest version, and minimum 3.5.1: https://marketplace.atlassian.com/apps/1212523/requirements-yogi?hosting=server&tab=versions (3.5.2 for the Jira part),
Install Requirement Yogi on the cloud: https://marketplace.atlassian.com/apps/1212523/requirements-yogi?hosting=cloud&tab=overview (Same for the Jira part)
Verify that the The app automatically creates a Requirement Yogi user. Here are the steps to check the user can view and create pages in your spaces. Follow steps below to check this.:
In Confluence Cloud → Settings → Security → Global Permissions:
Requirement Yogi Core (Spring Boot)
is expected to be
in a user group in the User groups tab,
Requirement Yogi Core (Spring Boot)
is expected to be listed in the Apps tab,
If you need help, see the screenshots in the section 1 of the child page Screenshots related to configuring CCMA and JCMA .
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 the section 2 of the child page Screenshots related to configuring CCMA and JCMA .
NB: We only need to edit pages during the migration. Once the migration is over, you can remove the add pages permission for the app. Requirement Yogi uses the user’s permissions to transform the pages in the Transformation Wizard.
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.
Do it again for the Jira part.
Differences between Cloud and Server
In the Cloud:
Data is stored in the cloud (https://requirementyogi.atlassian.net/wiki/spaces/RYC/pages/1804763557/Privacy+Policy#How-we-host-and-transfer-data-internationally ).
You don’t have access to a REST API, or the database, or server logs.
There is no report macro embeddable in documents (yet
).There are no baselines (replaced by variants in the cloud : Variants ).
You cannot display the requirement's details in a popup when hovering over a requirement in Confluence.
We cannot highlight a requirement in a page, or scroll down the page to show the requirement.
The cloud editor seems to struggle with tables of over 100 requirements. We advise splitting your documents in multiple pages if that is the case for you. ⚠️
To add requirements in bulk, you can use the Page transformations instead of the inline edits,
You can create and validate rules for your requirements (Validation rules )
Configuring requirement properties is done through the Requirement Yogi Configuration macro (Configuring requirement properties )
Our server is shared between customers, and we apply limits to some operations (like the traceability matrix) to avoid impacting the app performance for other customers.
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.
| Note |
|---|
In Jira, ensure you click “Choose what to migrate” (see screen below). In our trials, 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”. |
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 (https://requirementyogi.atlassian.net/servicedesk/customer/portal/1/group/1/create/9 )
At 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.
Troubleshooting
My app doesn’t process any pages?
Verify that the app user has view and edit permissions on the page. (Permission settings are handled by Atlassian)
The migration of requirement macros to the cloud format involves searching for pages containing requirement macros. Unfortunately, the search sometimes returns incomplete results and mistakenly assumes that no more pages need to be migrated. In that case, you can run the migration job again by clicking the “Retry” button in the Queue tab.
You can also manually run the transformation wizard (Page transformations ) to transform server macros to cloud macros.
My requirements are not found after a migration?
If clicking on a requirement brings you to a similar page.
Most often, it simply means that the page has not yet been indexed.
Verify the state of the queue in the Confluence Settings > Atlassian Marketplace > Requirement Yogi > Queue
Verify especially jobs with a Failed status, so you can retry them or contact the support team.
Indexation is triggered by an event on page modifications sent by Atlassian. Events can take a few minutes, or rarely hours before we receive them.
You can also queue the indexation of a page by clicking on the “Refresh” icon in the Requirement Yogi byline.
