Versions Compared

Old Version 1

changes.mady.by.user Jennifer Choban

Saved on

compared with

New Version 2

changes.mady.by.user Jennifer Choban

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents
maxLevel3
excludeOn this page

...

  • To use Issue Checklists with the API, the Save checklist data to Jira custom fields global setting must be enabled.

  • To update or remove an existing checklist via the API, the Checklist Text custom field must be present on the Edit issue screen. Follow these instructions for adding a custom field to a screen.

  • No configuration are required for reading a checklist, or checklist metadata via the API.

...

Item

Replace with

Example

email@example.com 

The email address provided in your Atlassian ID account

stefan@herocoders.com

<api_token>

A valid API token for your Atlassian ID

J3D4smrVz29cxzsd

https://your-domain.atlassian.net

The URL of your Jira Cloud instance

https://herocoders.atlassian.net

{issueIdOrKey}

The relevant issue key

DEMO-1

"customfield_10034"

The ID of the Checklist Text custom field in your instance. Follow these instructions for getting the custom field ID.

"customfield_10058"

...

Note

You will need to replace the custom field ID with the ID of the Checklist Text fieldin your instance.

Get a Checklist

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

Returns the details of an issue, including the checklist in text format.

cURL example:
Code Block
breakoutModewide
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/api/2/issue/{issueIdOrKey}' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json'

...

Create or Update a Checklist

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

Updates the issue by adding or updating a formatted checklist.

Note

The Checklist Text custom field must be present on the Edit issue screen. Follow instructions here for adding a field to a screen.

...

  1. Retrieve a representation of the issue via GET /rest/api/2/issue/{issueIdOrKey}

  2. Using Checklist Text field id, extract and parse checklist value: representation → fields → customfield_xxxxx (parse items by new line characters)

  3. Modify the parsed checklist as needed. For example, to check an item as complete, put an "x" in the square brackets (so that "* [] summary" becomes "* [x] summary"). 

  4. Upload the modified value back to the issue via PUT /rest/api/2/issue/{issueIdOrKey}

...

Expand
titleExample: Add a Checklist to an Issue (cURL)

  1. Open terminal.

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

    Text

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

    Replace customfield_12345 string with the ID of Checklist Text custom field in your Jira instance. See instructions here for finding custom field ID.

  3. Type following command in the terminal.

    Code Block
    curl -D- -u "jack@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@herocoders.com with the email address provided in your Atlassian ID account. 
    Replace api_token with a valid token generated in your Atlassian ID account (see instructions for generating tokens).
    Replace jiraUrl with URL of your Jira instance.
    Replace DEMO-1 with the appropriate issue key. 

  4. Go to Jira issue page to confirm that:

    1. Checklist has been updated and contains a single checked item "example item".

    2. The Checklist Text field has been updated with the checklist provided in example.json file. This will be visible if the Checklist Text field is on the theView Issue Screen:



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

...