Last updated Sep 4, 2024

Prepare your server app for Forge migration

This page explains how to prepare your server app for migration to Forge using the Atlassian app cloud migration library.

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.

Make sure you always use the latest version of the library.

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

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

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 the DiscoverableForgeListener interface for enabling Forge migrations. The methods to be implemented are:

Method	Description
`onStartAppMigration`	Core product migration is complete. Server app can begin Forge migration at this point.
`getForgeAppId`	The Forge app ID to which the migration is being carried out to.
`getForgeEnvironmentName`	The Forge environment to which the migration is being carried out to. This is by default set to "development" when not specified.
`getCloudAppKey`	The cloud app key of your Forge app to which the migration is being exported to. You will need to specify a cloud key listed on Marketplace to enable App Assessment. During development, you can ignore this field.
`getServerAppKey`	The server app key for where the migration is being exported from. When using atlassian-app-cloud-migration-listener this is not required if your app key is the same as your OSGi bundle name.
`getDataAccessScopes`	The data access scopes required to access the migration mappings.

See an example

1
2
@Override
public void onStartAppMigration(AppCloudForgeMigrationGateway gateway, MigrationDetailsV1 migrationDetails) {
    PaginatedMapping paginatedMapping = gateway.getPaginatedMapping("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 UUID getForgeAppId() {
    // Example Forge app ID - "1234abcd-efgh-4ucb-bc95-e006kd08e0e6"
    return UUID.fromString("your-forge-app-id");
}

@Override
public String getForgeEnvironmentName() {
    return ForgeEnvironmentName.DEVELOPMENT;
}

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

@Override
public String getServerAppKey() {
    return "your-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));
}

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 Assistants (JCMA/CCMA) that supports Forge migrations.
Have the latest plugin of your server app available with the Forge listener.