This article was written by Kamil Beer, an Atlassian Engineer at Idalko.
Handling the Atlassian apps is a part of a successful Cloud migration. As various teams come on board, they may need to install new add-ons and it’s common to see users working with features from ten or more plugins. And that might only be Jira (well don’t forget Confluence apps, too).
Migrating your Atlassian apps, however, is difficult and there is no means to move all apps while achieving the same set of features, not even with the Migration Assistants.
That’s why we decided to create this series of articles to help you migrate the most common add-ons safely and successfully.
So let’s get started!
Here’s what we cover in this blog post:
An Introduction to Migrating Apps
So what exactly is the challenge?
First, each app works in its own unique way, and there isn‘t a standard process you could follow for all of them. Moving a Jira workflow plugin will require a different approach than a Confluence diagramming add-on or an Outlook integration.
Second, Cloud and On-Prem apps usually aren’t identical. When you migrate the whole instance, what the add-ons can do won’t be the same. and sometimes the On-Prem features are already defined on Cloud, which happened with workflow plugins – JMWE or JSU.
Other times, however, the Cloud limitations simply don’t support the use case, like Scriptrunner’s Behaviour or User Switcher’s easy re-logging.
And sometimes, the corresponding Cloud app doesn’t even exist, which is the case with Rich Filters for Jira Dashboards (it’s currently under development though).
Technical Differences
Cloud and On-Prem apps also use different technologies.
Let’s have a quick look:
Frameworks and Programming Model
Server and Data Center apps are based on the “Atlassian Plugins” framework and run synchronously in the same Java Virtual Machine (JVM) as the main application. This allows users to call any part of the code. The add-ons are more customizable, but also more prone to crashes and performance issues after upgrades or version changes.
Cloud apps use “Atlassian Connect” and run separately. Thus, they can only communicate with it using REST API calls, limiting what the add-on can do. However, the API doesn’t change as much, which means the plugin isn’t as prone to malfunctions due to code change, nor is the main application if the app is buggy.
UI Customizations
On-premise, Javascript runs in the same context and frame as the host software. You can also customize the UI endlessly, thanks to direct code access. Because of this, Server apps suffer from similar code issues as mentioned above.
While you can’t modify the code on Cloud, some UI changes are available through the Atlassian Connect Javascript API. A list of the available modules is covered here.
Authentication and Authorization
On Server and DC, code can run under any user (or none at all) and bypass authentication and authorization. Cloud apps, on the other hand, have their own user executing the interactions. So bypassing would not be possible.
Migrate Scriptrunner
The first app we’ll look at is Adaptavist Scriptrunner. At the time of writing this article (August 2021), it‘s the top-selling add-on for Jira on-prem on the Atlassian Marketplace.
This guide covers both how to migrate it and also the critical differences between its Server and Cloud variants.
Feature (dis)parity
As Scriptrunner is based on inserting code, it immediately raises the question of how well this can be migrated. We can confirm: not very well. There are also other changes you should take into consideration first.
Let’s summarize what is known about the Cloud app:
- REST API: You cannot use the on-prem Java API on Cloud, only REST.
- Code: Most of the scripts on Cloud are still written in Groovy.
- Workflow: The features are similar, but some Conditions/Validators/Post functions have been deprecated, as Jira Cloud provides them natively. Those that remain need to be coded in the Atlassian Expression Language, not Groovy.
- JQL: About half of all functions were removed. Searching using the SR’s features is available through the Enhanced search interface.
- Services: Unavailable
- Behaviors: Unavailable
- Scripted Fields: There are some, however, they do not count as Jira fields, but as the issue’s properties, which aren’t JQL searchable. Their library is also non-existent. Issue, Database and LDAP pickers cannot be created.
- Built-in scripts: Only Bulk clone, Bulk fix resolutions, and Copy custom field values are available. The rest is unavailable. Running some of the Server scripts in the Console is possible, but with some limitations (see the end of paragraph).
- Listeners: You can still run Listeners, but their library is heavily reduced. Custom events and remote listeners were removed.
- Script console: Is available, but with reduced capabilities.
- Jobs: The minimum interval for running a job is one hour. Escalations can be made only for 50 issues at a time. Archiving is not possible.
- Fragments: Only web panels.
- Custom endpoints, database / LDAP connections, Script editor, Mail Handler, and Code insights are unavailable.
The code limitations in, for instance, Listeners or the Script Console are always subject to the platform REST API limitations and cannot run for more than 60 seconds. And, if Scriptrunner updates a page, users need to refresh it first.
Notable Differences
Some of the code needs to be changed. If you are using multiple issue.setX() functions in a script (e. g. issue.setFixVersions, issue.setCustomFieldValue), we suggest merging them into one operation. This is because each of these changes fires a notification – so they’re better off joined together to not spam users. For an example of a transformation, see here.
As fields are now being updated via REST API calls, they must be placed on issue edit screens, so that the API user can change them (as they would be able to do that manually).
How to Migrate Scriptrunner
ScriptRunner contains many different features, and you cannot migrate it with 1:1 parity through a click of a button.
To ensure a successful transfer, you can follow these steps:
Step 1: Investigate how much you use Scriptrunner. Browse each object type in System → Add-ons (e. g. Listeners, Jobs, REST Endpoints…) and write it down. You can easily identify Workflow Conditions, Validators, and Post functions using the Registry or Power Admin.
Step 2: It’s a good time to determine which Scripts you want to use on Cloud. For each, consider:
- Is this feature already available on Cloud or in an app you will have installed? Especially workflow functionalities, many of them are already included on Cloud.
- Can you implement the listener, job, or another SR object using Jira Automation (formerly Automation for Jira)?
- Is this feature even available on Cloud (e. g. Behaviors, Services)?
- Are you using any Java API extensions? Can they be transformed into REST ones? Or perhaps replaced?
After you narrow down the list of objects, you can start migrating. Great! The documentation will help you transfer the instance, it may also prove to be useful later, and finally, you have decluttered ScriptRunner.
The safest way to move is manually using your list. While the Migration Assistant transfers e. g. Fields, Custom Listeners, and Jobs (and transforms ScriptRunner’s JQL functions to Enhanced Search), taking manual control over the operation ensures that nothing breaks or disappears and the features are correctly adapted to Cloud.
By transferring an app like this, you’ll get a final overview of the parts which made it through.
As always, we recommend a test run on a staging Cloud instance to learn about possible issues on the way and to have a place to experiment with code changes.
Conclusion
Scriptrunner is a great app to begin our series of articles with. Having a myriad of use cases, many of which involve the application code or external integrations, it shows the difference between Cloud and Server plugins very well. These two types of add-ons also struggle with feature parity, and here, again, Scriptrunner is an excellent example. Adaptavist provides detailed documentation on this topic.
Still, while sometimes the vendors may try their best to make the transfer easy, even perhaps providing a mini-app to do so, some functionalities simply can’t be moved because of system limitations. However, often there are other options or workarounds to replace the on-prem features on Cloud. Along with performing a successful app migration, this will be one of our focuses in this series.
Recommended Reads:
- The Guide to Migrating Jira: Preparation, Planning, Testing, and Execution
- How to Prepare and Validate your Jira Test Instance after Changes or Migration
- Maintaining the Atlassian Stack: Best Practices
- Migration to Cloud: The Right Strategy to Migrate your Jira (Podcast)
