Editing global items using REST APIs

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:

CODE

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

See Configuring checklists using REST APIs: Base configuration path for more help with the Request URI.

APIs

Create

POST [...]/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.

JSON

{
  "name": "All tests clear"
}

or

JSON

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

Response

Returns the full JSON representation of the newly created item.

JSON

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

GET [...]/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

OPTIONAL

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.

JSON

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

GET [...]/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.	JSON `{ "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

PUT [...]/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.

JSON

{"mandatory":false}

or

JSON

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

Response

Returns the full JSON representation of the updated global item.

JSON

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

GET [...]/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.	JSON `{ "issueCount": 123 }`

Delete

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

You can delete a global item in the field configuration.

Description

Example

Query parameters

OPTIONAL

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 Exceptions for configuration REST APIs: Global item exceptions.