Table of contents
Introduction:
Our plugin allows you to change it's data via Atlassian API. We use the properties of the issue so you can get, update, delete or create data outside of the plugin UI.
You can preview the data by making a GET request to: https://{ site-url }.atlassian.net/rest/api/2/issue/{ issue.id }/properties/sd-checklists
PUT requests are also made to the same endpoint.
If your project permission is not set to "anyone" you will need an API Token. You can generate it here: https://id.atlassian.com/manage/api-tokens
After acquiring it you will be able to use the API as long as your account have sufficient permissions.
Below you can find examples using curl and postman, but first let's check the checklist data structure.
Data structure:
We store an array of checklists for every issue separately. Each checklist have an id, name and an array of items.
You should always set version to 1.0.0. It is here to help us detect the version of checklist our client is using.
Field responsibility:
- version - it allows us to detect what version of the checklist you are using. Leave it at 1.0.0.
- checklists - array of checklists in issue:
- id - id of checklist
- name - name of checklist
- items - tasks in checklist:
- name - name of the task
- required - currently not in use
- completed - Boolean if the task was completed or not
- status - one of the statuses (check settings to add more, edit, delete)
- user - latest user who edited the item
- date - latest time the item was edited
JSON Schema:
{
"definitions": {},
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://example.com/root.json",
"type": "object",
"title": "The Root Schema",
"properties": {
"version": {
"type": "string",
"title": "Version",
"description": "Version of the checklist. Currently at 1.0.0. This value should be always used.",
"default": "",
"examples": [
"1.0.0"
]
},
"checklists": {
"type": "array",
"title": "Checklists",
"description": "Array of checklists in the issue.",
"default": null,
"items": {
"type": "object",
"title": "Checklist",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"title": "The Name Schema",
"default": "",
"examples": [
"Example to do"
]
},
"items": {
"type": "array",
"title": "Items",
"description": "Tasks in the checklist",
"default": null,
"items": {
"type": "object",
"title": "Items",
"description": "Task in the checklist",
"default": null,
"required": [
"name",
"required",
"completed",
"status",
"user",
"date"
],
"properties": {
"name": {
"type": "string",
"title": "The Name Schema",
"default": "",
"examples": [
"<p>task 1</p>"
]
},
"required": {
"type": "boolean",
"title": "Required",
"description": "currently not in use",
"default": false,
"examples": [
true
]
},
"completed": {
"type": "boolean",
"title": "Completed",
"description": "Check if the task was completed or not",
"default": false,
"examples": [
true
]
},
"status": {
"type": "integer",
"title": "Status",
"description": "Indicate one of the statuses",
"default": 0,
"examples": [
0
]
},
"user": {
"type": "string",
"title": "User",
"description": "Id of latest user who edited the item",
"default": "",
"examples": [
""
]
},
"date": {
"type": "string",
"title": "date",
"description": "Time of the latest update",
"default": "",
"examples": [
"2019-08-13T13:18:24.046Z"
]
}
}
}
}
}
}
}
}
}
JSON Data:
{
"version":"1.0.0",
"checklists":[
{
"id":0,
"name":"Example to do",
"items":[
{
"name":"<p>task 1</p>",
"required":true,
"completed":true,
"status":0,
"user":"{ user id }",
"date":"2019-08-13T13:18:24.046Z"
}
]
}
]
}
Endpoints:
Issue screen:
https://{ site-url }.atlassian.net/rest/api/2/issue/{ issue.id }/properties/sd-checklists - read/update/delete the checklist
Settings screen:
https://{ site-url }.atlassian.net/rest/api/2/project/{ project.id }/properties/soldevelo-checklists-settings - enable/disable checklists for the project
Manage templates screen:
https://{ site-url }.atlassian.net/rest/api/2/project/{ project.id }/properties/default-templates - add/remove default template to the project
Other:
Templates and other settings are currently unavailable. You can not edit them outside of the app UI and currently we are not planing to change this behavior.
Examples with Curl:
How to retrieve checklists:
To retrieve the checklist for an issue you need to provide email and API key from account with sufficient permissions as well as url with 2 variables: your "site-url" and the "issue id".
curl -u { your email }:{ your API token } https://{ site-url }.atlassian.net/rest/api/2/issue/{ issue.id }/properties/sd-checklists
How to add/update checklist:
When updating the checklist you should get the current object, edit it to your liking and then send it back also as an whole object. You shouldn't post for example only one item which you edited.
Some examples:
If you want to mark the task as done then change "completed" field of an appropriate item.
If you want to rename the task then change the "name" field of an appropriate item.
If you want to add new task then add it to "items" array.
If you want to add new checklist then add it to "checklist" array with new unique id.
Here is how you can make PUT request with curl. Adding and updating is made using the same request.
curl -X PUT -H "Content-Type: application/json" -u { your email }:{ your API token } https://{ site-url }.atlassian.net/rest/api/2/issue/{ issue.id }/properties/sd-checklists -d '{
"version":"1.0.0",
"checklists":[
{
"id":0,
"name":"Example to do",
"items":[
{
"name":"<p>task 1</p>",
"required":true,
"completed":true,
"status":0,
"user":"{ user id }",
"date":"2019-08-13T13:18:24.046Z"
},
{
"name":"<p>task 2</p>",
"required":false,
"completed":true,
"status":0,
"user":"{ user id }",
"date":"2019-08-13T13:18:44.988Z"
},
{
"name":"<p>task 3</p>",
"required":false,
"completed":false,
"status":0,
"user":"{ user id }",
"date":"2019-08-08T13:30:29.643Z"
}
]
}
]
}'
How to remove checklist:
To delete all checklist you can make a PUT request with empty data.
curl -X PUT -H "Content-Type: application/json" -u { your email }:{ your API token } https://{ site-url }.atlassian.net/rest/api/2/issue/{ issue.id }/properties/sd-checklists -d '{}'
Examples with Postman:
How to retrieve data:
To make a GET request you need to set a basic auth with your email and API token. Header will be generated automatically. Check screenshot below for an example.
How to update data:
To make a PUT request you need to set a header, basic auth with your email and API token and body with data. Check screenshot below for an example.
