We have a new documentation site. Please go here to see the latest.

Migration guide for custom fields

Owned by Jack (Hunter) Jaroczynski
Last updated: Dec 10, 2018

New custom fields

Issue Checklist v1.8.20 introduced new custom fields integration. The fields are now created and managed automatically by Issue Checklist app.

The previous custom fields, created manually by Jira administrators, are now obsolete and no longer synchronized with the Checklist. These fields can be safely removed.

The above means that JQL queries, workflow validators and scripts, that use old custom fields, need to be updated and start using the new fields.

Why new custom fields?

New custom fields are created and managed automatically by Issue Checklist app. There is no more need for confusing and difficult configuration, i.e. creating the fields and adding them to the proper screen.

New custom fields implementation fixes several problems observed with the old custom fields. 

Do I need to migrate? 

If you see the warning icon on the Jira issue page, as presented on the screenshot below, then migration might be required (the warning icon is displayed if manually created Checklist custom fields are detected in your Jira).

If you don't see the warning icon, then you are OK to skip this migration guide. You might only want to read about profits of using custom fields.

Migration required warning

To remove the warning icon, please ask your Jira administrator to check if migration is required and delete the obsolete custom fields as described below.

Check and migrate old custom fields

The most common custom field usage is blocking issue transition, reading/writing Issue Checklist data through Jira REST API and populating custom fields and checklist through Recurring Tasks app. 

Read more below how to migrate both these use cases.

Blocking issue transition

If you use blocking issue transition for not completed checklist, then:

  1. Please follow our guide to add new validator.
  2. Remove the old validator. 

Recurring Tasks app

If you populate checklist to the issues created by Recurring Tasks app then:

  • go to the configuration page of Recurring Tasks,
  • find and edit the recurring task definition,
  • move checklist YAML data from the Checklist Content field to the Checklist Content YAML field. 
  • contact our support to confirm the migration is successful 

You might want to consult our documentation related to Recurring Tasks app for more details. 

Reading/writing Issue Checklist data through Jira REST API

Jira REST API can be used from the terminal/shell command line, scripts, programs or other external tools.

If your team has built that kind of integration with Issue Checklist then please replace the old custom fields with the new fields in the source code of the script/program using the below tips:

  • If your external integration uses Checklist custom fields by name then:

    • please replace Checklist Content field name with Checklist Content YAML new name.
    • delete old custom fields in Jira as described in the paragraph below

  • If your external integration uses Checklist custom fields by id then:

    • please replace old field ids with new fields ids 

       show how to find custom field ID in Jira

      Using URL

      1. Navigate to Administration >> Issues >> Custom Fields.
      2. Click the cog and hover over Configure or Screens option.
      3. Observe the URL at the bottom left of the browser window. Example:

        (info) The id for this custom field is 10006
    • delete old custom fields in Jira as described in the paragraph below

Please note, that only one of the new custom fields uses new name, i.e. Checklist Content YAML field (the old one is Checklist Content). 

Checklist Completed new custom field uses the same name as the old one. Checklist Progress custom field did not change. 

Delete old custom fields

New custom fields contain all the checklist data. The old custom fields data is no longer necessary and there is no need to copy the data from the old custom fields to the new custom fields.

New custom fields are easy to distinguish from the old ones by their description. New custom fields description starts with "Do not delete" text:

 

Please go to "Jira Settings > Issues > Custom fields" and delete following fields if present:

  • "Checklist Content" custom field.
  • "Checklist Completed" custom field (only if its description does not start with "Do not delete")