Versions Compared

Key

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

This article explains the steps required when migrating a Jira Server or Data Center instance to Jira Cloud when you were using JMWE workflow extensions on your Jira Server instance. 

...

titleJira Cloud Migration Assistant support

...

You can migrate JMWE data from Jira Server/Data Center to Jira

...

Background:

Because of the way Atlassian's Connect framework is implemented, workflow extensions (validators, conditions and post-functions) provided by add-ons are incompatible between JIRA Server and JIRA Cloud.  The entire JMWE configuration is contained within the workflows themselves. So you need to take a backup of your entire JIRA Server instance, identify the workflows and transitions that use JMWE workflow extensions, and fix them.

Challenges

Workflows using JMWE post-functions/conditions/validators in the Server will break on the Cloud because post-function configurations are incompatible with their Cloud equivalents.

  • Some workflow extensions are unavailable in the Cloud and hence they need to be removed
  • Some workflow extensions need to be completely recreated looking at their equivalents in the Server, followed by deleting the existing one in the Cloud
  • Some workflow extensions might be Run as a specific user which fail to reflect the user in the Run as section after the import. You will have to identify them, edit them and add the user in the configuration looking at the Server.
  • Some workflow extensions might use Groovy scripts either to execute the post-function conditionally or set a field value or comment an issue. Wherever you use Groovy scripts, write its equivalent Nunjucks template (in post-functions) or Jira expressions (in Conditions and Validators). You can test your Nunjucks scripts using the Nunjucks tester. Examples: 
  • Because of architectural differences between Jira Server and Jira Cloud, post-functions on Jira Cloud run asynchronously. This has two consequences:
    • You cannot rely on the order of execution of JMWE post-functions based on their position in the list of post-functions (unless you group post-functions in a "Sequence of post-functions" post-function)
    • Post-functions run after the transition completes, and thus after the issue is refreshed in the browser. Unless you take advantage of View Issue Page Actions, the result of post-functions will not be visible until you manually refresh the issue view page.

Missing features

Some features of workflow extensions mentioned below are unavailable in the Cloud. 

Migrating workflows

...

locationtop

Step 1 - Publish all your workflows

Before you begin fixing your workflows, publish all your workflows to avoid duplicate work (between the draft and corresponding published workflow)

Step 2 - Backup the Server instance

Using JIRA's XML backup utility backup your entire JIRA Server instance.

Step 3 - Manually edit the XML

  1. Extract the backup and open the entities.xml file with any text editor (one that can open large files)
  2. Edit the XML file to replace the Hide transition and Field is required validator with their equivalents
    1. Hide transition
      1. Search for <arg name="class.name">com.innovalog.jmwe.plugins.conditions.NonInteractiveCondition</arg>
      2. You should see XML for the condition similar to thisImage Removed
      3. Replace with <arg name="class.name">com.atlassian.jira.workflow.condition.RemoteOnlyCondition</arg> throughout the file using ReplaceAll.
      4. The replaced validator should look similar to this:Image Removed
    2. Field is required validator
      1. Search for <arg name="class.name">com.innovalog.jmwe.plugins.validators.FieldRequiredValidator</arg>
      2. You should see XML for the validator similar to thisImage Removed
      3. Edit the <validator>...</validator> element:
        1. Remove the <arg name="hidFieldsList"></arg> line, if it exists 
        2. Add this line: <arg name="contextHandling">no</arg>
        3. On the <arg name="fieldKey">...</arg> line replace, fieldKey with hidFieldsList
        4. On the same line, replace commas separating the fields with "@@"
        5. Add @@ after the last field
        6. Replace <arg name="class.name">com.innovalog.jmwe.plugins.validators.FieldRequiredValidator</arg> with <arg name="class.name">com.atlassian.jira.workflow.validator.FieldRequiredValidator</arg>
        7. The replaced validator should look similar to this:Image Removed
      4. Find the next instance of the search.
      5. Repeat step iii until you reach the end of the file.

By now, you will have completed the XML fixes for workflow conditions, validators and unavailable workflow post-functions. The remaining fixes must be done by recreating/modifying the post-function and deleting the existing ones.

Step 4 - Identify workflows and transitions using JMWE post-functions that need to be recreated

At the end of this step, you will create a table with the workflow name and the transition names of all the workflows containing JMWE post-functions that need to be recreated

...

Transition Names

...

Workflow Name

...

Search for the text - <arg name="class.name">com.innovalog.jmwe.plugins.functions.UnlinkIssuesFunction</arg>

...

Work your way up on the file from the line that contains <arg name="class.name">com.innovalog.jmwe.plugins.functions.UnlinkIssuesFunction</arg> to find the name of the transition on which the post-function is configured. You can identify it under the <actions> tag.

...

Write down the transition name in the table.

...

Work your way up further on the file from the line you have found the transition, to find the name of the workflow. You can identify it under the <Workflow> tag. 

...

Write down the workflow name

...

Find the next instance of <arg name="class.name">com.innovalog.jmwe.plugins.functions.UnlinkIssuesFunction</arg>

...

Now you will have a list of transitions and their corresponding workflow name.

...

Work your way up on the file from the line that contains <arg name="class.name">com.innovalog.jmwe.plugins.functions.LinkIssuesFunction</arg> to find the name of the transition on which the post-function is configured. You can identify it under the <actions> tag.

Write down the transition name in the table.

...

Work your way up further on the file from the line you have found the transition, to find the name of the workflow. You can identify it under the <Workflow> tag. 

Write down the workflow name.

...

Find the next instance of <arg name="class.name">com.innovalog.jmwe.plugins.functions.LinkIssuesFunction</arg>

...

Repeat steps b to g until you reach the end of the file.

Now you will have a list of transitions and their corresponding workflow name.

...

Work your way up on the file from the line that contains <arg name="class.name">com.innovalog.jmwe.plugins.functions.EmailIssueFunction</arg> to find the name of the transition on which the post-function is configured. You can identify it under the <actions> tag.

Write down the transition name in the table.

...

Work your way up further on the file from the line you have found the transition, to find the name of the workflow. You can identify it under the <Workflow> tag. 

Write down the workflow name.

...

Find the next instance of <arg name="class.name">com.innovalog.jmwe.plugins.functions.EmailIssueFunction</arg>

...

Repeat steps b to g until you reach the end of the file.

Now you will have a list of transitions and their corresponding workflow name.

...

Work your way up on the file from the line that contains <arg name="class.name">com.innovalog.jmwe.plugins.functions.CreateIssueFunction</arg> to find the name of the transition on which the post-function is configured. You can identify it under the <actions> tag.

Write down the transition name in the table.

...

Work your way up further on the file from the line you have found the transition, to find the name of the workflow. You can identify it under the <Workflow> tag. 

Write down the workflow name.

...

Find the next instance of <arg name="class.name">com.innovalog.jmwe.plugins.functions.CreateIssueFunction</arg>

...

Repeat steps b to g until you reach the end of the file.

Now you will have a list of transitions and their corresponding workflow name.

...

Sort the table by Workflow name

...

Step 5 - Identify workflows and transitions using JMWE post-functions that need rework

In this step identify workflows and transitions using JMWE post-functions that need rework. At the end of this step you will have three tables with workflows, transitions and post-functions that have:

  • Groovy scripts in the Conditional execution section
  • Groovy expressions or Groovy templates to set a field of an issue or comment an issue
  • a specific user in the Run as section

Identify post-functions with Conditional execution script

...

  1. <arg name="class.name">com.innovalog.jmwe.plugins.functions.CreateIssueFunction</arg>
  2. <arg name="class.name">com.innovalog.jmwe.plugins.functions.EmailIssueFunction</arg>
  3. <arg name="class.name">com.innovalog.jmwe.plugins.functions.LinkIssuesFunction</arg>
  4. <arg name="class.name">com.innovalog.jmwe.plugins.functions.UnlinkIssuesFunction</arg>

If not write down the name of the post-function looking at the class name.

...

Work your way up on the file from the line that contains <arg name="useGroovyCondition">yes</arg> to find the name of the transition on which the post-function is configured. You can identify it under the <actions> tag.

Write down the transition name in the table.

...

Work your way up further on the file from the line you have found the transition, to find the name of the workflow. You can identify it under the <Workflow> tag. 

Write down the workflow name.

...

Find the next instance of the search

...

Repeat steps 2 to 10 until you reach the end of the file.

Now you will have a list of transitions and their corresponding workflow name for post-functions that have a conditional execution script.

...

Identify post-functions with Groovy template to set a field value or comment an issue

...

  1. <arg name="class.name">com.innovalog.jmwe.plugins.functions.CreateIssueFunction</arg>
  2. <arg name="class.name">com.innovalog.jmwe.plugins.functions.EmailIssueFunction</arg>
  3. <arg name="class.name">com.innovalog.jmwe.plugins.functions.LinkIssuesFunction</arg>
  4. <arg name="class.name">com.innovalog.jmwe.plugins.functions.UnlinkIssuesFunction</arg>

If not, write down the name of the post-function looking at the class name

...

Work your way up on the file from the line that contains <arg name="valueType">template</arg> to find the name of the transition on which the post-function is configured. You can identify it under the <actions> tag.

Write down the transition name in the table.

...

Work your way up further on the file from the line you have found the transition, to find the name of the workflow. You can identify it under the <Workflow> tag. 

Write down the workflow name.

...

Find the next instance of the search

...

Repeat steps b to j until you reach the end of the file.

Now you will have a list of transitions and their corresponding workflow name with post-functions that have a Groovy template.

...

  1. <arg name="class.name">com.innovalog.jmwe.plugins.functions.CreateIssueFunction</arg>
  2. <arg name="class.name">com.innovalog.jmwe.plugins.functions.EmailIssueFunction</arg>
  3. <arg name="class.name">com.innovalog.jmwe.plugins.functions.LinkIssuesFunction</arg>
  4. <arg name="class.name">com.innovalog.jmwe.plugins.functions.UnlinkIssuesFunction</arg>

