Rate this page:
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).
The App migration platform provides the ‘App vendor checks’ feature in the Cloud Migration Assistant (CMA) that allows you to run pre-migration checks on your customer’s instance, surface warnings and provide resolution instructions before they run their migration.
The image below provides a sample preview of what the App vendor check feature looks like in the CMA.
When customers run their migration, they may face scenarios where the migration is blocked due to errors that occur while migrating apps. Current research shows that the issues that cause a large percentage of failed app migrations can be detected before the customer runs the migration. Detecting problems early reduces customer frustration, and reduces the chances of them being blocked by errors that can be resolved easily.
As an app vendor / Marketplace Partner, you play a crucial role in predicting the scenarios that can cause errors and block customers when they try to migrate your app to Cloud.
This page provides guidance on writing effective and easy-to-comprehend warning messages and resolution instructions in the CMA, so that the app migration becomes smoother for both you and the customer. Read our docs for technical information on how to build app vendor checks.
App vendor checks are messages that you can surface in the customer’s instances of the CMA, after running your check for potential issues that can cause failure while migrating your app to Cloud. See an example below of what the new 'App vendor check' screen looks like in the CMA.
The purpose of writing app vendor check messages is to:
A check has 2 parts:
The total size limit of a single check (title and body) is 1050 characters. Checks that exceed this limit may get truncated and not display as expected in the CMA user interface.
In order to create effective messages, consider the guidelines that follow.
Create an informative title that summarizes the scenario. For warning messages, summarise the issue in the title so that your customer can understand the problem just by reading the title alone. You can provide details about the issue and the workaround in the body of the check.
See a few examples of titles in the table below.
The limit for a title is 60 characters.
Warning check scenario | Sample title |
---|---|
Check has detected issues with failed project permissions | Project permissions are unavailable for migration |
Check that runs for workflow rule transition fails | Some workflows found to transition incorrectly to invalid status |
Check detects that custom field types have changed in Cloud | Custom field types values have changed in Cloud |
In most cases, this should be a step-by-step instructional guide on how customers can fix the error before proceeding with the migration. Your job is to provide customers with simple and easy to understand instructions to proceed with the migration. Avoid overwhelming customers with technical details unless absolutely necessary.
The body copy is divided into two parts:
A paragraph or sentence preceding the steps. The character limit for a paragraph or the sentence is 180 characters.
The steps to fix warning/error In any error state, it’s best to limit the number of steps to 5 or fewer. The character count for each step is 175 characters.
Content clarity: Keep content as short and concise as possible, particularly if you're providing step-by-step instructions. See an example below.
Good | Avoid |
---|---|
Click 'Open app preferences' below. | First, you need to click ‘Open app preferences’ below. |
American English: Atlassian follows the American English rules of spelling for written content in products. It is recommended you follow the same language rules to maintain consistency of content in the CMA.
Commas:
Good | Avoid |
---|---|
Read product-related data like pages, sites, issues, and projects. | Read product-related data like pages, sites, issues and projects. |
Good | Avoid |
---|---|
First, select 'Preferences' under ‘Settings’. | First select 'Preferences' under 'Settings'. |
Capitalization: Here are a few guideslines on how to capitalize titles and copy:
Good | Avoid |
---|---|
Remove undefined custom fields | Remove Undefined Custom Fields remove undefined custom fields |
Good | Avoid |
---|---|
Open app preferences. | Open App Preferences. |
Use of 'you' and 'your'
Good | Avoid |
---|---|
Remove custom fields in order to migrate. You can edit this after the migration in your Cloud site. | Remove custom fields in order to migrate. This can be edited after the migration in the Cloud site. |
Use active voice over passive voice
Good | Avoid |
---|---|
Remove custom fields in order to migrate. | Custom fields need to be removed in order to migrate. |
To better organize your content and write good app vendor check message copy, refer to the resources listed below:
Rate this page: