Page Comparison

Status

title	available since 6.1.0

Info
To improve readability, all JSON results will be beautified, whereas the actual results will not.

This API lets you configure templates.

Request URI

The base request URI for all APIs on this page is as follows:

Code Block
{JIRA Instance}/rest/com.okapya.jira.checklist/latest/checklists/templates

Info
For more help with the Request URI, see https://okapya.atlassian.net/wiki/spaces/CHKDOC5/pages/2940666209/Configuring+checklists+using+REST+APIs#Base-configuration-path.

Template API JSON structures

Template

When templates are manipulated through REST APIs, they are enriched with metadata information, such as the custom field and project names.

Expand

title	Example

Code Block

language	json

{
   "id":1,
   "items":[
      {
         "id":-1,
         "name":"Investigate",
         "mandatory":false,
         "rank":0,
         "statusId":"none",
         "dueDate":null,
         "isHeader":false,
         "checked":false,
         "priorityId":null
      },
      {
         "id":-2,
         "name":"Fix",
         "mandatory":false,
         "rank":1,
         "statusId":"none",
         "dueDate":null,
         "isHeader":false,
         "checked":false,
         "priorityId":null
      }
   ],
   "name":"Bug fixing",
   "description":"",
   "fieldConfigId":10302,
   "projectId":10000,
   "customFieldId":10101,
   "importable": true,
   "pinned": false,
   "projectKey":"OK",
   "projectName":"Okapya",
   "fieldConfigName":"Default Configuration Scheme for DoD",
   "customFieldName":"DoD",
   "projectAvatarId":10324
}

Field

Type

Description

id

Numeric

Status

colour	Green
title	get

The template’s unique identifier. This is the ID used when updating or querying a single template.

items

JSON Array

Status

colour	Green
title	get

An array of template items, which are simplified checklist items.

Info
For more information on the checklist item JSON structure, see Checklist item representations.

itemsJson

String of a JSON Array

Status

colour	Purple
title	post

Status

colour	Yellow
title	put

Status

colour	Yellow
title	mandatory

A string containing an array of template items, which are simplified checklist items.

Expand

title	Example

"[{\"name\":\"Item 1\",\"statusId\":\"inProgress\"}]"

Info
For more information on the checklist item JSON structure, see Checklist item representations.

name

String

Status

colour	Yellow
title	mandatory

The name of the template that will be seen and searched by users.

description

String

The template’s description.

fieldConfigId

Numeric

Status

colour	Yellow
title	mandatory

The configuration scheme context to which the template can apply. This determines what features are available when adding and editing items.

projectId

Numeric

Status

colour	Green
title	get

The project to which the template is specific. Project-specific templates can be edited by the project’s administrator from the Project Settings page or through REST APIs.

Templates that are not project-specific are considered global and will be available in all projects within the template’s custom field context. Because global templates can be used in other projects, only administrators can edit or delete them from the Manage apps or Field config context pages or through REST APIs.

projectKey

String

Status

colour	Green
title	get

The key of the project obtained through the projectId field.

projectName

String

Status

colour	Green
title	get

The name of the project obtained through the projectId field.

project

String

Status

colour	Purple
title	post

Status

colour	Yellow
title	put

Use this field when setting the template’s project. Either the project key or the project ID can be passed as a parameter.

customFieldId

Numeric

Status

colour	Green
title	get

The configuration scheme context’s checklist custom field ID.

owner

String

The owner of the template. Defaults to the template creator.

Allows users to modify their own templates when the Create / Edit Templates from Checklists parameter is enabled.

importable

Boolean

Indicates whether or not this template is available when importing a template in a checklist. Defaults to true.

Templates that are marked as “not importable” are typically used for default local items and/or post functions and are not meant to be used by end users.

pinned

Boolean

Indicates whether or not this template will be pinned in the template dropdown menu. Defaults to false.

fieldConfigName

String

Status

colour	Green
title	get

The configuration scheme context's name.

customFieldName

String

Status

colour	Green
title	get

The configuration scheme context’s checklist custom field name.

projectAvatarId

Numeric

Status

colour	Green
title	get

The avatar ID of the project obtained through the projectId field.

Template list

The template list consists of pagination information with a list of templates.

Expand

title	Example

Code Block

language	json

{
   "page":1,
   "totalCount":23,
   "templates":[
      {
         // Template 1 contents
      },
      {
         // Template 2 contents
      }
   ],
   "count":10,
   "countPerPage":10
}

Field	Type	Description
`page`	Numeric	The queried page. If the value is `null`, then pagination was not used to query the template list, which means that all of the queried templates should be included in the list.
`totalCount`	Numeric	The total number of templates available through the call, omitting pagination.
`templates`	JSON Array	The list of templates resulting from the API call.
`count`	Numeric	The number of templates in the list.
`countPerPage`	Numeric	The maximum number of templates per page, if pagination is used.

APIs

Get all templates

Status

colour	Green
title	get

[...]/templates

You can get all templates with the option to paginate and filter the results.

Note
This API needs administrator rights.

Description

Example

Query parameters

Status

title	all parameters are optional

page indicates what page should be fetched. When using pages, templates are grouped 10 to a page. If unspecified, all templates are queried.
nameFilter only fetches templates with a name that contains what is specified in the filter. The filter is case insensitive.
customFieldId only fetches templates that are configured for the specified custom field ID.
fieldConfigId only fetches templates that are configured for the specified field configuration ID.
project only fetches templates that are configured to be specific to the specified project key or ID.

[...]/templates?page=1&customFieldId=10001

Response

Returns the full JSON representation of the list of templates with pagination information.

Code Block

language	json

{
  "page": null,
  "totalCount": 2,
  "templates": [
    {
      "id": 1,
      "items": [
        {
          "id": -1,
          "name": "Analyze",
          "mandatory": false,
          "rank": 0,
          "statusId": "none",
          "dueDate": null,
          "isHeader": false,
          "checked": false,
          "priorityId": null
        },
        {
          "id": -2,
          "name": "Develop",
          "mandatory": false,
          "rank": 1,
          "statusId": "none",
          "dueDate": null,
          "isHeader": false,
          "checked": false,
          "priorityId": null
        }
      ],
      "name": "Development template",
      "description": "",
      "fieldConfigId": 10302,
      "projectId": null,
      "customFieldId": 10101,
      "owner": "johnb",
      "importable": true,
      "projectKey": null,
      "projectName": null,
      "fieldConfigName": "Default Configuration Scheme for DoD",
      "customFieldName": "DoD",
      "projectAvatarId": null
    },
    {
      "id": 2,
      "items": [
        {
          "id": -1,
          "name": "Investigate",
          "mandatory": true,
          "rank": 0,
          "statusId": "none",
          "dueDate": null,
          "isHeader": false,
          "checked": false,
          "priorityId": null
        },
        {
          "id": -2,
          "name": "Correct",
          "mandatory": true,
          "rank": 1,
          "statusId": "none",
          "dueDate": null,
          "isHeader": false,
          "checked": false,
          "priorityId": null
        }
      ],
      "name": "Bugfix template",
      "description": "",
      "fieldConfigId": 10302,
      "projectId": null,
      "customFieldId": 10101,
      "owner": "admin",
      "importable": true,
      "pinned": false,
      "projectKey": null,
      "projectName": null,
      "fieldConfigName": "Default Configuration Scheme for DoD",
      "customFieldName": "DoD",
      "projectAvatarId": null
    }
  ],
  "count": 2,
  "countPerPage": 10
}

Get a single template

Status

colour	Green
title	get

[...]/templates/{templateId}

By providing a template ID, you can get the contents of a single template.

Note
This API needs browsing rights on at least one project in which the template applies, unless the template is specific to a project, in which case the user needs browsing rights on the template’s project.

Description

Example

Response

Returns the full JSON representation of the requested template.

Code Block

language	json

{
   "id":1,
   "items":[
      {
         "id":-1,
         "name":"Analyze",
         "mandatory":false,
         "rank":0,
         "statusId":"none",
         "isHeader":false,
         "checked":false
      },
      {
         "id":-2,
         "name":"Develop",
         "mandatory":false,
         "rank":1,
         "statusId":"none",
         "isHeader":false,
         "checked":false
      }
   ],
   "name":"Development template",
   "fieldConfigId":10302,
   "customFieldId":10101,
   "fieldConfigName":"Default Configuration Scheme for DoD",
   "customFieldName":"DoD"
}

Get templates available within a project

Status

colour	Green
title	get

[...]/projects/{projectKeyOrID}/templates

You can get all templates that can be used for the provided project key or ID, including global templates (templates that have no value in their projectId field).

Note
This API needs browsing rights on the provided project key or ID.

Description

Example

Query parameters

Status

title	all parameters are optional

page indicates what page should be fetched. When using pages, templates are grouped 10 to a page. If unspecified, all templates are queried.
nameFilter only fetches templates with a name that contains what is specified in the filter. The filter is case insensitive.
customFieldId only fetches templates that are configured for the specified custom field ID.
importable only fetches importable templates.

[...]/projects/10001/templates?page=1&customFieldId=10001

Response

Returns the full JSON representation of the list of templates with pagination information.

Code Block

language	json

{
  "page": null,
  "totalCount": 2,
  "templates": [
    {
      "id": 1,
      "items": [
        {
          "id": -1,
          "name": "Analyze",
          "mandatory": false,
          "rank": 0,
          "statusId": "none",
          "dueDate": null,
          "isHeader": false,
          "checked": false,
          "priorityId": null
        },
        {
          "id": -2,
          "name": "Develop",
          "mandatory": false,
          "rank": 1,
          "statusId": "none",
          "dueDate": null,
          "isHeader": false,
          "checked": false,
          "priorityId": null
        }
      ],
      "name": "Development template",
      "description": "",
      "fieldConfigId": 10302,
      "projectId": null,
      "customFieldId": 10101,
      "owner": "johnb",
      "importable": true,
      "projectKey": null,
      "projectName": null,
      "fieldConfigName": "Default Configuration Scheme for DoD",
      "customFieldName": "DoD",
      "projectAvatarId": null
    },
    {
      "id": 2,
      "items": [
        {
          "id": -1,
          "name": "Investigate",
          "mandatory": true,
          "rank": 0,
          "statusId": "none",
          "dueDate": null,
          "isHeader": false,
          "checked": false,
          "priorityId": null
        },
        {
          "id": -2,
          "name": "Correct",
          "mandatory": true,
          "rank": 1,
          "statusId": "none",
          "dueDate": null,
          "isHeader": false,
          "checked": false,
          "priorityId": null
        }
      ],
      "name": "Bugfix template",
      "description": "",
      "fieldConfigId": 10302,
      "projectId": null,
      "customFieldId": 10101,
      "owner": "admin",
      "importable": true,
      "projectKey": null,
      "projectName": null,
      "fieldConfigName": "Default Configuration Scheme for DoD",
      "customFieldName": "DoD",
      "projectAvatarId": null
    }
  ],
  "count": 2,
  "countPerPage": 10
}

Get importable templates

Status

colour	Green
title	get

[...]/projects/{projectKeyOrID}/customFields/{customFieldId}/templates

You can obtain all templates that are importable for the provided project and custom field ID.

Note
This API needs browsing rights on the provided project key or ID.

Description

Example

Response

Returns the full JSON representation of the list of templates with empty pagination information.

Info
Because no pagination is required in this API, the `page` field will always be null. The response will always include all importable templates.

Code Block

language	json

{
  "page": null,
  "totalCount": 2,
  "templates": [
    {
      "id": 1,
      "items": [
        {
          "id": -1,
          "name": "Analyze",
          "mandatory": false,
          "rank": 0,
          "statusId": "none",
          "dueDate": null,
          "isHeader": false,
          "checked": false,
          "priorityId": null
        },
        {
          "id": -2,
          "name": "Develop",
          "mandatory": false,
          "rank": 1,
          "statusId": "none",
          "dueDate": null,
          "isHeader": false,
          "checked": false,
          "priorityId": null
        }
      ],
      "name": "Development template",
      "description": "",
      "fieldConfigId": 10302,
      "projectId": null,
      "customFieldId": 10101,
      "owner": "johnb",
      "importable": true,
      "projectKey": null,
      "projectName": null,
      "fieldConfigName": "Default Configuration Scheme for DoD",
      "customFieldName": "DoD",
      "projectAvatarId": null
    },
    {
      "id": 2,
      "items": [
        {
          "id": -1,
          "name": "Investigate",
          "mandatory": true,
          "rank": 0,
          "statusId": "none",
          "dueDate": null,
          "isHeader": false,
          "checked": false,
          "priorityId": null
        },
        {
          "id": -2,
          "name": "Correct",
          "mandatory": true,
          "rank": 1,
          "statusId": "none",
          "dueDate": null,
          "isHeader": false,
          "checked": false,
          "priorityId": null
        }
      ],
      "name": "Bugfix template",
      "description": "",
      "fieldConfigId": 10302,
      "projectId": null,
      "customFieldId": 10101,
      "owner": "admin",
      "importable": true,
      "projectKey": null,
      "projectName": null,
      "fieldConfigName": "Default Configuration Scheme for DoD",
      "customFieldName": "DoD",
      "projectAvatarId": null
    }
  ],
  "count": 2,
  "countPerPage": 10
}

Create a template

Status

colour	Purple
title	post

[...]/templates

You can create a template.

Note

This API needs administrator rights, unless the template is project-specific, in which case the user needs administration rights on the template’s project.

When the Create/Edit Templates from Checklists feature is enabled, users can create project-specific templates.

Description

Example

Request

A web form that includes all the fields for the template that you are creating.

The form can be simplified to only include the required fields.

Note
The value of the `rank` field in the items is ignored. The order in which the items are received dictates their order in the template.

Code Block

language	json

{
  "name": "New template name!",
  "importable": false
}

Response

Returns the full JSON representation of the created template.

Code Block

language	json

