Migrating from On-prem to Checklist for Jira Enterprise

There are two options for migrating from Checklist for Jira on-prem to Checklist for Jira | Enterprise (cloud):

• Jira Cloud Migration Assistant (JCMA)  RECOMMEND

• Direct import (if your Jira issues have already been migrated to the new Cloud instance)
  

Due to differences between Jira DC/Server and Jira Cloud, the checklist apps offer similar functionality but may achieve that functionality in different ways. Comparable features are available, but there is not 100% feature parity.

Jira Cloud Migration Assistant (JCMA)

How to Prepare for Migration

In the (Source) Data Center Instance

1. Ensure that you are using Checklist for Jira Server / Data Center version 7.0.6 or later.

2. Install the Jira Cloud Migration Assistant app.

3. Navigate to Jira Settings > Apps > Manage Apps and select Checklist for Jira. Confirm that the version is 7.0.6 or later and that the app key is com.okapya.jira.checklist.

In the (Destination) Cloud Instance

1. Install the Checklist for Jira Enterprise app.

2. Navigate to Jira Settings > Apps > Manage Apps and select Checklist for Jira Enterprise. Confirm that the version is 2.0.0a or later and the app key is com.okapya.jira.checklist.

3. Verify that the projects you will be migrating do not already exist in the Cloud instance.

Executing the Migration

1. In the source instance, navigate to System and select Migrate to cloud from the left nav bar.
   

   

2. Enter your Administrator password when prompted.
   

   

3. On the Connect to Cloud page, use the dropdown to select the destination cloud instance. If the dropdown is empty or the target instance is not shown, click Choose cloud site. You will be given the option to attach an existing cloud instance or create a new cloud instance.
   

   

4. Click Continue.

5. The Migration Assistant home page will open. Scroll down to Assess your apps and click Begin assessing.
   

   

6. Verify that the projects being migrated include at lease one Checklist Definition. Then, on the list of apps, find Checklist for Jira. In the status dropdown, select Needed in cloud.
   

If you are migrating in batches and none of the projects in a given batch include Checklist Definitions that should be imported in total to the Cloud, please select Not needed in cloud in the status dropdown.

Lack of Checklist Definitions will means the on-prem checklist app will not generate any files to be sent to the JCMA. This can cause the import to get stuck.

7. Make the appropriate selection for any other apps. Click Done.

8. Scroll down to Prepare your apps and click Continue preparing.
   

   

9. Click Confirm to accept the privacy policy of the cloud app. Click Done.
   

   

10. Follow the JCMA instructions for migrating users and email domains.

11. Scroll to Migrate your data and click Create a migration.
    

    

12. You may be shown the screen below; this is totally optional. To avoid it in the future, tick the “Don’t show me this screen again” box.
    

    

13. Name the migration.
    

    

14. Select the migration stage (testing or production).
    

    

15. Select the destination cloud instance.
    

    

16. Select Choose what to migrate.
    

    

     

17. Under Projects, click Select.
    

    

18. Use the checkboxes to select the project(s) you want to migrate. The app will check that the projects do not already exist on the cloud site.
    

    

     

19. Make the appropriate selections for migrating Boards, User & Groups, JSM customers, etc. Click Run pre-migration checks.
    

    

20. Click Review migration.
    

    

21. After confirming that the migration will include the correct data, click Run.
    

    

Note that in the Cloud App, global and local items are separated into two different checklists: an issue that had a checklist with both global and local items in the on-prem version will have two different checklists (global and local) in the Cloud version.

Post-migration Configurations

Once the migration is complete:

1. Navigate to Jira Settings > Apps > Manage Apps and review the following:

   1. Global Settings – Ensure your global settings are properly configured. (If checklists are not shown on the main issue panel, enable the Show Checklist Always setting.)

   2. Global Checklists – Review your global checklists. You may want to adjust the Checklists context.

   3. Permissions – Review checklist permissions.

   4. Statuses – Verify that any custom statuses migrated correctly.

2. Checklist for Jira | Enterprise creates several custom fields. However, since Jira Cloud does not support a checklist custom field type, your previous checklist custom fields will not have been migrated. Therefore it is recommended that you review places other than the issue panel where you were using these fields, and replace them with the new custom fields created by the cloud app:

   1. Automation rules

   2. Board cards

   3. Create and transitions screens

   4. Workflow conditions, post functions, rules and validators

3. Default local checklist items are not supported in cloud. However, you can accomplish the same thing using a default template.

4. Checklist item assignees – Jira Cloud creates different user IDs than Jira Server/Data Center. Currently, after verifying that all of your users were successfully migrated to cloud, you will need to re-assign checklist items.

We’ve worked hard to make your migration easy, but if you run into any trouble your Enterprise subscription comes with priority support including discovery meetings, demo calls and guided support.

An error can occur if you cancel a JCMA import in progress. Please see this page before canceling an import.

Direct Import

How to Prepare for Migration

Checklist for Jira Server/Data Center

