Set up app vendor checks

This page explains how to set up app vendor checks for the Cloud Migration Assistant (CMA), to make migration more successful for you and your customers.

Libraries

To create pre-migration app vendor checks, use the atlassian-app-cloud-migration-listener v1.1.0 or above.

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

Interfaces

Expose an OSGi component that implements the following interface:

1
2
public interface PreMigrationCheckRepository {
  Set<CheckSpec> getAvailableChecks();

  CheckResult executeCheck(String checkId, MigrationPlanContext context);
}

Field details

Implement the getAvailableChecks() method to return the static specs of the checks that your app supports called CheckSpec. It requires the following attributes:

• checkId: An internal identifier of the check. You must ensure that this identifier is unique across all checks.
• title: This is the title that will be displayed to the customer and has a maximum limit of 60 characters.
• description: This is a short description of what this check does. Currently not used in the UI but provides a way to add information on what this check is about.
• stepsToResolve - This is a key value pair of templates that instructs the customer on how to resolve this check. Each CheckSpec can have multiple templates stored and used during the execution of executeCheck(). The maximum character limit for each template is 1050.

Limits

• We currently support only 3 checks for each app. If you create more than 3 checks, the app migration platform cannot guarantee the execution of the checks above the check limit, nor the priority order in which the checks will be executed.

• We encourage the use of the isValid() method when writing a CheckSpec. This is to ensure that the check written is within the character limit, and returns a list of error messages in case there are issues with the checks. If CheckSpec is deemed invalid, the content of the check gets truncated to the prescribed limit.

Formatting the body of the check

Use any of the following tags to format stepsToResolve:

• <paragraph></>
• <ordered-item></>
• <unordered-item></>

These tags can be used in any combination and order. For example, a paragraph can be followed by ordered-item, and then another paragraph) as long as it does not exceed the character limit. We encourage that the proper tags are written and tested in the user interface to verify how the rendering works. We cannot ensure that the steps will display correctly if the tags are not used as recommended.

The executeCheck() method

The executeCheck() method is invoked when the user is getting ready to perform a migration. If your app supports multiple checks, each one will trigger a different execution of this method with their respective checkId.

The executeCheck() method returns a CheckResult which is composed of the following:

Known Issues

"Download Report" button not working

This issue affects Jira Cloud Migration Assistant versions 1.9.8 to 1.9.13. It is fixed in version 1.9.14

When the state of a check result is WARNING and the user selects the Download report button in the migration assistant, the operation fails and returns an HTTP 500 error with the following message: UnableToWriteCsvException: Csv content is empty. The error occurs even when CSV content has been provided.

Related ticket: MIG-1482

Sample app

We have provided a sample implementation of the app vendor check for your reference.