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

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 34 Next »

On 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.


This guide applies to Jira REST API version 2 calls only. While the latest Jira REST API version is 3, it is still in beta and doesn't work with the Issue Checklist. 


This guide applies to Jira Classic projects only. Jira Next-Gen projects don't support global custom fields, which is required for checklist REST API access.

You can access checklist data stored in custom fields even if the Issue Checklist plugin has been uninstalled. 


Prerequisites

  • "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 (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.


Please note that through API you can also read checklist metadata stored in issue entity properties, like the number of items or completeness status.



Authentication

Following guide is based on basic-authentication which means that all calls will impersonate you during the call. Your user needs to have relevant permissions granted ("read issue", "edit issue") in your Jira to manipulate the issue checklist custom field. Also, a valid api_token for your Atlassian ID account is required (see instructions how to generate the token).

Note: in the cURL examples below you will need to replace:

WhatReplace withExample

email@example.com 

an email address provided in your Atlassian ID accountstefan@herocoders.com
<api_token>a valid API token for your Atlassian IDJ3D4smrVz29cxzsd
https://your-domain.atlassian.netthe URL of your Jira Cloud instancehttps://stefan-dev.atlassian.net

{issueIdOrKey}

an issue key that you want to interact withDEMO-1


Available resources (Text format examples)

Get issue checklist

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

Returns the details of an issue, including its checklist.

cURL example:
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):
{
  "expand": "",
  "id": "10002",
  "self": "https://your-domain.atlassian.net/rest/api/2/issue/10002",
  "key": "DEMO-1",
  "fields": {
  (...) // omitted for brevity
    "customfield_10034": "--- Tested on\n* Chrome\n* Safari\n* Firefox\n* Edge\n* [x] IE11",
  }
  (...) // omitted for brevity
}

(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 response format of the checklist is documented in separate page: Issue Checklist Text format.


Create or update issue checklist

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

Updates the issue including its checklist.

cURL example:
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:
{"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:
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:
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):
{
  "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:
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:
{"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:
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:

  • download current representation of the issue via GET /rest/api/2/issue/{issueIdOrKey}
  • knowing Checklist Content YAML (or Checklist Text) field id, extract and parse checklist value: representation → fields → customfield_xxxxx 
    • for Checklist Content YAML field use YAML processing library of your choice
    • for Checklist Text parse items by new line characters
  • modify parsed checklist according to your needs, i.e.:
    • set items checked property to true (Checklist Content YAML)
    • add preceding '[x] ' to each item (Checklist Text)
  • upload modified value back to the issue via PUT /rest/api/2/issue/{issueIdOrKey}

Add checklist to the issue (cURL)

 Click here to expand...
  1. Open terminal.

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

    YAML
    {"fields": {"customfield_12345": "items:\n  - text: example item\n    checked: true\n"}}

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

    Text
    {"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:

    curl -D- -u "jack@gebsun-support.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-support.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. 

  4. 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".



    2. "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:



      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)

 Click here to expand...

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

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

    npm install axios lodash js-yaml

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

    script.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];
	
	console.log('Found checklist:\n', checklistYaml);
	
	let checklist = yaml.safeLoad(checklistYaml);
	
	checklist.items.forEach(function (item) {
		item.checked = true;
	});

	let fields = {};
	fields[_checklistFieldId] = yaml.safeDump(checklist);
	
	console.log('Saving updated checklist:\n' + fields[_checklistFieldId]);
	
	return axios.put(jiraURL + '/rest/api/2/issue/' + issueKey, {fields: fields}, {auth: credentials});
}).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 YAML 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 YAML field.
     

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


  5. Type following command in the terminal:

    node script.js
  6. Go to your JIRA and selected issue page and see the Checklist modified by the script:
     
  • No labels