1. Verify the scope of each Checklist Custom Field Context. Ensure that the Context is only marked as “All Projects” for checklists that you truly want to have on all of your Jira issues. (When using checklists on-prem you may have set the Context to “All Projects,” but omitted the Checklist Custom field on screens in certain projects. When migrating to Cloud, this can result in useless data being stored in the database, or unwanted checklists appearing on Jira issues.)

2. Some items will need to be verified/reconfigured post-migration. Therefore, you may want to prepare an inventory of:

   1. Global items - Once migration is complete, you may want to create Checklist templates that include these items.

   2. Checklist permissions

   3. Checklist conditions

   4. Checklist validators

   5. Checklist post functions

   6. Assigned checklist items - depending on the migration path you used, user IDs may or may not have been mapped from on-prem to cloud. Therefore, once users are set up in Cloud you will need to re-assign checklist items.

3. Follow the instructions on this page to create the export file.

Checklist for Jira Enterprise

Note that we recommend preparing your data first and waiting until you are ready to migrate before starting a trial of Checklist for Jira Enterprise, as the trial is for a limited time.

1. Install Checklist for Jira Enterprise.

Executing the Migration

Note that Jira will not be impacted by the migration. However, there will be some downtime during which you will not be able to access your checklist data.

This import process will load all checklist data files created by the Checklist for Jira Export feature and copy them to the Checklist for Jira | Enterprise app.

The importer for Checklist for Jira on-prem is available in Checklist for Jira | Enterprise.

Checklist for Jira | Enterprise works differently than Checklist for Jira Server/DC. Learn more here.

This import process will load checklist data files created by the Checklist for Jira on-prem export feature and copy them to Checklist for Jira | Enterprise.

1. Use the Checklist for Jira Export feature to generate the files that will be loaded into Issue Checklist.

2. Navigate to Jira Settings > Apps and select Import under the Checklist for Jira | Enterprise heading.

3. Select the Checklist for Jira Server/DC tab.
   

   

4. Locate the files generated during the Checklist for Jira Server export process and drag them to the upload area. Alternatively, you can also click the area and select the files from your computer.
   

   

5. When all the files generated during the Export process are in the list, click Upload files.

6. Determine if you want to overwrite or append to previously imported checklists. The import process is designed to allow for incremental imports, and does not prevent duplicates. If you perform an import without enabling Clear previously imported data, any previously imported items may appear as duplicates in subsequent imports. Use the Clear previously imported data toggle to indicate if you want to:

   • Clear previously imported data (Toggle enabled)
     Replace any previously imported data from Checklist for Jira on-prem with the items being imported from the currently uploaded files. It is recommended that you enable the toggle if you attempt to perform an import more than once. Data to be replaced includes:

     • Global Checklists

     • Checklist items in Jira issues (global and local)

     • Checklist item statuses
       
       Please see the troubleshooting imports page for more information.

   • Append imported checklist items to already existing checklists (Toggle disabled)
     Imported checklist items will be appended to the existing checklist(s) on the issue. If you will import the same checklist Checklist Field but for other project(s), duplicate Global Checklist will appear. It’s recommended to import a checklist Custom Field configuration for all projects at once.
     
     We recommend waiting to work on checklists until the import is finalized. In case of doubts, please contact our support.

     

7. Once the files are uploaded, and you’ve confirmed that the Clear previously imported data toggle is in the correct position, click Start import. The import will be scheduled and a gray panel will show the import status. Click on the Refresh icon to update the status.
   

   

   
   
   

8. When the import is complete, the status panel will turn green and will display the number of checklist items and issues impacted.
   

   

Note that in the Cloud App, global and local items are separated into two different checklists: an issue that had a checklist with both global and local items in the on-prem version will have two different checklists (global and local) in the Cloud version.

Post-migration Configurations

Once the migration is complete:

1. Navigate to Jira Settings > Apps > Manage Apps and review the following:

   1. Global Settings – Ensure your global settings are properly configured. (If checklists are not shown on the main issue panel, enable the Show Checklist Always setting.)

   2. Global Checklists – Review your global checklists and their contexts. If the context did not migrate, please contact support.

   3. Permissions – Review checklist permissions.

   4. Statuses – Verify that any custom statuses migrated correctly.

2. Checklist-type custom fields used in your on-prem instance are not supported in Jira cloud. If you were using these fields in places other than the issue panel (automation rules, board cards, create and transition screens, workflow behaviors, etc.), you will need to replace those custom fields with the custom fields created by Checklist for Jira Enterprise.

3. Default local checklist items are not supported in cloud. However, you can accomplish the same thing using a default template.

4. Checklist item assignees – After verifying that all of your users were successfully migrated to cloud, you may need to re-assign checklist items on local checklists. Mentions/assignees are not supported in Global Checklists.

We’ve worked hard to make your migration easy, but if you run into any trouble your Enterprise subscription comes with priority support including discovery meetings, demo calls and guided support.