Checklist storage and storage migration
- Pavel Pavlovsky (Unlicensed)
- Oleksandr Haiun
- Oleksandra Kravets
Starting from version 5.0.0 we introduced a new Checklist data storage for Jira Server and Data Center. 🚀
Contents 👇🏼
Overview
From the very beginning, our add-on provided administrators with an easy way to install and start using Checklists on their Jira instance with minimal configuration.
Initially, we used Jira Issue Property as the main storage for checklist data. The introduction of the "Checklists" and "Smart Checklist Progress" custom fields allowed users to access additional features. For more details, see our documentation → Custom Fields Setup.
However, in response to growing user demand for new features and improvements, we have introduced a new storage system based on the client’s Jira database, along with a unique "Smart Checklist" field of a unique type.
Benefits the new storage brings
Custom Statuses Implementation: Unlock advanced workflow capabilities by implementing custom statuses for your checklists → Custom Statuses
Improved Search Functions: Enhance your search capabilities with advanced JQL search options for checklists → JQL Search Checklists
Checklist View in Search, Jira Dashboard, and Confluence: Easily view checklists across various Jira and Confluence interfaces.
Better Support for Jira Data Center to Jira Cloud Migration: Smoothly transition from Jira Data Center to Jira Cloud with enhanced checklist support and data migration capabilities → Migrate Checklists from Jira Server/ Data Center to Jira Cloud
☝🏼NOTE: With the introduction of the new storage system, the issue property com.railsware.SmartChecklist.checklist is no longer the primary storage for checklists. However, if you have Automation set up to read or write checklists, you can continue to use this property alongside the Checklists custom field.
Migration to the new storage
☝🏼NOTE: Before migrating to version 5.0+ on your Production instance, ensure that it has been thoroughly tested on your Test or Development instance.
For new users (versions 5.0 and higher), no action is required. Upon installation, the new fields are automatically created, and Smart Checklist will begin saving data there immediately.
For existing users (versions older than 5.0), your checklists will migrate to the new storage automatically when you access your Jira issues with checklists and update checklist items. Alternatively, you can initiate a migration process to transfer all your historical checklist data at once. The good news —it’s just a one-click process!
👤 JIRA PERMISSION REQUIRED: Make sure you have JIRA Administrators global permission to access app settings.
Steps
Go to Manage apps in your Jira Administration settings.
Go to Smart Checklist → Settings in the left side bar.
Then, navigate to the Global Settings tab.
In the Migrate to a new checklists storage section, click Start Migration button.
☝🏼NOTE: Run Re-Indexing manually after the migration is complete to enable searching through checklist values. For more details on re-indexing, refer to the Jira documentation.
Re-start migration
Re-start migration will re-synchronize all available checklist storages (custom fields, issue property and Data Base). This is particularly useful for existing customers who want to update their manually configured Checklists and Smart Checklist custom fields to the new fields provided by the add-on. It is also helpful if the automatic storage synchronization has encountered any issues.
Force Existing Checklist Update Option
☝🏼NOTE: Use this option cautiously, as it updates all Jira issues, even those without checklists. These updates may trigger user notifications!
If you need to overwrite existing checklists in the database that have already been migrated, you can use the Force Existing Checklist Update option. This feature is particularly useful in scenarios where you’ve previously upgraded to version 5.0+, reverted to an older version like 4.16 (which uses the old storage), and then updated back to version 5.0+.
By using this option, you ensure that your checklist data is consistent with the latest storage format, even after reverting to older versions.
💡HINT: Migration runs only for projects where Smart Checklist is enabled. You can use this information to speed up the migration process or to test Migration on a single project.