Versions Compared

Old Version 35

changes.mady.by.user Jack Hunter

Saved on

compared with

New Version 36

changes.mady.by.user Maciej Opala

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

On this page

Table of Contents
maxLevel3
excludeOn this page

Introduction

...

On this page

Table of Contents
maxLevel3
excludeOn this page

Introduction

You can use Jira REST API to interact with the Issue Checklist programmatically. This page documents the REST resources available to use, including example requests and responses. Use this API to build script interactions with your checklist, or develop any other type of integration.

...

  • "Save checklist data to Jira custom fields" option must be enabled in Global Settings.
  • For updating or removing existing checklist a custom field Checklist Content YAML or Checklist Text custom field (depending on the format you want to use) must be present on the Edit issue screen. You can configure that in your Jira project settings with these instructions: how to add a custom field to a screen.
    For only reading the checklist, there is no such requirement.

...

Available resources (Text format examples)

Get issue checklist

GET /rest/api/2/issue/{issueIdOrKey} (reference)

Returns the details of an issue, including its checklist.

...

Create or update issue checklist

PUT /rest/api/2/issue/{issueIdOrKey} (reference)

Updates the issue including its checklist.

cURL example:
Code Block
curl --request PUT \
  --url 'https://your-domain.atlassian.net/rest/api/2/issue/{issueIdOrKey}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "fields": {
      "customfield_10034": "--- Tested on\n* [x] Chrome\n* Safari\n* Firefox\n* Edge\n* [x] IE11\n--- Mobile\n* Android\n* iPhone"
    }
  }'

(warning) Note the "customfield_10034" string can be different than in the example above. It should be the ID of "Checklist Text" custom field found in your Jira instance (see instructions how to find custom field ID).

The request format of the checklist is documented in separate page: Issue Checklist Text format.

Response errors:
Code Block
{"errorMessages":[],"errors":{"customfield_10034":"Field 'customfield_10034' cannot be set. It is not on the appropriate screen, or unknown."}}

The Checklist Text custom field must be present on the Edit issue screen. You can configure that in your Jira project settings with these instructions: how to add a custom field to a screen.

Remove issue checklist

Same as "Create or update issue checklist" above, but you need to pass null or empty value for the custom field:

cURL example:
Code Block
curl --request PUT \
  --url 'https://your-domain.atlassian.net/rest/api/2/issue/{issueIdOrKey}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "fields": {
      "customfield_10034": null
    }
  }'

Available resources (YAML format examples)  

Get issue checklist

GET /rest/api/2/issue/{issueIdOrKey} (reference)

Returns the details of an issue, including its checklist.

cURL example:
Code Block
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/api/2/issue/{issueIdOrKey}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'
Example response (application/json):
Code Block
{
  "expand": "",
  "id": "10002",
  "self": "https://your-domain.atlassian.net/rest/api/2/issue/10002",
  "key": "DEMO-1",
  "fields": {
  (...) // omitted for brevity
    "customfield_10033": "items:\n  - text: '---Tested on'\n    checked: false\n  - text: Chrome\n    checked: true\n  - text: Safari\n    checked: false\n  - text: Firefox\n    checked: false\n  - text: Edge\n    checked: false\n  - text: IE11\n    checked: false\n",
  }
  (...) // omitted for brevity
}

(warning) Note the "customfield_10033" string can be different than in the example above. It should be the ID of "Checklist Text" custom field found in your Jira instance (see instructions how to find custom field ID).

The response format of the checklist is documented in separate page: Checklist Content YAML.

Create or update issue checklist

PUT /rest/api/2/issue/{issueIdOrKey} (reference)

Updates the issue including its checklist.

cURL example:
Code Block
curl --request PUT \
  --url 'https://your-domain.atlassian.net/rest/api/2/issue/{issueIdOrKey}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "fields": {
      "customfield_10033": "items:\n  - text: ---Tested on\n    checked: false\n  - text: Chrome\n    checked: true\n  - text: Safari\n    checked: false\n  - text: Firefox\n    checked: false\n  - text: Edge\n    checked: false\n  - text: IE11\n    checked: true\n  - text: ---Mobile\n    checked: false\n  - text: Android\n    checked: false\n  - text: iPhone\n    checked: false\n"
    }
  }'

(warning) Note the "customfield_10033" string can be different than in the example above. It should be the ID of "Checklist Text" custom field found in your Jira instance (see instructions how to find custom field ID).

The request format of the checklist is documented in separate page: Checklist Content YAML.

Response errors:
Code Block
{"errorMessages":[],"errors":{"customfield_10033":"Field 'customfield_10033' cannot be set. It is not on the appropriate screen, or unknown."}}

The Checklist Content YAML custom field must be present on the Edit issue screen. You can configure that in your Jira project settings with these instructions: how to add a custom field to a screen.

