Editing templates using REST APIs

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

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

For more help with the Request URI, see 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.

Example

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	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 Checklist item representations.
`itemsJson`	String of a JSON Array	POST PUT MANDATORY A string containing an array of template items, which are simplified checklist items. Example `"[{\"name\":\"Item 1\",\"statusId\":\"inProgress\"}]"` For more information on the checklist item JSON structure, see Checklist item representations.
`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.

Example

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

GET [...]/templates

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

This API needs administrator rights.

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.

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

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

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

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.

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

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

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

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.

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

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

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

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.

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

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

POST [...]/templates

You can create a template.

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.

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.

JSON

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

Response

Returns the full JSON representation of the created template.

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

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

You can update the specified template’s content.

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.

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

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.

JSON

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

Response

Returns the full JSON representation of the updated template.

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

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.

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

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

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

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

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.

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

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.

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.