App vendor checks

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.

How do app vendor checks help app migration?

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.

Visualising app vendor checks in the Cloud Migration Assistant

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.

Apps with no checks

The apps that have not implemented the App vendor checks feature are grouped in a section at the top of the page.

How to write effective app vendor checks

The purpose of writing app vendor check messages is to:

• flag potential errors/warnings to customers that can fail an app migration before they migrate
• surface specific instructions to customers on how to fix warnings before running the migration

A check has 2 parts:

• Title
• Body

In order to create effective messages, consider the guidelines that follow.

Title

Create an informative title 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.

See a few examples of titles in the table below.

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.

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:

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, refer to the resources listed below:

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

Atlassian created app related checks running by default

Following is list of app related checks that Atlassian includes and runs for all apps in every migration plan. You should not need to invest effort into creating checks for the same conditions.