Rate this page:
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.
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. See also how to build app vendor checks.
For more updates, follow the app migration platform changelog.
When your customers run their migration, they may face run into errors. 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 easily-resolved errors.
As an app vendor/Marketplace Partner, you play a crucial role in predicting the scenarios that can cause errors and block your customers when they try to migrate your app to cloud.
App vendor checks are messages that you can surface in your customer’s instances of the CMA, after running your check for potential issues that can cause failure while migrating your app to cloud.
This is how the new 'App vendor check' screen appears in the CMA.
Apps that haven't implemented the app vendor checks feature are grouped in a section at the top of the page.
App vendor check messages should flag potential errors/warnings to customers, and surface instructions on how customers can fix these warnings before running the migration.
A check has a title and body.
Create an informative title (no more than 60 characters) that summarizes the scenario so your customer can understand it just by reading the title alone. If the check passes, no additional information is shown. If the check comes back with a warning, you can provide more details and steps to resolve the issue.
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.
NEW You can now provide a hyperlink to your app documentation if required. From JCMA v1.9.0 and above, the hyperlink you provide will appear as a clickable link.
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.
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.
Content clarity: Keep content as short and concise as possible, particularly if you're providing step-by-step instructions. See an example below.
|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.
|Read product-related data like pages, sites, issues, and projects.||Read product-related data like pages, sites, issues and projects.|
|First, select 'Preferences' under ‘Settings’.||First select 'Preferences' under 'Settings'.|
Capitalization: Here are a few guidelines on how to capitalize titles and copy:
|Remove undefined custom fields||Remove Undefined Custom Fields|
|Open app preferences.||Open App Preferences.|
Use of 'you' and 'your'
|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
|Remove custom fields in order to migrate.||Custom fields need to be removed in order to migrate.|
Hyperlinks in body
|If you cannot resolve this check with the steps provided above, follow the detailed instructions at https://www.documentation.mycompany.com/steps||Goto link: https://xyz-prod-us-west-2.s3.us-west-2.amazonaws.com/tenant/916cb978-1704-3ee7-a36a-693ca746c77b/66d89977-efea-30f7-b845-1c9a3718900zzz?response-content-disposition=attachment%3B%20filename%3Ddetail.txt&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230411T191624Z&X-Amz-SignedHeaders=host&X-Amz-Expires=00000&X-Amz-Credential=AZAAYZHVO3UWO5VEXJLJ%2F20230411%2Fus-west-x%2Fs3%2Faws4_request&X-Amz-Signature=01aab2f57c9b660e75071e5cea26d4f11cf37f5078f0469564bc26a6e7ec015|
To better organize your content and write good app vendor check message copy, see:
Here's a list of app related checks that Atlassian includes and runs for all apps in every migration plan. You shouldn't need to create checks for the same conditions.
|App assessment is incomplete||Customers will be taken back to the app assessment to record decisions for each of the apps in the assessment. Once the assessment for each app is completed, re-running the check will display a green tick.|
|Some apps marked as 'Needed in cloud' on your server are out of date||Customers will need to update their apps in server to a version that’s compatible with app migration.|
|You have not consented to app data migration||Customers need to consent to app migration on the ‘Agree’ screen.|
|Some 'Needed in cloud' apps are not installed on your cloud site||Customers need to install all the apps that they have chosen as ‘Needed in Cloud’ on their Cloud site. Customers can do this on the ‘Install’ screen.|
|Some apps marked as ‘Needed in cloud’ do not meet the migration success rate criteria||If customers selected apps marked as Stage 1 during assessment phase as ‘Needed in Cloud’ that have unknown or low migration success rates, they will be given the option to remove the apps from the migration, or proceed with migration regardless of low migration success rates.|
|Some apps need a cloud license update NEW||This new pre-migration check is available in Confluence Cloud Migration Assistant (CCMA) version 3.4.3 and higher and in Jira Cloud Migration Assistant (JCMA) version 1.9.0 and higher. |
This check verifies that all apps participating in migration plan have an active cloud app license installed on their cloud site instance. If the license for any of those apps is inactive, customers will be redirected to manage the app license on cloud site. This is a non-blocking check and customers will be able to proceed with the migration if this check fails.
|Some apps are not registered to receive migration notifications NEW||This pre-migration check is available in Confluence Cloud Migration Assistant (CCMA) version 3.4.3 and higher and in Jira Cloud Migration Assistant (JCMA) version 1.9.0 and higher. |
This check verifies all apps participating in migration plan are registered to receive migration notifications. This means the check will pass for the apps that have registered a webhook to receive migration events for a given cloud site. If this check fails, the customer will be directed to the marketplace partner support portal. This is a non-blocking check and customers will be able to proceed with the migration if this check fails.
Rate this page: