Troubleshooting

Owned by Mileva Briand
Last updated: Oct 30, 2024
3 min read

There is a permission error on a lot of pages

You can click on the page link to view the page. You will see unmigrated macros in yellow.

  • Either you did not allow the app to edit pages, as seen above,

  • Either you did, but there are page-level restrictions, and pages can’t be processed,

  • In either case, you can process pages later on, after the end of the migration. 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.

To process pages manually:

 

  • Create a transformation named, for example, “Migration”:

    • Go to a non-migrated page in the space,

    • In the top-right “…” menu, click “Requirement Yogi”. A dialog appears.

    • Click “Add step” → “Migration from Server to Cloud”,

    • Before executing this step, there should be an input box named “Transformation name:”. If there is a value, it will save this transformation for the current space, so that you can repeat it.

    • Click Transform.

    • You will have to create this transformation in each space.

  • Transform the pages in bulk:

    • Go to the Requirements tab in the sidebar,

    • Open the “Pages” tab, so reach the same screen as the screenshot above,

    • Tick “Use CQL query”,

    • Enter the CQL: type=page AND macro=requirement AND ryc_isMigrated != true

    • Select all pages and click Transform,

    • Do it until there are no unmigrated pages left in the space.

  • Repeat on other spaces.

  • Again, the upside of this method is, as an external consultant you don’t need to fiddle with the permissions, you can just ask your customer to perform this operation with their own permissions.

You can also 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

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 (Transformation wizard: Transform your pages ) to transform server macros to cloud macros.

 

I cannot find my requirements 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.

 

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.