Last updated Dec 7, 2022

Rate this page:

Building App vendor checks

This page provides information on how you can build app vendor checks for the Cloud Migration Assistant. Read our doc for more information on how app vendor checks work and how to write effective checks to make migration more successful for you and your customers.

The App vendor check feature is currently available for Marketplace Partners in the Jira Cloud Migration Assistant (JCMA) version 1.7.7 and higher by enabling the feature flag com.atlassian.jira.migration-assistant.enable.app-vendor-check.

Watch our Changelog for future updates about the public release of this feature for customers in the CMAs, and when this feature will be available for Marketplace Partners in the Confluence Cloud Migration Assistant (CCMA).

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.1.0</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 when the check fails, 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></>

Note: 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.

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

    Sample app

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

    Rate this page: