Skip to main content
Skip table of contents

Migration path

We provide a partially automated migration path for Workflow Enhancer for Jira related conditions and validators that you can run after using Atlassian’s Cloud migration assistant.

Unfortunately, we cannot offer a fully automated migration path for conditions and validators at the moment, as Atlassian is currently not providing a way to support this for Forge apps. However, there is an open issue covering this topic, so we would appreciate votes there such that this blocker will be removed as soon as possible and we will be able to provide an automated solution.

If you are migrating with the Cloud migration assistant, conditions offered by Workflow Enhancer for Jira are not supported. The Cloud migration assistant will drop them upon migrating.

Table of Contents

Conditions and Validators

Prerequisites

For the migration of the Workflow Enhancer data, you must have completed the migration using Atlassian’s Cloud migration assistant. After that migration, your workflows will have been migrated to the Cloud, but they will be missing all conditions, validators and post-functions from Workflow Enhancer for Jira.

How to Export

  • Go to your Server respectively Data Center instance

  • Go to “Settings” → “Manage apps”

  • Go to “Workflow Enhancer” → “Cloud migration”

  • Click on “Download configuration”

  • Save the resulting JSON file on your hard drive

Please note that the export does not contain post functions as the Cloud version of Workflow Enhancer for Jira does not offer post functions.

How to Import

  • Go to your Cloud site

  • Go to “Settings” → “Apps”

  • Click on “Workflow Enhancer for Jira” on the left sidebar

  • Switch to the “Cloud migration import” tab

  • Click on “Upload configuration”

  • Upload the JSON file from the export

  • This will show you a table of all elements from Workflow Enhancer for Jira that you need to configure manually

Workflow Status

Next to the workflow name, there is a symbol that indicates the current status of the workflow, as such:

Workflow Status

Meaning

(tick)

The workflow contains the correct number of validators and conditions, and also all of them are correctly configured.

​⚠️

The number of validators or conditions in this workflow does not match with the uploaded configuration.

(error)

The workflow contains the correct number of validators and conditions, however some of them are not correctly configured.

Creating the Elements

The migration importer shows a table for every workflow that has elements from the Workflow Enhancer for Jira that need to be manually added to the Workflows.

Why do I need to create the elements manually?

Currently, it is not possible to create new workflow rules programmatically. Vote on https://ecosystem.atlassian.net/browse/FRGE-1330 to further automate this process.

Workflow

Link to the workflow that contains the migrated condition or validator

Transition

Link to the transition of the workflow that contains the migrated condition or validator

Type

Shows whether the element is a condition or a validator

Jira expression

The expression that is contained in the Universal Condition or Universal Validator. This is already in the Cloud format.

Error message

For validators, this shows the configured error message. If the validator did not have an error message configured in Server, this shows a default error message.

For conditions, this shows N/A because conditions don't have an error message

Status

  • (error) Shows that the condition or validator is not yet configured

  • (question) Shows that the condition or validator is configured correctly but contains parts that cannot be migrated automatically

  • (tick) Shows that the condition or validator is configured correctly

In order to manually configure your Workflow Enhancer for Jira elements, do the following steps for every condition or validator:

  1. Click on the transition link to get to the correct transition

    1. Click on “Create draft” if you do not have a draft for this workflow already

  2. Click on “Add condition” or “Add validator”

  3. Select “Universal Condition” or “Universal Validator” from the list

  4. Copy the correct configuration from the table

    1. Copy the Jira expression into the Jira expression input field

    2. Adapt the Jira expression if it has warnings inside the table

      1. For validators: Make sure to copy the error message into the error message input field as well.

  5. Click on “Add”

  6. After migrating and configuring all conditions and validators for a workflow: Publish the workflow.

  7. You can check whether you configured everything correctly by reloading the “Cloud migration import” page and re-uploading your configuration file.


Custom field migration

