Transformation - Migrate Server macros to Cloud

If you encounter issues during the migration where some pages are not migrated, do not worry, you will always be able to migrate pages at any time in the future.

If you want to know reasons why some pages are not migrated, please read the full documentation. Here’s a recap

• If there are restrictions on pages, which is very frequent. In case some pages are restricted, then the app’s user can’t view and edit those pages.

• Requirement Yogi can’t recognise the format of the page because of the legacy editor, or because requirements are embedded into other macros we cannot parse.

• Confluence rejects the modification, for example if Confluence rate-limited the app because it was performing too many modifications,

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

What types of macros do we transform?

Steps overview

Bulk transformation from the Migration Notification Page

This method can only be used if you have used CCMA, you will then be able to access the ‘Migration notification page’. There will be a button “Transform … remaining pages”. It may take a bit of time — up to about 10 seconds max to appear.

Click on the button and make sure you do not close the tab before the transformation is done.

Open

Conditions for the button to appear:

• The migration job is finished (Error, Cancelled, or Success)

• AND the CQL query to find non migrated macros returns pages.

Troubleshooting:

• It’s possible that even when the progress bar reaches the end, some pages remain (and the button is still there) → Refresh the page and try again.

  • This is because CQL may not give out all results at first (cache, rate limit or else) and you may have to trigger the search again with a refresh.

• If there is an error, the transformation currently will get stuck and you will need to refresh and restart the process.

Manual transformation, more accurate

1. Find Server / Data Center macros

Visually, there is a difference between the Server / Data Center macros, and the Cloud.

Server / Data Center	Cloud

Server / Data Center	Cloud
Open	Open
Macros from Server will usually have this message Unknown macro : 'macro-name'	This is a functioning macro in Cloud.

To find non-migrated macros, you can use CQL in our Requirement app:

• Navigate to Requirements > Transformations tab. Use the search (advanced CQL) and use this query: type=page AND macro=requirement AND ryc_isMigrated != true.

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

See more information here: Advanced searching using CQL

2. Apply the transformation in 1 page

To begin the manual transformation you need to first create and save a transformation on a single page. Then you will be able to apply it on multiple pages, by going into the ‘Transformations’ tab.

1	Click on the Requirement Yogi Byline (at the top of the page) > Transformation wizard	Open
2	Click “Add a transformation” → “Migrate Server macros to Cloud” → Save rule.	Open
3	Make sure you save this transformation by giving it a name, for example “Migration transformation". Click Transform.	Open

3. Transform all non-migrated pages in bulk

1	Make sure you have already saved the Transformation beforehand with Step 2 above. Then go to Requirement Yogi > Transformations	Open
2	Use the search to find non-migrated pages: Tick “Use CQL query”. Enter the CQL: type=page AND macro=requirement AND ryc_isMigrated != true.
3	Select all pages and click Transform. Please note the select all will save your selection if you have more than 10 pages and click on the next set of pages.

Do these steps until there aren’t any more non-migrated pages left in the space. You will have to create this transformation in each space and repeat the steps above on each spaces.

You can perform this step at any point in the future, if you notice that a page wasn’t migrated. Since this search is performed by space, you’ll need to repeat this operation in any space that requires it.

Have any questions ?

Reach out on the support: https://support.requirementyogi.com/