{
  "id": 1,
  "items": [
    {
      "id": -1,
      "name": "Analyze",
      "mandatory": false,
      "rank": 0,
      "statusId": "none",
      "dueDate": null,
      "isHeader": false,
      "checked": false,
      "priorityId": null
    },
    {
      "id": -1,
      "name": "Develop",
      "mandatory": false,
      "rank": 1,
      "statusId": "none",
      "dueDate": null,
      "isHeader": false,
      "checked": false,
      "priorityId": null
    }
  ],
  "name": "New template",
  "description": "",
  "fieldConfigId": 10302,
  "projectId": null,
  "customFieldId": 10101,
  "owner": "creator",
  "importable": false,
  "projectKey": null,
  "projectName": null,
  "fieldConfigName": "Default Configuration Scheme for DoD",
  "customFieldName": "DoD",
  "projectAvatarId": null
}

Update a template

Status

colour	Yellow
title	PUT

[...]/templates/{templateId}

You can update the specified template’s content.

Note

This API needs administrator rights, unless either the updated template is project-specific or the payload contains the project field. In either case, the user must have administration rights on the related projects.

When the Create/Edit Templates from Checklists feature is enabled, users can update the templates they own.

Only administrators can update the owner of a template.

Description

Example

Request

A JSON representation of the fields to update.

The items are a JSON array of checklist items.

To keep updating simple, you only have to list the fields and values that you want to update.

Note
Updating items' fields replaces all items with the specified value.

Note
The value of the `rank` field in the items is ignored. The order in which the items are received dictates their order in the template.

Code Block

language	json

{
  "name": "New template name!",
  "importable": false
}

Response

Returns the full JSON representation of the updated template.

Code Block

language	json

{
  "id": 1,
  "items": [
    {
      "id": -1,
      "name": "Analyze",
      "mandatory": false,
      "rank": 0,
      "statusId": "none",
      "dueDate": null,
      "isHeader": false,
      "checked": false,
      "priorityId": null
    },
    {
      "id": -2,
      "name": "Develop",
      "mandatory": false,
      "rank": 1,
      "statusId": "none",
      "dueDate": null,
      "isHeader": false,
      "checked": false,
      "priorityId": null
    }
  ],
  "name": "New template name!",
  "description": "",
  "fieldConfigId": 10302,
  "projectId": null,
  "customFieldId": 10101,
  "importable": false,
  "projectKey": null,
  "projectName": null,
  "fieldConfigName": "Default Configuration Scheme for DoD",
  "customFieldName": "DoD",
  "projectAvatarId": null
}

See where a template is in use

Status

colour	Green
title	GET

[...]/templates/{templateId}/usages

You can use this query to see where the template has been used to configure default local items and Modify Checklists post functions.

Note
This API needs administrator rights unless the template is project-specific, in which case the user needs administration rights on the template’s project.

Description

Example

Response

Returns a JSON array with the list of the template is used.

Code Block

language	json

[
   "Workflow Function 'Start Development Process' in transition 'Start Progress' of workflow 'OK: Project Management Workflow'.",
   "Default Local Items of Checklist 'DoD'."
]

Delete a template

Status

colour	Red
title	delete

[...]/templates/{templateId}

You can delete a template. This API does not return a response.

Note

This API needs administrator rights unless the template is project-specific, in which case the user needs administration rights on the template’s project.

When the Create/Edit Templates from Checklists feature is enabled, users can delete templates they own.

Add template to favorites

Status

colour	Purple
title	POST

[...]/templates/{templateId}/favorite

You can add a template to your personal favorites. If the template is already a favorite, the API still returns

Status

title	200 OK

.

This API does not return a response.

Note
This API needs browsing rights on at least one project where the template is applicable, unless the template is specific to a project, in which case you need browsing rights on the template’s project.

Remove template from favorites

Status

colour	Red
title	DELETE

[...]/templates/{templateId}/favorite

You can remove a template from your personal favorites. If the template is not a favorite, the API still returns

Status

title	200 OK

.

This API does not return a response.

Note
This API needs browsing rights on at least one project where the template is applicable, unless the template is specific to a project, in which case you need browsing rights on the template’s project.

Versions Compared

Old Version 2

New Version Current

Key

On this page:

Request URI

Template API JSON structures

Template

Template list

APIs

Get all templates

Get a single template

Get templates available within a project

Get importable templates

Create a template

Update a template

See where a template is in use

Delete a template

Add template to favorites

Remove template from favorites

Status
title SERVER documentation
(On Cloud? Go here.)

Have questions? Contact our Service Desk for help anytime.

Page Comparison

Versions Compared

Old Version 2

New Version Current

Key

On this page:

Request URI

Template API JSON structures

Template

Template list

APIs

Get all templates

Get a single template

Get templates available within a project

Get importable templates

Create a template

Update a template

See where a template is in use

Delete a template

Add template to favorites

Remove template from favorites

StatustitleSERVER documentation (On Cloud? Go here.)

Have questions? Contact our Service Desk for help anytime.

Status
title SERVER documentation
(On Cloud? Go here.)