On this page

Introduction

For readability reasons, we only refer to Data Center or DC on the following pages, but explicitly include Server here unless otherwise mentioned.

JWT has an automated migration path that assists with migrating from JWT DC to JWT Cloud. The automated migration uses the Jira Cloud Migration Assistant (JCMA) which is still in beta for app migrations. 

Pre-migration

  1. Please ensure that the correct version of JWT DC (version 3.3.0 or later) is installed on your Jira on-prem instance.
  2. Please ensure that the correct version of JWT Cloud is installed on your Jira Cloud instance.

  3. Make sure that you have Jira Cloud Migration Assistant in the list of user-installed apps on your Jira DC instance if you are running Jira < 8.1.4 (for higher Jira versions it is already pre-installed). If you don't, then go to "Find new apps" and download it. If it's already installed, please be sure to have it updated to the most recent version.
  4. None of the projects you want to migrate must already exist in Jira Cloud (not even in the trash). This also includes the corresponding inactive workflows/workflow schemes! 

Migration

  1. From your Jira DC instance, navigate to the System tab within the Jira administration and select Migrate to cloud from the Import and Export section of the left navigation.
  2. Follow the steps from the JCMA to define what you will migrate.
  3. In the Assess your apps step, make sure that you have marked Jira Workflow Toolbox status as Needed in cloud. If no green check is present, you have to upgrade to version JWT 3.3.0. Choose Not needed in cloud for xApps Library by Decadis.



What JCMA migrates

The JCMA migration runs project-based, i.e. only those JWT functions are migrated which are defined in one of the workflows belonging to the migrated projects. The Atlassian documentation describes in What gets migrated with the Jira Cloud Migration Assistant the details of a migration, How the Jira Cloud Migration Assistant links your data from Atlassian gives a detailed description of how JCMA handles certain data.

Nevertheless, we highlight specific scenarios, which you have to be aware of when migrating JWT:

  • Only those custom fields are migrated, which are associated to a screen of the projects migrated during the actual migration. They have a different customfield ID after migration.
  • Not all locked custom fields may be migrated, even if they are associated to the screen, and they are available per se in the Jira Cloud instance (e.g. "Epic color", "Original story points"). 
  • If entities with the same name already exist on Jira Cloud (e.g. custom fields when re-running a project's migration), a "migration" tag will be added to the name.
  • Only those resolutions, which are used by one of the issues of the currently migrated projects, are migrated.
  • Only those issue link types, which are used by one of the issues of the currently migrated projects, are migrated.
  • Global reflexive transitions are not migrated by JCMA.


You need to consider this information in contexts like

  • a conditional execution that compares to a certain resolution
  • using custom field codes in parser expressions
  • setting fields in Update or copy field values
What JWT app migration performs

Only JWT workflow functions are migrated.

Automation rules are and will not be part of JWT Cloud. The main reason is the availability of Atlassian's own automation engine

Calculated fields are and will not be part of JWT Cloud. In order to address our target audiences even more precisely, we have decided to deliver our calculated fields' functionality separately in the cloud in the form of Smart Fields for Jira.

JWT calendars are not part of JWT Cloud. This might change related to customer demand.

JWT JQL functions are not part of JWT Cloud. This might change related to customer demand.

Temporary fields are not part of JWT Cloud. This might change related to customer demand.

The automated migration follows the rules described for the manual migration (besides "Execute remote action" and "Add or remove watchers", which do not have an automated migration path so far). Specifically, this means that we cannot map all elements of a workflow rule or JWT parser expression exactly from JWT DC to JWT Cloud. The information which can be found in the column "Notes" of the description of the respective rules of the manual migration, e.g. Migrate 'Transition issue' is reflected as a feedback message in the Migration log. The same applies if a parameter/option is not present in JWT Cloud (marked with "-" in the documentation).

Due to the different feature set of JWT DC and JWT Cloud, some parameters/options/values available in JWT DC are not available in JWT Cloud. If possible, they are replaced by default values, e.g. if a non-user field is specified for the "Run as" parameter. In this case, it will be replaced by the "Current user".  Others will result in an error. These situations are reflected in the Migration log and include the following scenarios:

  • Field codes, e.g. Sprint start date
  • Custom field codes that were not migrated by JCMA
  • Parser functions that are not available on JWT Cloud, e.g. filterByFieldValue()
  • Missing values that were not migrated by JCMA, e.g. resolutions or link types
  • Parameters/options not available in JWTC, e.g. the option to copy the remaining fields in Create issue
  • Parameter values that are not present in JWT Cloud, e.g. non-user fields in the parameter "Run as"


Certain parameters and values are handled differently in JWT Cloud. This is reflected in the Migration log and include

  • that user field codes like %{issue.assignee} return the Atlassian account Id whereas JWT DC returns the user's name
  • that setting fields with a certain type like %{issue.version} (e.g. in Create issue) require using the ID of this field and not the plain value as in JWT DC.  This is not processed automatically by the migration and results in an error in the Migration log


The names of the migrated workflow rules may differ between JWT DC and JWT Cloud.

Examples: 

The latter applies to a number of conditions and validators. They have to be migrated to ones based on Jira expressions due to requirements from Jira Cloud. Especially JWT parser expressions are then not translated into Jira expressions (due to the very different paradigms used in both approaches). We strongly recommend checking the results in such cases (it may even happen that the migration results in an empty Jira expression):

Cancel and re-run a JCMA migration

JWT supports to cancel and, if necessary, to re-run a migration.

Note: Atlassian does not allow to cancel a migration before a certain amount of time has elapsed.


When a JWT app migration was canceled, the migration process might several minutes to finish the currently processed workflow rule. The JCMA status reflects this as CANCELING. Workflow rules that were already migrated before canceling will not be reverted in any way.


As soon as JWT successfully canceled the current migration, the JCMA status moves to INCOMPLETE.

If you choose to re-run the migration from the Actions drop-down menu, you will find additional migration entries in the Migration log, one for every migration run.

Note: If you have already migrated to the Cloud and need information regarding how to fix errors, see the Migration log.

Post-migration

After the migration has finished, JCMA displays a completion message.

We strongly recommend to check the Migration log in your target Cloud site, because it supports you with all the details on necessary post-migration tasks to be completed on your Cloud site.


Should you wish to consult the JCMA migration logs, use the Actions drop-down menu.

Newer versions of the JCMA do not display the above completion message anymore. Instead, you can choose to view the JCMA migration logs from the Actions drop-down menu.

Note: The JCMA migration logs are provided as a CSV file. The way the file is opened and displayed is dependent of your local computing environment, which may not be able to present you with a clickable link to our Migration log.

In case if any warnings or errors were found during the migration, this post-migration report shows a status of INCOMPLETE


If you still have questions, feel free to refer to our support team.