Possible scenarios impacting app migration journey, with solutions

This notice provides information about an issue the App migration platform team has detected that may impact your app migration journey.

As you know, when your migration path is ready, you’ll need to use the Marketplace migration APIs to publish a new version of your server app and surface it in the Cloud Migration Assistants. We provide the OSGI library, and the Tracker library to help your server app integrate with the Cloud Migration Assistants.

With regard to the above setup, we have detected 2 scenarios that may have an unexpected impact on our customers.

Scenario 1: Customers install a server app with a migration path in a Confluence/Jira instance that does not have the Cloud Migration Assistant installed.

Scenario 2: Customers install a server app with a migration path in a Confluence/Jira instance that has an outdated version of the Cloud Migration Assistant installed (prior to App migrations).

In both the above scenarios, the impact on your migration journey depends on how you have implemented your migration path. The section below details the implementation options and resulting impact.

Implementation Impact
Server app uses OSGI dynamic dependencies No impact. Your app will install normally.
Server app uses the OSGI library The App will fail to install. The customer will not be able to install the latest version of your app and will need to install an old version to be able to use it.
Server app uses the Tracker library 2 things can happen:
  • The app is installed normally. If the migration assistant is installed later, app migration will not work.

  • Install fails and the app is disabled.

What is the solution?

Our team has published a fix for the Tracker library. This fix also resolves the issue of app’s module in a disabled state after OSGI restart. Learn more

If you’re currently using the Tracker library, you should update your app to use the latest version of the Tracker library.

The team is working on a new way for server apps to integrate with our platform, which will replace the current libraries. The new solution will offer a new way for your apps to integrate with the App migration platform without being dependent on the Cloud Migration Assistants. Your apps will not need to register themselves in the migration assistant. Instead, the migration assistant will scan for apps that have exposed a listener object.

How to fix the current problem for the Tracker library

In order to fix the current problem with the -tracker lib, you will need to:

  1. In the atlassian-plugin.xml file, remove the following code:
        <bundle-instructions>
            <DynamicImport-Package>
                com.atlassian.migration.app.*
            </DynamicImport-Package>
        </bundle-instructions
  1. In the pom.xml file, update atlassian-app-cloud-migration-tracker to the latest version (1.21) :
        <dependency>
            <groupId>com.atlassian</groupId>
            <artifactId>atlassian-app-cloud-migration-tracker</artifactId>
            <version>1.21</version>
        </dependency>`

Add the dynamic import tag inside element:

    <DynamicImport-Package>
        com.atlassian.migration.app
    </DynamicImport-Package>`

Update the element with

!com.atlassian.migration.app

In the end your element should look like:

 <instructions>
    <Atlassian-Plugin-Key>${atlassian.plugin.key}</Atlassian-Plugin-Key>
      <!-- Add dynamic package import here -->
        <DynamicImport-Package>
          com.atlassian.migration.app
        </DynamicImport-Package>
        <!-- Add package import here -->
          <Import-Package>
            !com.atlassian.migration.app,
            org.springframework.osgi.*;resolution:="optional",
            org.eclipse.gemini.blueprint.*;resolution:="optional",
               *
          </Import-Package>

          <!-- Ensure plugin is spring powered -->
          <Spring-Context>*</Spring-Context>
 </instructions>`
  1. If there is any app-migration-tracker.properties, remove it.

What do you need to do now

You can still work on your migration path. However, do not publish your app to Marketplace as a public version if you have not tested your app with the scenarios explained above.

What do you need to do when the new solution is released

We’ll publish details about the new solution soon. Existing libraries will still be available but the goal is to deprecate the tracker library eventually. We’ll give you time to make the change and support these libraries but the only way to fix the problem indefinitely will be to stop registering your listeners and expose them instead.

How this impacts participation in the customer EAP

Publishing your migration path publicly to Marketplace is the best option and we’re currently targeting this option for the EAP. But if you’re unable to make the changes on time for EAP, you will need to publish your migration path as a private version or provide a jar to Atlassian so our support team can install it in our customers’ instances.

3 Likes

Thank you, this is very much appreciated. Is there any kind of timeline for this? We’re just about to start implementing the integration with the migration app and it would be very helpful to know if we should just wait a little bit longer.

Hi Jens. We don’t have a confident timeline yet. We have some unknowns around how to ensure retro-compatibility of the old approach when we release the new one. But as we’ll maintain retro-compatibility, you don’t need to wait. Your integration won’t break when we release the new approach. And the changes required to use the new one might be minimal as your listener or logic won’t need to change, only the way to expose it to the migration assistant.

1 Like