How app vendor checks work

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 set up app vendor checks.

Why are the checks important?

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.

How do the checks appear in the Cloud Migration Assistant?

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 with no checks

Apps that haven't implemented the app vendor checks feature are grouped in a section at the top of the page.

How to write effective checks

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.

Title

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.

Body

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.

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:

1. A paragraph or sentence preceding the steps. The character limit for a paragraph or the sentence is 180 characters.

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

Best practices for writing body content

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

  • In lists of three or more things, include the comma before words like 'and' or 'or'. See an example below.

  Good	Avoid
  Read product-related data like pages, sites, issues, and projects.	Read product-related data like pages, sites, issues and projects.

  • Use a comma after an introductory phrases like 'For example' or 'First'. See an example below.

  Good	Avoid
  First, select 'Preferences' under ‘Settings’.	First select 'Preferences' under 'Settings'.

• Capitalization: Here are a few guidelines on how to capitalize titles and copy:

  • Always use sentence case for text, headings, and page titles. Capitalize the first letter of the first word, as well as any proper nouns or names. See an example below.

  Good	Avoid
  Remove undefined custom fields	Remove Undefined Custom Fields

  • Capitalize the first letter of text on buttons. The remaining text can remain in sentence case. See an example below.

  Good	Avoid
  Open app preferences.	Open App Preferences.

• Use of 'you' and 'your'

  • Instead of writing about customers in general, write to your reader directly as if you are speaking to them. Refer to the reader as 'you' and tell them what to do directly. See an example below.

  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

  • Active voice makes your writing easy to understand, particularly if you're writing instructions or a step-by-step guide for customers. This means that the subject (customers) performs the action (the verb). Sentences written in active voice also ensure brevity of sentences, making your writing easier to read. See an example below.

  Good	Avoid
  Remove custom fields in order to migrate.	Custom fields need to be removed in order to migrate.

• Hyperlinks in body

  • Fully qualified https:// urls in the body will be automatically turned into hyperlinks. However, we recommend that you include hyperlinks only if necessary and instead provide detailed step-by-step instructions in the body itself. Hyperlinks count towards the total character limit and should be kept short for readability.

  Good

  Avoid

  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

More resources

To better organize your content and write good app vendor check message copy, see:

• General writing guidelines: https://atlassian.design/content/writing-guidelines/
• Guidelines to writing warning messages: https://atlassian.design/content/writing-guidelines/writing-a-warning-message

Default Atlassian checks

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.