Migrating from Server or Data Center to the Cloud

Who should read this page?

This document is for Jira administrators who are planning to migrate some or all of their projects from Jira Server or Jira Data Center to a Jira Cloud instance. It's about the Risk Register app specifically and explains how to include risk data in the data migration. Refer to the Atlassian Migration Centre for more general information about server-to-cloud migrations.

For conciseness, we'll hereafter refer to Jira Server and Jira Data Center collectively as 'the server'.

Why is this document necessary?

Atlassian produces a free app called Jira Cloud Migration Assistant (JCMA), which you can install in your Jira Server or Jira Data Center instance via the Atlassian Marketplace. The Risk Register app augments the JCMA to include risk data along with the core data - projects, issues, users, workflows, and so on - that JCMA migrates natively.

This document describes how to use the JCMA to migrate your Risk Register data to the cloud. It does not provide a user guide for JCMA itself; for that, refer to the JCMA documentation.

Compatibility

Support for automated migration of Risk Register data is provided by a combination of the JCMA and the Risk Register app. We recommend that you upgrade to the latest version of Risk Register before performing the migration. The minimum versions of those server-side apps required for automated migration are:

  • JCMA version 1.7.3

  • Risk Register version 6.2.21 (for use with Jira 8+) or version 6.2.21-j7 (for use with Jira 7.x)

Overview

When you include Risk Register in your automated migration with JCMA, various risk-related data are bundled up and delivered to the target Cloud instance. Those data include risk models, risk registers, risk assessments, and values assigned to the Treatment and Realization custom fields. Before beginning the migration process, you'll need to prepare your Jira Cloud instance to receive the risk data. The rest of this document describes how to do that.

Migration is project-based

The JCMA lets you nominate which projects are migrated across to the cloud. It’s important to understand that only Risk Register data about projects included in your migration will be transferred to the Cloud. If you add Project A to your migration, then only Project A’s risk data will be transferred. If you don’t include any projects in your migration, then no Risk Register data will be transferred. This enables larger installations to migrate their data incrementally.

The migration will always create new risk registers in the cloud corresponding to server-side risk register projects included in the data migration.

JCMA now offers a “Migrate all data at once” pathway. That operation will migrate risk data as if all projects in the source Jira instance had been selected.

Risk model migration

Both the server edition and Cloud editions of Risk Register support the use of multiple risk models. Risk models are automatically migrated by the JCMA when you have Risk Register installed.

Risk model inclusion in migrations

A risk model in the server will be migrated to the Cloud automatically if that risk model is explicitly associated with a project that is included in the migration, or if it is the default risk model and one of the projects in the migration is implicitly associated with the default risk model by virtue of not being explicitly associated with a risk model.

The naming of migrated risk models

Migrated risk models are given unique names on the Cloud side, according to the following rules:

  1. The string “ (migrated)” is appended to the name of the server-side risk model; for example: “Standard Risk Model” becomes “Standard Risk Model (migrated)”.

  2. If the risk model name from 1. is already assigned to an existing risk model in the Cloud, then a second candidate name is constructed by appending “ (migrated 2)” to the name of the server-side risk model.

  3. If the risk model name from 2. is already assigned to an existing risk model in the Cloud, then more candidate names are generated by incrementing the numeral until an unused name is found. In other words, candidates are generated by appending “ (migrated 3)”, and then “ (migrated 4)”, and so on.

The assignment of migrated risk models to projects

When you install Risk Register in Jira Cloud, a default risk model is automatically created for you. Since there can be only one default risk model in the Jira Cloud instance, any server-side default risk model included in the migration will become a non-default risk model on the Cloud side. It will be assigned to any projects included in the migration that used the default risk model on the server-side.

Any non-default risk model on the server-side will be created as a non-default risk model on the Cloud side and will only be assigned to projects that were migrated from the same server in this migration or in any migrations completed within the last 2 years.

Example: Suppose My Risk Model is assigned to Project A on the server, and My Other Risk Model on the cloud side is already assigned to Project A; then My Risk Model will be migrated to the cloud but will not be assigned to Project A.

We recommend you double-check the assignment of risk models to projects after the migration, to ensure that the right risk models will be applied to the risks in those projects. You can manually make any necessary corrections in the risk model editor.

Risk model collisions

A collision occurs when a risk model migrated by a previous migration is included in a subsequent migration attempt. In such cases, the following rules are applied:

  • If the previously-migrated risk model has not been changed on the Cloud side since it was migrated (it remains at version 1), then the risk model is not re-migrated on the subsequent attempt. Migrated risk assessments will reference the previously-migrated risk model.

  • If the previously-migrated risk model has been changed on the Cloud side since it was migrated, a new risk model will be created on the Cloud side upon the subsequent attempt. Migrated risk assessments will reference that newly-migrated risk model. The name of the new risk model will be constructed as explained under The naming of migrated risk models (above).

The migration of risk assessments

Risk assessments are the impact, probability, and risk level values assigned to risk issues. Risk assessments are automatically migrated if they are attached to the issues included in a migration.

The migration of risk assessments proceeds in two phases:

  • Risk assessments are attached to migrated issues and are linked to their migrated risk models.

  • Migrated risk assessments undergo harmonization.

If a server-side risk model could not be migrated for some reason, then any risk assessments based on that risk model won’t be migrated. Errors will be reported in the error log for those cases, and the migration will be marked as having failed.

The migration of custom fields

This section explains how the Risk Register app migrates data stored in various custom fields on the server.

In Jira Server/Data Center, the app stores data in two special custom field types: Risk Factor and Exposure. Impact, probability, realization, and treatment values are stored in Risk Factor fields; inherent risk and residual risk are stored in Exposure fields. Because JCMA doesn’t know about those special field types, the data they contain are not migrated by JCMA’s core migration phase.

Pre-migration report warnings

You’ll see messages in JCMA’s pre-migration report of this kind:

“The "Impact" custom field is not supported via migration. The value for this issue will not be migrated.”

You will also see warnings related to the “Risk Factor” custom field type, like this:

“The "Risk Factor" custom field type is not supported via migration. The configuration for this field will not be migrated and any items that reference it, such as workflow schemes and filters may no longer work.”

Those messages are normal and expected. You can ignore them. The second phase of JCMA’s migration is where the Risk Register app picks up the values of those special custom fields and migrates them to the cloud.

Migration of Treatment and Realization data

Most customers won’t need to perform any preparation steps to migrate Treatment and Realization values. If an administrator has manually changed the options for those fields in the server, you may need to make some adjustments before starting the migration.

In the cloud, the available options for Treatment are these:

  • Accept

  • Avoid

  • Mitigate

  • Transfer

The migration process assigns Treatments to issues in the cloud according to the indexes of the values transferred from the server. So a Treatment value from the server that is the second available option in the server will be assigned the second available option in the cloud, ‘Avoid’, no matter what the text value of that option may be in the server.

WARNING: If you have more than four options for Treatment in the server data may be lost in the migration. Any issues assigned the fifth and higher values in the server will be left unassigned with respect to migrated issues in the cloud.

We recommend that you make the Treatment options in the server the same as those in the cloud before beginning the data migration. In so doing, you may need to reassign some Treatment values in the server to make them fit into the four categories used by the cloud.

In the cloud, the available options for Realization are these:

  • Not realized

  • Realized

The Risk Register app migrates Realization values in the same way as Treatment fields, so the same cautions apply.

Workflow

JCMA’s pre-migration report will include messages related to transition validators and transition conditions attached to the workflow(s) that Risk Register created in Jira Server/Data Center. They look something like this:

“The "ImpactProvidedValidator" validator is not supported via migration. The workflow will still be migrated, however the validator on "Analyze" transition will be skipped, which may impact the permissions in your destination.”

The Jira Cloud edition of Risk Register does not automatically create risk management workflows and does not trigger workflow transitions like it does in the Server/Data Center product. In Jira Cloud, you can use any workflow you like, including the one migrated from the server with your risk issues. Automatic transitions between the states of that workflow will not be managed by the app.

Troubleshooting

If the JCMA core migration fails, a log file is produced that you can download and inspect. If you see errors of this kind:

“ABC project-import We couldn't import Custom Field 'Realization'. Reason: Cannot find an app custom field with name Realization and type com.projectbalm.riskregister.riskregister-jira:riskfactor-cf-type and key com.projectbalm.riskregister.riskregister-jira__realization.”

… you have not installed the Risk Register app in the target Jira Cloud instance. Simply install the app in Jira Cloud and rerun the migration.

Re-running a failed migration

A new feature of JCMA allows Server/Data Center administrators to re-run the app-specific components of a failed migration.

image-20240229-053237.png

Risk Register supports re-running of migrations, with the following caveats:

  • Risk models won’t be re-migrated unless you delete them from the Cloud side first

  • Risk registers from previous migrations won’t be overwritten. If you want to ensure that duplicate risk registers are not created in the target Cloud instance, delete the risk registers migrated previously before re-running the migration.

Search