Last updated Feb 5, 2024

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.


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



Expose an OSGi component that implements the following interface:

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.


  • 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></>

The above tags are included in the character limit (1050) for check.

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 time limit for each check execution is 5 minutes, with a global time limit of 10 minutes for all checks.

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

statusThe various states of CheckResult are:
  • SUCCESS - The check didn't find any issues and can proceed with the migration
  • WARNING - There were issues found but customer can still proceed
  • BLOCKING - There is an issue that will prevent the app from migrating. This status currently creates the same customer experience as WARNING status, it does not block the migration. We plan to enable the blocking behaviour in the future.
  • CHECK_EXECUTION_ERROR - The check couldn't be completed as it encountered a problem
  • stepsToResolveKeyThis is the template that the check should display to the customer. This value should correspond to the key that was provided in the CheckSpec.stepsToResolve field. If the value does not match, no instructions will be rendered in the user interface.
    CSV fileIn the event that there is a need to provide context as to which specific areas the issues were found for (e.g The following Jira tickets have permission problems), you can provide a csv file for the customer to download. The file size limit is 250kb or 250 characters per row, of up to 1000 rows per check. If the file exceeds these limits, it will be truncated.

    Sample app

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

    Rate this page: