Forging Ahead: Lifting Enterprise Survey to Cloud with Atlassian's Migration Platform

[#1]

Did you ever have to organize a team event and had to implement some voting options for your colleagues using Confluence? Or did you have to gather opinions company-wide in Confluence? If so, you have probably heard of Mulitvote & Enterprise Survey for Confluence. This is one of our apps and it is available for Confluence Data Center (DC) as well as for Confluence Cloud. There was a missing puzzle piece to connect these two and open the migration path to the Cloud which is now completed. We want to share our story of how Multivote & Enterprise Survey now supports migrations from DC to the Cloud and what further challenges still lie ahead.

We are TNG Technology Consulting GmbH - a values-based consulting partnership focused on high-end information technology. We trust Atlassian’s products for our internal processes since the early 2000s and became an Atlassian Solution Partner in 2007.

Initially, we started developing open source plugins for Atlassian’s products to optimize our internal processes. By now this effort has evolved into a dedicated product team to support and expand upon what we have built so far.

Mulitvote & Enterprise Survey for Confluence has its origins back in those open source days and is the flagship of our app portfolio.

Multivote & Enterprise Survey for Confluence Migration Path

As the name suggests, Mulitvote & Enterprise Survey supports two main features, quickly set-up, light-weigth multivotes and complex, almighty Surveys. It made sense to tackle the migration of these features independently - but with which to start? Multivote DC offers more features than Multivote Cloud, meaning before the migration assistant we would have to do quite some other development work first. So we tackled the Surveys as we already have feature parity.

In order to migrate Surveys from DC to Cloud, we need to migrate both the data, i.e., the questions and responses, as well as the respective macro which renders the data on a Confluence page. Let’s have a quick look at both parts.

Data migration

As we focus on app development with Atlassian’s Forge, we utilize the Forge storage to store the Survey data. This means, we need to migrate the data from the DC database into the Forge storage in the Cloud. Atlassian has recently released support of Forge apps in their Cloud Migration Platform which makes the data migration for Forge app developers much more convenient. So what is it? In a nutshell, Atlassian provides an event-based platform which allows you to send your on-premise data to the Cloud. These events can then be picked up and processed by your Cloud app.

Macro migration

Why is it necessary to migrate the macros too? If you are familiar with Confluence DC and Confluence Cloud, you might have noticed that the page editors look and behave differently. While the Cloud editor is the new standard, the DC one is called the legacy editor. It is important to note that there is no feature parity between those and it is not clear whether there will ever be. During a Confluence Cloud migration the user has to perform the migration to the new editor manually to prevent possible data loss. We now also have to take care that our legacy macro gets converted to the cloud macro to live in this new environment.

What are Our Learnings?

A New Platform

The support of Forge apps in the Cloud Migration Platform was released by Atlassian three months ago. The event-based framework mentioned above is totally new for our app as well as to some of our developers. We think that we are among the first ones trying to roll this out in production. Since there were so many new components for the project, it is clear that not everything will work out perfectly first try. But let's flip the perspective: building something new on top of something innovative is actually really exciting. Plus, it will have a direct and tangible impact on our customers.

Code Generation

Another problem is that Mulitvote & Enterprise Survey for DC is written in Java while for Cloud it is Typescript. As long as these apps do not interact which each other (as they did until now), this is not a problem. However, now we want to move Surveys from one to the other. So a Survey object that is sent from server to cloud must have the same structure either in Java or in Typescript. Of course, you could just implement them accordingly. This, however, is susceptible to errors and it is very hard to maintain. Our solution is code generation! Just writing a single definition file, the code generators can produce the code for the so called Data Transfer Objects for Java and Typescript with the exact same semantics.

Forge Storage Limit

One downside of using the Forge storage is its limits which of course are necessary for the flawless operation of the Atlassian Cloud. Currently, the storage limit is 250KiB per entry, which determines the maximum size of a Survey. This limit can easily be exceeded, for example if you stored numerous images in your Survey. Right now, our only way of handling this to let the user know and suggest to reduce the size of their survey before migrating.

Error Handling

During the implementation, the error handling has grown a lot. There are just so many cases which might occur during a migration of Surveys: Survey data is not migrated, macros are not migrated, Surveys are too big, the new editor doesn’t support multi-nested expand macros, and so on. Of course, all potential combination of these errors must also be handled. We ended up with huge system which notifies the user as good as possible about any problems and their solutions.

Idempotency of Migrations

Ideally, one would only migrate once all data and apps from DC to Cloud. However, when it comes to actual migrations, customers may need to migrate multiple times, maybe for testing or to incrementally move to the Atlassian Cloud. So, what should happen with our app data in case a customer migrates multiple times? We had to consider quite some edge cases but managed to ensure idempotency when repeating migrations.

What is next?

Multivote

The Survey feature is now the first of two features which we will support to be migrated. The next one will be Multivote. As we have already mentioned above, there is still some work to do to reach feature parity. After that, we are prepared to tackle this next endeavor.

Automigration

It is always a good advice to improve the User Experience (UX) of your product. And there is room for improvement in migration assistant. We want to make the migration as easy as possible for the user. This not only makes the user happy but also decreases the load on our support channel. One way of doing so is to let the macro migration happen in the background as soon as the user changes from legacy to the new cloud editor.

Pre-migration checks

Speaking of better UX, it would also be nice to enlighten the user about possible problems upfront so they can better plan their Cloud migration. The Cloud Migration Platform allows for implementation of so called “App vendor checks” to do exactly that. For example, we could warn users about too large surveys in advance of a migration and allow them to adjust such surveys.

What Do You Think?

Have you had experience with Cloud migrations, the Migration Assistant or even the Migration Assistant for Forge? We are curious about your opinion.

[David Yu]

Hey David from app migrations thank you for sharing your experience and glad you are using our platform to help your customers migrate.

Feel free to provide feedback if there were any issues and gaps you encountered.

Since we are on the topic of sharing how to build great migrations for our customers here are some ideas that I collected over time. 

For your Server app: 

• Make migration listener fault tolerant - failure server side is difficult to debug
  • Handle exceptions
  • Add retries
• Handle app data upload failures - prone to network issues 
  • There are built-in retries but sometimes it is not enough
• Memory size (512MB) and compute time (55 seconds, 15 minute long compute EAP) is limited in Forge functions so a small upload size is recommended 
• Ensure correct access scopes otherwise migration API calls will fail e.g. retrieving exported app data

For your Forge app

• Monitor for server side errors and address them - they likely cause migrations to fail
  • avi:ecosystem.migration:errored:listener
• Use mappings to reduce API calls. - there are undocumented mappings
  • migration.getMappings()
• Idempotent functions are important to handle duplicate events and reruns 
• Don’t assume order of events listener triggered could come after app data uploaded
• Must call migration.messageProcessed() within 15 minutes otherwise Atlassian fails the migration
• Use migration.addLog() to communicate with customer e.g. reason for failure
• Forge tunnel can be used to stream logs to your local machine

Best practices

• Test at scale and large customer migration strategies e.g. parallel migrations, phased migrations
• Idempotent migrations i.e. re-runnable
• When a migration settles, migration APIs will return 403 response codes 
• Rate limits frequently hit from migrations - use exponential backoff strategy
• Test without devmode to ensure marketplace information is set correctly
• Migrate only required data, not all spaces and projects are migrated at once
  • Use the container API to find the relevant list of migrated spaces/projects

Hope that helps!