We are also offering Cloud migration support for expressions using custom fields.

  1. Have a Universal Validator or Universal Condition with an expression that checks a custom field

  2. Migrate the project including its custom fields using the Jira Cloud Migration Assistant

  3. Export and import the configuration as usual

  4. Check the warnings and the custom field id

  5. Find the custom field id in the Cloud inside the Custom Field administration or using the Workflow Enhancer

  6. Make sure that the Server id is mapped to the correct id in the Cloud.

Warnings

There are several elements that cannot be migrated automatically or can have potential for improvements after migration. These will be underlined in the table and you can get more information when hovering over these areas.

Warnings and Errors

Warning

Description

Suggestion

Example

USER_NAME_TO_ACCOUNT_ID

The Server version of the Workflow Enhancer compares fields with user pickers to their username. The username property is not existing in the Cloud.

Rewrite the expression to map against the displayName or the accountId of the user.

  • issue.assignee?.accountId == "admin"issue.assignee?.accountId == "03ec17bf-9dcc-48a5-9eb1-4cbd739275e2"

  • issue.reporter?.accountId != /.*a.*/issue.reporter?.displayName.match('.*a.*') == null

NULL_CHECK_WITH_ORDER_OPERATOR

You used an order operator with an empty clause. In Cloud, you need to compare the empty clause with null, so this may fail.

You probably want to use != or == instead of the order operator.

  • issue.assignee?.accountId < ""issue.assignee == null

RECURSIVE_FIELD_EVALUATION

