Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Info

Using an old version of Requirement Yogi?

Please head to Migrating to the Cloud (before RY Data Center 3.5). Or better: Upgrade and use the easy guide below!

This page describes how to migrate Requirement Yogi Data Center to Confluence and Jira Cloud, using the official CCMA (Confluence Cloud Migration Assistant) and JCMA (Jira Cloud Migration Assistant).

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.

Follow each steps

...

Before the Migration

...

Starting the migration

...

Ending the migration

...

Table of Contents
minLevel1
maxLevel3
outlinefalse
styledefault
typelist
printabletrue

What will be migrated?

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, external properties and Jira links.

  • Requirements

    • As they are defined on Confluence pages, they will always be migrated, as well as their properties and dependencies.

  • External Properties.

(tick) Ready

  • Requirements links to Jira issues + relationship

(tick) Ready

  • Baselines

(tick) Ready with manual export/import.

Not within the CCMA but it is possible to manually export Baselines from Server and import them back to the Cloud (since 4.2.14)

  • Traceability Matrices

(error) No, and we’ve stopped working on it*

  • Other RY macros on pages

  • Requirement Types

(error) No, and we’ve stopped working on it*

  • For reports (requirement-report, requirement-report-pages), you’ll have to remove old macros and replace them 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 either.

*We’ve stopped working on the migration of 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

...

Make sure permissions are set up so we can view and create pages in your spaces:

More information in the FAQ. issues projects

RY for Confluence

RY for Jira

1

On the Server/DC side, upgrade the CCMA plugin to the latest version;

On the Server/DC side, upgrade the JCMA plugin to the latest version;

2

Upgrade Requirement Yogi for Confluence Server to the latest version (minimum 3.5.1)

Upgrade Requirement Yogi for Jira Server to the latest version (minimum 3.5.2)

3

Install Requirement Yogi on Confluence Cloud.

Install Requirement Yogi on Jira Cloud.

4

Once the installation is complete, make sure you link your RY for Confluence and RY for Jira instances together, see docs.

5

Make sure permissions are set up so we can view and create

pages in your

spaces:

  • More information in the FAQ.

56

Make sure pages with requirements on your Server / Data Center instance are not restricted.

  • If there are page-level restrictions, then the app will not be able to view/edit pages with requirements.

  • See possible solutions in the FAQ.

67

Open the migration endpoints:

  • In Confluence Cloud > Manage Apps > Requirement Yogi Administration > Support > Activate the Server / Cloud migration for this instance.

  • This enables Requirement Yogi to receive notifications from the server migration assistant. You can close it once the migration is over.

Open the migration endpoints:

  • In Jira Cloud > Manage Apps > Requirement Yogi Administration > Support > Activate the Server / Cloud migration for this instance.

  • This enables Requirement Yogi to receive notifications from the server migration assistant. You can close it once the migration is over.

78

If you are using multiple relationships for requirement-issue links in Server / Data Center, make sure you create the same relationships in the RY for Jira Cloud administration as well.

...

See typical warnings in the Troubleshooting page.

...

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.

Frequently Asked 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.

...

titleScreenshots for Global Permissions:

...

RY Global permissions.pngImage Removed

  1. 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
titleScreenshots for Space permissions:
RY Space permissions.pngImage Removed

How to make sure permissions are correct in Jira Cloud?

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.

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

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

...

Info

Using an old version of Requirement Yogi?

Please head to Migrating to the Cloud (before RY Data Center 3.5). Or better: Upgrade and use the easy guide below!