Editing templates using REST APIs

available since 6.1.0

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

This API lets you configure templates.

1 Request URI
2 Template API JSON structures
- 2.1 Template
- 2.2 Template list
3 APIs
- 3.1 Get all templates
- 3.2 Get a single template
- 3.3 Get templates available within a project
- 3.4 Get importable templates
- 3.5 Create a template
- 3.6 Update a template
- 3.7 See where a template is in use
- 3.8 Delete a template
- 3.9 Add template to favorites
- 3.10 Remove template from favorites

Request URI

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

{JIRA Instance}/rest/com.okapya.jira.checklist/latest/

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.

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

Field	Type	Description
`id`	Numeric	get The template’s unique identifier. This is the ID used when updating or querying a single template.
`items`	JSON Array	get An array of template items, which are simplified checklist items. For more information on the checklist item JSON structure, see https://okapya.atlassian.net/wiki/spaces/CHKDOC5/pages/3236626499.
`itemsJson`	String of a JSON Array	post put mandatory A string containing an array of template items, which are simplified checklist items. `"[{\"name\":\"Item 1\",\"statusId\":\"inProgress\"}]"`
`name`	String	mandatory The name of the template that will be seen and searched by users.
`description`	String	The template’s description.
`fieldConfigId`	Numeric	mandatory The configuration scheme context to which the template can apply. This determines what features are available when adding and editing items.
`projectId`	Numeric	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	get The key of the project obtained through the `projectId` field.
`projectName`	String	get The name of the project obtained through the `projectId` field.
`project`	String	post 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	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	get The configuration scheme context's name.
`customFieldName`	String	get The configuration scheme context’s checklist custom field name.
`projectAvatarId`	Numeric	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.

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

Field	Type	Description

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

get [...]/templates

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

	Description	Example

Description

Example

Query parameters

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.

Get a single template

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

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

	Description	Example

	Description	Example
Response	Returns the full JSON representation of the requested template.

Get templates available within a project

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

	Description	Example

Description

Example

Query parameters

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.

Get importable templates

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

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

	Description	Example

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

Create a template

post [...]/templates

You can create a template.

	Description	Example

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.

Response

Returns the full JSON representation of the created template.

Update a template

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

You can update the specified template’s content.

	Description	Example

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.

Response

Returns the full JSON representation of the updated template.

See where a template is in use

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.

	Description	Example

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

Delete a template

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

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

Add template to favorites

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

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

This API does not return a response.

Remove template from favorites

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

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

This API does not return a response.

Checklist for Jira - Server & Data Center Docs

Editing templates using REST APIs

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

SERVER documentation (On Cloud? Go here.)

Have questions? Contact our Service Desk for help anytime.