In the Server version of Workflow Enhancer, the fields wrapped in { instead of {{ are recursively evaluated. A recursive field evaluation tries to recursively determine the field to take into account by recursively parsing the field value over and over. This behavior is not supported in the Cloud part, thus, we give a RECURSIVE_FIELD_EVALUATION warning for these cases.

You can use the toggle in the migration import page to choose not showing RECURSIVE_FIELD_EVALUATION warnings, if you do not care about recursively evaluated fields. It is very unlikely that you have relied on this feature. If you have not relied on this feature, you can keep these warnings hidden.

INVALID_ARITHMETIC_OPERATION

You try to do a non-allowed arithmetic operation. For example, you may have tried to add two Date values or add a Number value and a String value.

As a fallback, we take the expression on the left of the arithmetic operation. You should check the fallback expression and fix it manually if needed.

  • issue.created + issue.duedate > 12.12.2012 12:30issue.created > 12.12.2012 12:30

  • issue.summary - 5 == "test"issue.summary == "test"

UNKNOWN_ARITHMETIC_OPERATION

You have tried to make an arithmetic operation with an element that is not known to our automatic conversion.

You have to check the element that has failed, and change it with a suitable alternative if possible.

UNKNOWN_ELEMENT

You have tried to migrate an element that is not known to our automatic conversion.

The unknown element is not converted, you have to check the Jira expression manually.

UNKNOWN_CUSTOM_FIELD

You have tried to migrate a custom field that is not known to the transpiler and is not converted.

The unknown custom field is not converted, you have to check the Jira expression manually.

CUSTOM_FIELD_ID_MAPPING

You have tried to migrate a custom field. Its id could not be mapped during the transpilation.

Check the id of this custom field on the migrated Cloud configuration, and make sure that it is mapped to that id in the Cloud.

  • Example can be found here

UNTRANSPILABLE_CUSTOM_FIELD

You have tried to migrate a custom field which representations in Server / Data Center and Cloud are completely different. It is not possible to automatically convert them.

The custom field is not converted, you have to check the expression manually.

Information and Possible Improvements

Warning

Description

Suggestion

Example

REALTIMESPAN_CONVERSION

You have used an expression that contains a real time span in Server. This has been converted to seconds in Cloud. In order to represent the time span in seconds, some extra variables are added to the front of the Jira expression in Cloud.

This is just an informational warning.

  • issue.timeSpent == 3Wissue.timeSpent == 1814400 or

  • issue.timeSpent == 3Wissue.timeSpent == 3 * WEEKS

WORKTIMESPAN_CONVERSION

You have used an expression that contains a work time span in Server. This has been converted to seconds in Cloud. In order to represent the time span in seconds, some extra variables are added to the front of the Jira expression in Cloud.

This is just an informational warning.

  • issue.timeSpent == 1d 20minissue.timeSpent == 87600 or

  • issue.timeSpent == 1d 20minissue.timeSpent == 1 * WORK_DAYS + 20 * MINUTES

LABELS_IMPROVEMENT_SUGGESTION

During the migration, a Jira expression that contains labels, which is an array of String, is converted into its own String representation.

Please consider if you can replace the String representation with a direct assertion for issue.labels.

  • ('[' + issue.labels.join(', ') + ']') == "[]"issue.labels == []

FIX_VERSIONS_IMPROVEMENT_SUGGESTION

During the migration, a Jira expression that contains fixVersions, which is an array of String, is converted into its own String representation.

Please consider if you can replace the String representation with a direct assertion for issue.fixVersions.

  • ('[' + issue.fixVersions.map(item => item.name).join(', ') + ']') == /.*4.2.5.*/issue.fixVersions.map(version => version.name).some(versionName => versionName=="4.2.5")

AFFECTS_VERSIONS_IMPROVEMENT_SUGGESTION

During the migration a Jira expression that contains versions, which is an array of String, is converted into its own String representation.

Please consider if you can replace the String representation with a direct assertion for issue.versions.

  • ('[' + issue.versions.map(item => item.name).join(', ') + ']') == "[]"issue.versions == []

COMPONENTS_IMPROVEMENT_SUGGESTION

During the migration, a Jira expression that contains components, which is an array of String, converted into its own its String representation.

Please consider if you can replace the String representation with a direct assertion for issue.components.

  • ('[' + issue.components.map(item => item.name).join(', ') + ']') == "[component]"issue.components.map(item => item.name) = ['component']

LINKED_ISSUES_IMPROVEMENT_SUGGESTION

During the migration, a Jira expression that contains links, which is an array of String, converted into its own its String representation.

Please consider if you can replace the String representation with a direct assertion for issue.links.

  • ('[' + issue.links.map(item => item.name).join(', ') + ']') == "[]"issue.links == []

GROUPS_MACRO_IMPROVEMENT_SUGGESTION

During the migration, a Jira expression that contains groups, which is an array of String, is converted into its own String representation.

Please consider if you can replace the String representation with a direct assertion for user.groups.

  • ('[' + user.groups.join(', ') + ']') == /.*groupA.*/user.groups.includes('groupA')

ROLES_MACRO_IMPROVEMENT_SUGGESTION

During the migration, a Jira expression that contains roles, which is an array of String, is converted into its own String representation.

Please consider if you can replace the String representation with a direct assertion for user.getProjectRoles(project)

  • ("[" + user.getProjectRoles(project).map(item => item.name).join(",") + "]") == "[role]"user.getProjectRoles(project).map(item => item.name) == ['role']

SUBTASKS_MACRO_IMPROVEMENT_SUGGESTION

During the migration, a Jira expression that contains subtasks, which is an array of String, is converted into its own String representation.

Please consider if you can replace the String representation with a direct assertion for issue.subtasks

  • ('[' + issue.subtasks.map(subtask => ('[' + subtask.labels.join(', ') + ']')).join(', ') + ']').match('.*label.*') != nullissue.subtasks.flatMap(item => item.labels).includes('label')

Post Functions

Currently, post functions are not available in the Cloud version of Workflow Enhancer for Jira as Atlassian is currently not offering the necessary extension points (cf. https://ecosystem.atlassian.net/browse/FRGE-1230 ). Please feel free to vote and/or comment the linked issue in order to help us being able to provide post functions also for the Cloud version of Workflow Enhancer for Jira.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.