Upgrading from V4 to V5

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

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.

To determine whether a global item is missing, the name (complete Markdown text and description) and rank of the item are compared between the backup and instance.

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.

Warning example

MISSING GLOBAL ITEM - No global item was found for custom field 'CF_NAME' in context 'CF_NAME Default Context' with name 'Item Name' at rank '1'. A new global item will be created from the backup.

The rank starts at 1, which indicates the order in which the global items appear.

Be careful of false positives caused by item ordering. If a global item is missing, the ranks of all the subsequent global items will shift ahead by one. Because their ranks will no longer be the same in both the backup and instance, the system will no longer see them as matches.

For example: In the backup, A=1, B=2, and C=3. In the instance, item A is missing, so B=1 and C=2. As a result, B and C are no longer considered to be matches.

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:

CODE

[
  {
    "id": 10001,
    "option": true,
    "name": "Global Item",
    "checked": true
  },
  {
    "id": 1,
    "name": "Local item",
    "checked": true
  }
]

New structure:

CODE

[
  {
    "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.