You need administrator rights in Jira to perform the tasks on this page.

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

Request URI

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

http://{JIRA Instance Name}/rest/com.okapya.jira.checklist/latest/checklists/configuration/{FieldConfigId}/globalitems

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

APIs

Create

[...]/globalitems

You can create a new global item in the field configuration.

Description

Example

Request

A JSON representation of the item to create.

The JSON can be simplified to only include the required fields, such as the name.

Specifying a rank value will insert the item at that specific rank.

Ranks are zero-based.

{
  "name": "All tests clear"
}

or

{
  "name": "All tests clear",
  "statusId": "blocked"
}

Response

Returns the full JSON representation of the newly created item.

{
  "id": 3,
  "name": "All tests clear",
  "mandatory": true,
  "rank": 0,
  "statusId": "blocked",
  "dueDate": null,
  "isHeader": false,
  "checked": false,
  "priorityId": null,
  "disabled": false
}

Get all items

[...]/globalitems

You can get all global items included in the path’s field configuration, with the option to exclude disabled items.

Description

Example

Query parameters

enabledOnly can be appended as a query parameter to exclude disabled items.

[...]/globalitems?enabledOnly

Response

Returns the full JSON representation of the list of global items.

[
  {
    "id": 3,
    "name": "All tests clear",
    "mandatory": true,
    "rank": 0,
    "statusId": "none",
    "dueDate": null,
    "isHeader": false,
    "checked": false,
    "priorityId": null,
    "disabled": false
  },
  {
    "id": 5,
    "name": "Development reviewed",
    "mandatory": true,
    "rank": 1,
    "statusId": "none",
    "dueDate": null,
    "isHeader": false,
    "checked": false,
    "priorityId": null,
    "disabled": false
  }
]

Get a single item

[...]/globalitems/{globalItemId}

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

Description

Example

Response

Returns the full JSON representation of the requested global item.

{
  "id": 3,
  "name": "All tests clear",
  "mandatory": true,
  "rank": 0,
  "statusId": "none",
  "dueDate": null,
  "isHeader": false,
  "checked": false,
  "priorityId": null,
  "disabled": false
}

Update an item

[...]/globalitems/{globalItemId}

You can update the specified global item’s content.

Description

Example

Request

A JSON representation of the fields to update, including their values.

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

Specifying a rank value will move the item at that specific rank.

Ranks are zero-based.

{"mandatory":false}

or

{"mandatory":false, "disabled":true}

Response

Returns the full JSON representation of the updated global item.

{
  "id": 3,
  "name": "All tests clear",
  "mandatory": false,
  "rank": 0,
  "statusId": "none",
  "dueDate": null,
  "isHeader": false,
  "checked": false,
  "priorityId": null,
  "disabled": true
}

See where a global item is in use

[...]/globalitems/{globalItemId}/usages

You can query to know how many issues currently have a value for the global item.

Description

Example

Response

Returns a JSON with the number of issues that have a value for the specified global item.

{
  "issueCount": 123
}

Delete

[...]/globalitems/{globalItemId}

You can delete a global item in the field configuration.

Description

Example

Query parameters

deleteIssueValues can be appended as a query parameter to also delete issue values.

If this parameter isn’t provided, issue values won’t be deleted.

The deletion will behave the same way as if the Global Item Validation setting were disabled.

[...]/globalitems/1?deleteIssueValues

Exceptions

For the list of potential exceptions, see https://okapya.atlassian.net/wiki/spaces/CHKDOC5/pages/2940666327/Exceptions+for+configuration+REST+APIs#Global-items-exceptions.

(On Cloud? Go here.)
Have questions? Contact our Service Desk for help anytime.