Remove issue checklist

Same as "Create or update issue checklist" above, but you need to pass null or empty value for the custom field:

cURL example:
Code Block
curl --request PUT \
  --url 'https://your-domain.atlassian.net/rest/api/2/issue/{issueIdOrKey}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "fields": {
      "customfield_10033": null
    }
  }'

Examples

General read-modify-update scenario

One of the common scenarios is to programmatically retrieve checklist from the Jira issue, modify its items (depending on some business logic), and pass the checklist back to Jira issue with the items updated. We won't provide a working solution in your favorite technology, but the general gist is:

...

  • for Checklist Content YAML field use YAML processing library of your choice
  • for Checklist Text parse items by new line characters

...

  • set items checked property to true (Checklist Content YAML)
  • add preceding '[x] ' to each item (Checklist Text)

...

cURL example:
Code Block
curl --request PUT \
  --url 'https://your-domain.atlassian.net/rest/api/2/issue/{issueIdOrKey}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "fields": {
      "customfield_10034": "--- Tested on\n* [x] Chrome\n* Safari\n* Firefox\n* Edge\n* [x] IE11\n--- Mobile\n* Android\n* iPhone"
    }
  }'

(warning) Note the "customfield_10034" string can be different than in the example above. It should be the ID of "Checklist Text" custom field found in your Jira instance (see instructions how to find custom field ID).

The request format of the checklist is documented in separate page: Issue Checklist Text format.

Response errors:
Code Block
{"errorMessages":[],"errors":{"customfield_10034":"Field 'customfield_10034' cannot be set. It is not on the appropriate screen, or unknown."}}

The Checklist Text custom field must be present on the Edit issue screen. You can configure that in your Jira project settings with these instructions: how to add a custom field to a screen.


...

Remove issue checklist

Same as "Create or update issue checklist" above, but you need to pass null or empty value for the custom field:

cURL example:
Code Block
curl --request PUT \
  --url 'https://your-domain.atlassian.net/rest/api/2/issue/{issueIdOrKey}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "fields": {
      "customfield_10034": null
    }
  }'


Examples

General read-modify-update scenario

One of the common scenarios is to programmatically retrieve checklist from the Jira issue, modify its items (depending on some business logic), and pass the checklist back to Jira issue with the items updated. We won't provide a working solution in your favorite technology, but the general gist is:

  • download current representation of the issue via GET /rest/api/2/issue/{issueIdOrKey}

Add checklist to the issue (cURL)

...

Save the exact content of the below snippet to a local file, e.g. example.json (choose one of the snippets: YAML or Text):

Code Block
titleYAML
{"fields": {"customfield_12345": "items:\n  - text: example item\n    checked: true\n"}}

...

  • knowing Checklist Text field id, extract and parse checklist value: representation → fields → customfield_xxxxx (parse items by new line characters)
  • modify parsed checklist according to your needs, for example to check item put "x" in its square brackets (so that "* [] summary" becomes "* [x] summary") 
  • upload modified value back to the issue via PUT /rest/api/2/issue/{issueIdOrKey}

Add checklist to the issue (cURL)

Expand
  1. Open terminal.

  2. Save the exact content of the below snippet to a local file, e.g. example.json:

    Code Block
    titleText
    {"fields": {"customfield_12345": "[x] example item"}}

    Replace customfield_12345 string with the ID of "Checklist Text" custom field in your Jira instance (see instructions how to find custom field ID).

  3. Type following command in the terminal:

    Code Block
    curl -D- -u "jack@gebsun-supportjack@herocoders.com:api_token" --request PUT --header "Content-Type: application/json" --url 'https://jiraUrl.atlassian.net/rest/api/2/issue/DEMO-1' --data-binary @example.json

    Replace jack@gebsun-supportjack@herocoders.com with an email address provided in your Atlassian ID account. 
    Replace api_token with a valid token generated in Atlassian ID account (see instructions how to generate token).
    Replace jiraUrl with URL of your Jira.
    Replace DEMO-1 with an issue key that you want to update. 

    Go to Jira issue page (in our case https://jiraUrl.atlassian.net/browse/DEMO-1) and see that:
    Checklist has been updated automatically and it contains single checked item "example item".
    Image Removed
    "Checklist Content YAML" (or "Checklist Text") field has been updated with the YAML (or Text) provided in example.json file. You can see it only if Checklist Content YAML (or Checklist Text) field is visible on the View Issue Screen:
    Image Removed
    You can also see that the other checklist custom fields (Checklist Progress and Checklist Completed) has been updated accordingly.

Check all checklist items for a given issue (Node.js)

const axios = require('axios'); const yaml = require('js-yaml'); const _ = require('lodash'); const issueKey = 'DEMO-2'; const jiraURL = 'https://your-jira-url.atlassian.net'; const credentials = {username: 'username', password: 'apiToken'}; const checklistFieldName = 'Checklist Content YAML'; let _checklistFieldId; console.log('Looking for Checklist Content YAML field ID...'); axios.get(jiraURL + '/rest/api/2/issue/' + issueKey + '/editmeta', {auth: credentials}).then(function (response) { let checklistField = _.find(response.data.fields, function (field) { return _.isMatch(field, {name: checklistFieldName}) && _.find(field.operations, function (operation) { return operation === 'set'; }); }); return checklistField ? 'customfield_' + checklistField.schema.customId : null; }).then(function (checklistFieldId) { if (checklistFieldId) { console.log('Found checklist field ID:', checklistFieldId); _checklistFieldId = checklistFieldId; return axios.get(jiraURL + '/rest/api/2/issue/' + issueKey, {auth: credentials}); } else { throw new Error('Checklist field ID not found'); } }).then(function (jiraIssueResponse) { // todo check jiraIssueResponse for errors like incorrect credentials, etc. const checklistYaml = jiraIssueResponse.data.fields[_checklistFieldId];

. 

  • Go to Jira issue page (in our case https://jiraUrl.atlassian.net/browse/DEMO-1) and see that:
    1. Checklist has been updated automatically and it contains single checked item "example item".

      Image Added

    2. "Checklist Text" field has been updated with the checklist provided in example.json file. You can see it only if Checklist Text field is visible on the View Issue Screen:

      Image Added

      You can also see that the other checklist custom fields (Checklist Progress and Checklist Completed) has been updated accordingly.
    • Expand

    1. Install Node.js if you haven't already

    2. Install required Node.js modules with following command:

      Code Block
      npm install axios lodash js-yaml

      Save the content of script.js file provided below to your local filesystem:

    Code Block
    languagejs
    themeEclipse
    titlescript.js

    Check all checklist items for a given issue (Node.js)

    Expand

    1. Install Node.js if you haven't already

    2. Install required Node.js modules with following command:

      Code Block
      npm install axios lodash


    3. Save the content of script.js file provided below to your local filesystem:

      Code Block
      languagejs
      themeEclipse
      titlescript.js
      const axios = require('axios');
const _ = require('lodash');

const issueKey = 'DEMO-2';
const jiraURL = 'https://your-jira-url.atlassian.net';
const credentials = { username: 'username', password: 'apiToken' };
const checklistFieldName = 'Checklist Text';

async function updateChecklist() {
	console.log(`Looking for ${checklistFieldName} field ID`);

	const metaResponse = await axios.get(`${jiraURL}/rest/api/2/issue/${issueKey}/editmeta`, { auth: credentials });
	const checklistField = _.find(metaResponse.data.fields, (field) => {
		return _.isMatch(field, { name: checklistFieldName }) && _.find(field.operations, (operation) => {
			return operation === 'set';
		});
	});

	if (!checklistField) {
		throw new Error('Checklist field not found');
	}

	const checklistFieldId = `customfield_${checklistField.schema.customId}`;
	console.log(`Found checklist field ID: ${checklistFieldId}`);

	const issueResponse = await axios.get(`${jiraURL}/rest/api/2/issue/${issueKey}`, { auth: credentials });
	const checklistText = issueResponse.data.fields[checklistFieldId];

	console.log('Found checklist:\n', checklistYaml);
	
	let checklist = yaml.safeLoad(checklistYamlconsole.log(checklistText);

	
	checklist.items.forEach(function (item) {
		item.checked = true;
	});

	let fields = {};
	fields[_checklistFieldId] = yaml.safeDump(checklist);
	// replace "x" with "done" if you use checklist item statuses
	const updatedChecklistText = checklistText.replace(/^\*\s+\[.*]/gm, '* [x]');

	console.log('Saving updated checklist:\n' + fields[_checklistFieldId]);
	
	return');
	console.log(updatedChecklistText);

	const fieldsToUpdate = {
		[checklistFieldId]: updatedChecklistText,
	};

	await axios.put(jiraURL + '`${jiraURL}/rest/api/2/issue/' + issueKey${issueKey}`, { fields: fieldsToUpdate fields}, { auth: credentials });
}

updateChecklist().then(function () => {
	console.log('Checklist updated successfully');
}).catch(function (error) => {
	console.error('Failed: ', error instanceof Error ? error.stack : JSON.stringify(error));
});

      The scripts reads Checklist Content YAMLText value from your issue, transforms it to JSON format with the help of js-yaml library, checks every item , transforms data back to YAML and performs PUT request to JIRA to change value of the Checklist Content YAMLText field.
       

    4. Edit script.js file and change issueKey, jiraUrl and credentials variables according to your setup. 


    5. Type following command in the terminal:

      Code Block
      node script.js


    6. Go to your JIRA and selected issue page and see the Checklist modified by the script:
      Image Removed.