.png?version=1&modificationDate=1750854922486&cacheVersion=1&api=v2&width=746 "Requirement Yogi (Data Center) > FAQ & Troubleshooting > RY Global permissions (User groups).png")
After performing the Cloud migration process of Requirement Yogi, it is possible that you encounter some issues. Check our guide to fix those issues. |
Please find all frequently asked questions regarding migration prerequisites, steps and troubleshooting in this page.
đĄ Please note that the RY for Confluence migration only triggers the migration of external properties and a transformation of requirement macros from Server to Cloud. If you encounter some issues during your migration, most of the times requirement data will not be lost because they are attached to their Confluence pages. Itâs always possible to transform non-migrated requirements later on with a manual transformation.
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.
At any time, if some requirements are not migrated, you can use a manual transformation to migrate Server macros to Cloud: https://confluence.intranet.requirementyogi.com/wiki/spaces/RY/pages/1847132161/How+to+manually+migrate+pages+from+Server+to+Cloud?atlOrigin=eyJpIjoiMDIzNDFlZjJlYjVmNDliNTg2OWViZmQ0YzI0YTExYjQiLCJwIjoiYyJ9 .
Some RY macros are not migrated and cannot be transformed with the migration / transformation wizard:
For reports (requirement-report, requirement-report-pages), youâll have to remove old macros and replace them manually 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 because we do not have an equivalent on the cloud.
Traceability Matrices and Requirement Types are also not migrated.
Baselines are not migrated within the CCMA, but they can be manually exported and reimported if necessary. Please find the documentation for more information.
The migration of our Jira app includes requirement links to Jira issues, also applying the relationships.
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:
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.
|
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.
 |
If some pages are restricted, here are the possible solutions:
On Server / Data Center, remove all page restrictions by going into the Space Settings > Permissions > Restricted pages.
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.
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.
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.
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.
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: https://developer.atlassian.com/cloud/confluence/advanced-searching-using-cql/
You may want to check the requirement macro count from Server and compare it with the Cloud, to make sure everything is fully migrated.
Count for whole instance: Check the macro usage in Confluence Administration, this will give you the count of all requirement yogi macros over the whole instance.
Count per space: Check the Requirement Yogi administration > Usage statistics, this will give you the requirement macro count per space, user and over time. This can be useful if you want to know on which spaces you should expect requirements to be created on your Confluence Cloud instance.
Note that the count for macros requirement adds up both requirement definition and requirement link macros.
Count of requirement definitions: In one space with requirements, click on Requirements in the sidebar, go to the Search.
Count for whole instance: Check the Confluence Administration > Data Management > Macro Usage, this will give you the count of all requirement yogi macros over the whole instance.
Count per space: Check the Requirement Yogi administration > Usage, this will give you the requirement definition macro count per space.
This is different than Server, the Requirement counts only adds requirement definition macros and not the link macros.
If some requirement counts donât add up, itâs because the count on the cloud doesnât count for Server / Data Center macros. In that case, it probably means some of your requirements have failed to be transformed into Cloud macros. See more information to find requirements, and to transform them manually.
It is possible to use the transformation wizard to manually migrate server macros to Cloud macros but you will lose your External properties.
It is not possible to perform the migration manually in bulk in Jira. Once you perform the JCMA and migrate your Jira issues, it is possible to relink existing requirements to Jira but this will require some work.
Information you need to extract from your Server / Data Center instance are: Requirement ids, Issue keys, and relationships.
Open a traceability matrix in any space of your Confluence Server instance (with administrator permissions).
Use the search query jira is not null to only display requirements with Jira links,
Add a new column: Column heading â cog menu â Jira â All issues,
Important: Click âCross-space searchâ at the top-right.
Export the matrix in Excel if you need to.
Then go to each Jira issue on the Cloud, and create the links manually: https://confluence.intranet.requirementyogi.com/wiki/spaces/RYC/pages/2191917075/Advanced+Bulk+link+requirements+to+Jira+issues?atlOrigin=eyJpIjoiMThjMmU0NTI0OWNmNGIwMWIxY2Y1ZmIzM2JhOTY3MGQiLCJwIjoiYyJ9 .
If your migration is stuck at 99%, itâs probably because there are some warnings you need to acknowledge.
You can manually acknowledge warnings in the RY Migration Notifications and fix errors later. See the rest of the page for more information.
When pages are restricted (view), our app user âRequirement Yogi for Confluence Cloudâ cannot see which pages have requirements or not, and thus will not be able to transform Server macros into Cloud. This will cause an error, and possibly prevent the migration from going into success.
If some pages are restricted, it is not a blocking issue for you as a user because it is still possible to transform Server macros into Cloud macros manually. This may take you some time, but this type of error can be acknowledged and fixed later on.
Stop and re-run the migration after fixing permissions issues:
You can stop the migration manually, and fix the permissions manually:
Remove page-level restrictions on your Data Center instance, see docs.
Make sure the RY for Confluence Cloud app user has permissions to view and edit pages, as seen in this documentation.
Once the permissions are fixed, you can re-run a migration. Please note that itâs always possible to run the Confluence migration without Requirement Yogi, and then perform a separate migration only with the app.
Acknowledge the errors manually and migrate macros with the Transformation Wizard
When there is an error in the RY Migration notifications, there should be a link to the restricted page. Server macros will appear like âUnknown macro: requirementâ.
Manually click on Resolve to acknowledge the errors.
Note this will not actually resolve the issue, it will only allow you to update the status of the migration so you can end it.
Once the migration is ended, you can process to the manual migration of macros with the transformation wizard, view full documentation.
đĄ The upside of transforming the pages manually, is that this action is performed using the current userâs credentials, instead of the app's credentials.
There may be some permissions error.
Make sure the RY for Confluence app user has view and edit permissions on pages, see more information.
There may be a CQL error and a timeout.
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.
If too many pages are in fail, note you can also manually run the transformation wizard to transform server macros to cloud macros, see more information.
If clicking on a requirement lands on a âRequirement does not existâ page:
Most often, it simply means that the page has not yet been indexed.
As long as requirement macros are on pages, you will always be able to index them again and we will automatically recover the requirementâs properties, dependencies etc.
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, when editing and updating a page, we should receive a indexation event. 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.
In Requirement Yogi for Confluence Cloud, the requirement definition macros are expected to be in the 1st column starting at 2nd row with a horizontal table, or 2nd column - 1st row for vertical tables.
In some cases, your table headers may also have a wrong set up.
This is not a blocking issue, properties are the content of your requirement table, in the Confluence page. As long as you have your Confluence page, your properties will exist for your requirements.
If your requirements are defined in another column, you can use the configuration macro to map the ârequirementâ column to the actual column in your table. You can apply this solution on multiple pages using the transformation wizard.
You can also edit the settings of the table to set the âHeader rowâ or âHeader columnâ. You can apply this solution on multiple pages using the transformation wizard.
There can be some cases in the migration where the editor of the page is still in âLegacyâ and we cannot parse the content of the page and perform the transformation.
There can be some cases where your requirement tables are embedded inside another macro, which prevents us from parsing the content of the page and performing the transformation.
If the manual transformation fails, please try to convert the page to the new (Cloud) editor instead of the legacy editor.
If it still fails after that, please reach out to the support with the storage format of the page:
Click on More actions > Advanced details > View storage format
If you still have questions or would like some reassurance and clarifications, please feel free to reach out. Our team will be happy to help: https://support.requirementyogi.com/.