If not, write down the name of the post-function looking at the class name

...

Work your way up on the file from the line that contains <arg name="valueType">expression</arg> to find the name of the transition on which the post-function is configured. You can identify it under the <actions> tag.

Write down the transition name in the table.

...

Work your way up further on the file from the line you have found the transition, to find the name of the workflow. You can identify it under the <Workflow> tag. 

Write down the workflow name.

...

Find the next instance of the search

...

Repeat steps b to j until you reach the end of the file.

Now you will have a list of transitions and their corresponding workflow name with post-functions that have a Groovy expression.

...

Identify post-functions with Run as specific user

...

  1. <arg name="class.name">com.innovalog.jmwe.plugins.functions.CreateIssueFunction</arg>
  2. <arg name="class.name">com.innovalog.jmwe.plugins.functions.EmailIssueFunction</arg>
  3. <arg name="class.name">com.innovalog.jmwe.plugins.functions.LinkIssuesFunction</arg>
  4. <arg name="class.name">com.innovalog.jmwe.plugins.functions.UnlinkIssuesFunction</arg>

If not write down the name of the post-function looking at the class name

...

work your way up on the file from the line that contains <arg name="runAsUser"> to find the name of the transition on which the validator is configured. You can identify it under the <actions> tag.

Write down the transition name in the table.

...

Work your way up further on the file from the line you have found the transition, to find the name of the workflow. You can identify it under the <Workflow> tag. 

Write down the workflow name.

...

Find the next instance of the search

...

Repeat steps 2 to 10 until you reach the end of the file.

Now you will have a list of transitions and their corresponding workflow name with post-functions that are run as a specific user.

...

Now prepare a single table sorting it based on the Workflow name, Transition name. Add the count if a transition has a post-function more than once, as shown in the table

...

Step 6 - Import the backup into your JIRA Cloud instance

  1. Re-zip the extracted files.
    1. In Windows: Select all the extracted files and re-zip them using any tool, say 7z or
    2. In Linux: Navigate to the directory where the files are that you want to zip. Then type: zip newbackup file1 file2 file3
    3. In Mac: Navigate to the directory where the files are that you want to zip. Then type: zip -r backup.zip newbackup.zip
  2. Log in to JIRA Cloud as an administrator.
  3. Import the backup into your JIRA Cloud instance using Jira Import Wizard in Import and Export section.

Step 7 - Install the JMWE add-on

See here to know how to install the JMWE add-on

Step 8 - Fix your workflows

In this step you will do the remaining fixes:

  • Recreating the workflow extension and deleting the existing ones or
  • Edit the workflow extension and modify it.

Recreate the workflow extensions in Jira Cloud

  1. Refer to the table prepared in Step 4
  2. For each affected workflow listed in the table, open the workflow in an edit mode in the Cloud and Server. 
    1. For each affected transition listed of the workflow, go to that transition in the editor and then to the Post-functions tab.
    2. Locate the post-function in JIRA Cloud. You can easily identify JMWE post-functions imported from Server because they appear strange with the Class: com.innovalog.jmwe.plugins.functions.UnlinkIssuesFunction similar to this:
      Image Removed
    3. Identify the name of the post-function looking at the class name (look at the end of the line).
    4. Locate the same post-function in JIRA Server by its position in the list and edit it to see its full configuration.
    5. Recreate the post-function:
      1. Click on Add post-function in JIRA Cloud.
      2. Recreate the post-function looking at its equivalent configuration in JIRA Server.
    6. Move the post-function right before the existing post-function
    7. Delete the existing post-function in JIRA Cloud.
  3. Once all the transitions in a workflow are fixed, publish the workflow.

Modify the workflow extensions in Jira Cloud

...

  1. For each affected transition listed for the workflow, go to that transition in the editor and then to the Post-functions tab.
    1. For each post-function listed in the table locate the Post-function in JIRA Cloud looking at the same post-function in JIRA Server by its position in the list.
    2. Edit the post-function. If the fix is for
      1. A Conditional execution/Groovy expression/Groovy template, look at the script in the Server and write a Nunjucks template that is equivalent to the existing one. Save the post-function.
      2. The Run as specific user, look at the selected user in the Server and select the same in the Cloud. Save the post-function.

...

JMWE supports automated migration using the Jira Cloud Migration Assistant (JCMA) in versions 7.2.0 and later.

Automated Path using JCMA for later versions

JMWE for Jira Server/Data Center 7.2.0 and later has an automated path for migrating from Server to Cloud. If you are running JMWE version 7.2.0 or later, please refer the article on migrating using the JCMA.

Manual migrations

Prior to supporting automated migration using JCMA, migrations needed to be done manually. Although not recommended, you can migrate earlier versions of JMWE for Server/Data Center (prior to 7.2.0) by referring to the article on manual migration. Again, this is not recommended. We strongly advise upgrading to the latest version (7.2.0 or above) and using the automated path using JCMA.