Migrate App Data from a Server app to a Forge app

[#1]

Ever since the end of sale announcement for Server and the release of Forge, more and more apps have been migrated to the Cloud using the Forge framework. While Atlassian continuously develops on the Forge framework, there are still a lot of gaps.

One of the biggest issues we and our customers are facing is the migration path from their Server or Data Center instance to the Cloud. Atlassian provides automated migration support with the Jira / Confluence migration assistant, which is also capable of migrating apps from Server to Cloud. Unfortunately, this does not include Forge apps. This means that all migrating customers need to reconfigure all apps that rely on Forge. Apps that store their own state (e.g., voting history) will not migrate this, and hence customers will lose their data.

Furthermore, this is especially hard-hitting for macros, as all migrated Confluence pages are migrated to the legacy editor. As Forge apps cannot be added to the legacy editor, there is no way for a vendor to automatically map the server macro instances to the new ones - and this information will also be lost when migrating.

In our last communications with Atlassian, they made the point that they are in the process of providing an automated migration path for the data of Server apps to the Cloud Forge counterparts, but also drew attention to the fact that this will still take some time (https://jira.atlassian.com/browse/MIG-771). As we want to provide aid for our customers swiftly so that they can migrate as soon as possible with our Apps, we started building a semi-automated migration path for one of our apps: Workflow Enhancer for Jira.

Cloud Migration for Forge Apps

Workflow Enhancer for Jira provides customized validators and conditions for workflows. When running the default Jira Cloud migration assistant, it will recognize that there are workflow transition rules that don’t have an automated migration path in the Jira Cloud migration assistant, and thus will be removed. This information is hidden inside the pre- and/or post-migration report, so it can easily be missed.

Category,Referenced by project,Impacted type,Impacted name,Problem,Description,Next steps
Unsupported,JCM,Workflow,"""JCM: Project Management Workflow""",Transition condition,"The ""UniversalCondition"" condition is not supported via migration. The workflow will still be migrated, however the condition on ""Stop Progress"" transition will be skipped, which may impact the permissions in your destination.","Review the workflow post migration to ensure the permissions are set correctly. To check which workflows may be affected during pre-migration, run SQL queries from this page: https://confluence.atlassian.com/jirakb/troubleshooting-errors-and-non-migrated-entities-with-the-jira-cloud-migration-assistant-1021239878.html"
Unsupported,JCM,Workflow,"""JCM: Project Management Workflow""",Transition validator,"The ""UniversalValidator"" validator is not supported via migration. The workflow will still be migrated, however the validator on ""Reopen"" transition will be skipped, which may impact the permissions in your destination.","Review the workflow post migration to ensure the permissions are set correctly. To check which workflows may be affected during pre-migration, run SQL queries from this page: https://confluence.atlassian.com/jirakb/troubleshooting-errors-and-non-migrated-entities-with-the-jira-cloud-migration-assistant-1021239878.html"

As our customers' business processes heavily rely on restrictions on the workflow transitions, our customers need to go through all workflows by hand, review them and fix missing validators and/or conditions.

Custom Migration Assistant

To improve the migration experience, we provide a custom migration tooling directly built inside our app, giving you the current status of the migration of the Workflow Enhancer’s configuration.

Firstly, you can download the full data of the Workflow Enhancer configuration from your Server instance as a JSON file.

 

Then, you can upload this configuration file on our app’s Cloud migration import page on your Cloud site.

This will show you the current status of the Workflow Enhancer’s migration. It will list for you all workflows that contain workflow transition rules of the Workflow Enhancer, the respective transition, their type and the content of the elements in the format that is necessary for the Cloud version. In the final column, it will display the status, i.e. whether the rules have already been configured correctly on the Cloud site or not.

Unfortunately, Atlassian does not provide an endpoint to directly create the workflow transition rules automatically, so you will need to click on the link to the Transition, add the Workflow Enhancer condition or validator there, and copy the necessary configuration inside.

Highlights

We took the extra mile and made a smart conversion with giving as many hints for the new Cloud format version as feasible on the underlined parts. Many things will change between Server and Cloud formats - and the Cloud version is much cleaner which you will appreciate. You can also have a look with our code editor when entering the new expressions which you hopefully will enjoy as much as we did building it!

Limitations

Some hints need to be fixed by yourself due to the fact that we do not have the information from the Jira Migration assistance present. For example, in the server version, Workflow Enhancer for Jira compares fields to the username of a user. In the Cloud, the username property is replaced with the accountId, but this mapping is only known to the Jira Migration assistant, meaning we cannot get this information. This has to be done manually by the user, at least until Atlassian provides access to the Cloud migration assistant for Forge apps.

Outlook

We would like to improve the migration assistant in a way that the workflow transition rules are automatically created and configured. For that, we would need a REST endpoint similar to this, that allows for creation instead of updating workflow transition rules. Then, we could offer customers a button that automatically creates all elements, and they would only need to have a look at workflow transition rules with warnings.

Finally, the goal would be to integrate our migration into the Jira Cloud migration assistant as soon as this is possible.

Additionally, we’re evaluating possibilities on how to provide a similar migration assistant for our apps that provide Dashboard gadgets (Custom Content for Jira and Bar Charts for Jira) and for Confluence macros (Multivote & Enterprise Survey for Confluence).