Please find all frequently asked questions regarding migration prerequisites, steps and troubleshooting in this page.

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

Expand
title Screenshots for Global Permissions:

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.

Expand
title Screenshots for Space permissions:

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: https://developer.atlassian.com/cloud/confluence/advanced-searching-using-cql/

3. If you want to know on which spaces requirements are defined

In your Data Center instance > Requirement Yogi Administration > Usage metrics, you will be able to find spaces where requirements are defined. This can be useful if you want to know on which spaces you should expect requirements to be created on your Confluence Cloud instance.

Troubleshooting

Lots of pages have permission errors

Anchor
manual-migration manual-migration

Explanations

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.

Severity

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.

Possible solutions

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

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

My app doesn’t process any pages

Possible solutions

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

I cannot find my requirements after a migration

1. If clicking on a requirement brings you to a ‘Requirement does not exist’ page

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.

My requirement is indexed, but it is missing properties.

In RY Cloud, the requirement definitions are assumed to be in the first column (or first row for vertical tables).

If your requirements are defined in another column, you’ll have to use the configuration macro to map the “requirement” column to the actual column in your table.

The manual transformation does not work

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 send us the page in storage format (Head to More actions / Advanced details / View storage format to retrieve it), and we’ll be happy to assist in the resolution of the issue.

Counting requirement macros (Server and Cloud)

You may want to check the requirement macro count from Server and compare it with the Cloud, to make sure everything is fully migrated.

On Server / Data Center

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

Option 2 - Count per space: Check the Requirement Yogi administration > Usage statistics, this will give you the requirement macro count per space, user and over time.

Note that the count for macros requirement adds up both requirement definition and requirement link macros.

Option 3 - Count of requirement definitions: In one space with requirements, click on Requirements in the sidebar, go to the Search.

On Cloud

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

Option 2 - 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.