Server listener set-up

This page explains how to set up the communication between your server app and the App migration platform.

Registering your server app for migration will allow you to:

• Enable app migration in your server app
• Get notified by the App migration platform when core data migration is complete, and app data migration starts. This will allow you to access/read mappings related to core product data (you can access the same mappings by making a request from your cloud site).
• Upload your app-related data to Atlassian's secure cloud storage

Use the App cloud migration library

The App cloud migration library is an interface component that allows developers to create migration listeners on their server apps. Only one listener should be registered per server app key, however multiple server apps can send data to a single cloud app. The Cloud Migration Assistants (CCMA/JCMA) export the library's classes in the runtime. The library has no external dependencies, which avoids conflicts with the tech stack that your app uses.

This section explains three options for a dependency that you can add to utilize the App cloud migration library. This addition will allow your server app to integrate with the Cloud Migration Assistants.

Make sure to always use the latest version available.

Option 1: atlassian-app-cloud-migration-listener

This option has no dependency between Cloud Migration Assistants and your app. This is the simplest approach.

1
2
<dependency>
  <groupId>com.atlassian</groupId>
  <artifactId>atlassian-app-cloud-migration-listener</artifactId>
  <version>1.0.3</version>
</dependency>

See an example of how to use the atlassian-app-cloud-migration-listener dependency.

Option 2: atlassian-app-cloud-migration-tracker

This option does the following:

• Track the changes on the OSGi context
• Behaves like a buffer for events that can be managed (like when the Cloud Migration Assistant restarts)

1
2
<dependency>
    <groupId>com.atlassian</groupId>
    <artifactId>atlassian-app-cloud-migration-tracker</artifactId>
    <version>1.26.1</version>
</dependency>

See an example of how to use the atlassian-app-cloud-migration-tracker dependency.

Option 3: atlassian-app-cloud-migration-osgi

This option has dependency between Cloud Migration Assistants and your app.

1
2
<dependency>
    <groupId>com.atlassian</groupId>
    <artifactId>atlassian-app-cloud-migration-osgi</artifactId>
    <version>1.0.0</version>
</dependency>

See an example of how to use the atlassian-app-cloud-migration-osgi dependency.

See a comparison of the libraries.

A version catalogue and information about their end-of-life policy can be found on the library version page.

Implement the interface

You will need to implement a listener interface. Depending on the library you are using this can be DiscoverableListener, AppCloudMigrationListenerV1 or CloudMigrationListenerV1. The methods to be implemented are:

atlassian-app-cloud-migration-listener

See an example

1
2
@Override
public void onStartAppMigration(String transferId, MigrationDetailsV1 migrationDetails) {
    PaginatedMapping paginatedMapping = gateway.getPaginatedMapping(transferId, "confluence:page", 5);
    while (paginatedMapping.next()) {
        try {
            Map<String, String> mappings = paginatedMapping.getMapping();
            log.info("mappings = {}", new ObjectMapper().writeValueAsString(mappings));
        } catch (IOException e) {
            log.error("Error retrieving migration mappings", e);
        }
    }
}

@Override
public String getCloudAppKey() {
    return "my-cloud-app-key";
}

@Override
public String getServerAppKey() {
    return "my-server-app-key";
}

@Override
public Set<AccessScope> getDataAccessScopes() {
    return Stream.of(
            APP_DATA_OTHER, PRODUCT_DATA_OTHER, MIGRATION_TRACING_IDENTITY, MIGRATION_TRACING_PRODUCT
    ).collect(Collectors.toCollection(HashSet::new));
}

Register the listener (options 2 and 3 only)

Use the class that you have implemented to register on the following gateway: AppCloudMigrationGateway

See an example

1
2
public class MyPluginComponentImpl implements MyPluginComponent, DisposableBean {

  private final AppCloudMigrationGateway gateway;

  public MyPluginComponentImpl(AppCloudMigrationGateway migrationGateway) {
    this.gateway = migrationGateway;
    this.gateway.registerListener(this);
  }
}

The gateway will also expose the following methods to your app:

See an example

The example that follows uses deregisterListener to deregister the listener.

1
2
@Override
public void destroy() throws Exception {
    gateway.deregisterListener(this);
}

Test the server app implementation in your local environment

You can test your implementation and changes locally through these steps:

• Add the dependency to use the App cloud migration library

• Install and run the Jira or Confluence Cloud Migration Assistant (JCMA/CCMA)

• Have the latest plugin of your server app available with the listener