Upgrading from V4 to V5
- Maxime Lefebvre
- Pascal Perreault [Okapya]
The Checklist app has undergone some major enhancements in V5. Although you will not require any manual assistance to upgrade, you should be aware of these fundamental changes:
Good practices
Test the upgrade in a staging environment (copy of production)
Back up the production database before upgrading
On this page:
Global items
Global items were previously configured in three different sections of the configuration page: Options, Default Value and Discretionary Options. These are now grouped into a single section called Global Items.
For more information, see Editing global items.
Migration from options to global items
In V5, the way that global items (previously known as options) are stored in the database has changed. Upgrading to V5 will automatically migrate all options to the new, more flexible structure.
To make it possible to revert to a previous version, the previous options will be kept in the database. If you roll back to a previous version, the Checklist app will once again use the options that you had before you upgraded.
Support for HTML markup
Administrators could previously inject HTML (and JavaScript) inside an option name. To prevent security risks, HTML markup is no longer supported.
The new features in V5 should be useful for replacing your custom HTML, as we now support Markdown (see Using special formatting and Adding descriptions to items or headers).
New features
The following new features have been introduced in V5.
Mandatory items
The Emphasize Mandatory parameter has been replaced with the Mandatory Items setting. Whereas Emphasize Mandatory only showed an asterisk * next to a mandatory item, the Mandatory Items setting toggles the mandatory feature on and off completely.
For more information, see Making mandatory items optional.
The Mandatory Items feature is turned on by default. If you do not want this feature, you will need to turn it off after upgrading to V5 (see Editing parameters).
Section Headings
A new Section Headings feature has been introduced to allow you to create headers within a checklist.
For more information, see Creating and manipulating headers.
The Section Headings feature is turned on by default. If you do not want this feature, you will need to turn it off after upgrading to V5 (see Editing parameters).
Project imports
Previously, you had to create the missing options exactly as they were in the backup before importing a project. With the new global items structure, missing global items are created automatically to match the backed-up project.
For each missing global item, a warning will appear in the Import Validation step of the project import, informing the user that they will be created.
REST API
With the changes to global items, the REST API structure has also changed. Any scripts that manipulate checklists using the REST API will have to be updated.
Previous structure:
[
{
"id": 10001,
"option": true,
"name": "Global Item",
"checked": true
},
{
"id": 1,
"name": "Local item",
"checked": true
}
]New structure:
[
{
"id": 1,
"globalItemId": 10001,
"name": "Global Item",
"checked": true
},
{
"id": 2,
"name": "Local item",
"checked": true
}
]In the new structure, global items are no longer defined by the combination of the option and id properties. They are now identified by the new globalItemId property.
The id property still indicates the unique identifier of a checklist item, but is no longer equivalent to the global item ID.
Scripting
The changes that impact scripting are as follows.
Checklist item class
If you have scripts that manipulate checklist items, you may need to migrate some methods to new ones. You can see which methods are now deprecated in Enhancing checklists using Groovy scripts.
Options table
If you have scripts that modify Jira’s options table for a checklist field, they will no longer work. If you ever need to modify global items through scripting, please contact us.
Re-upgrading after a rollback
Global items are only migrated once. If you upgrade to V5, roll back, and then want to upgrade to V5 again, the global items will not be migrated again. This means that any changes that were made to global items after the rollback will not be migrated when you re-upgrade.
If this situation applies to you, please contact us before you upgrade to V5 again. A technical workaround exists, and we would be happy to help you through it.
Downgrading to V4
If you ever need to downgrade to V4, see Downgrading from V5 to V4.
Data support
We no longer support the data format that was stored using V2 of our app. V3 and V4 converted the data to the newer format, so this should not cause any problems.