Last updated Nov 9, 2023

Rate this page:

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.

  • The app vendor check feature is available in the Jira Cloud Migration Assistant (JCMA) version 1.9.0 and higher by default. This means you won't need to use feature flag to enable this feature.
  • The app vendor check feature is available in the Confluence Cloud Migration Assistant (CCMA) version 3.4.3 and higher by default. This means you won't need to use feature flag to enable this feature.


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.

    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.

    Rate this page: