Replace issue field option

DELETE

/rest/api/3/field/{fieldKey}/option/{optionId}/issue

Issue custom field options (apps)

Deselects an issue-field select-list option from all issues where it is selected. A different option can be selected to replace the deselected option. The update can also be limited to a smaller set of issues by using a JQL query.

Connect and Forge app users with Administer Jira global permission can override the screen security configuration using overrideScreenSecurity and overrideEditableFlag.

This is an asynchronous operation. The response object contains a link to the long-running task.

Note that this operation only works for issue field select list options added by Connect apps, it cannot be used with issue field select list options created in Jira or using operations from the Issue custom field options resource.

Permissions required: Administer Jira global permission. Jira permissions are not required for the app providing the field.

Request Example

Shell

JavaScript

Java

Swift

curl --location --request DELETE 'http://jira.local:8080/jira/rest//rest/api/3/field//option//issue'

Response Example

303 - Success

{
  "self": "https://your-domain.atlassian.net/rest/api/3/task/1",
  "id": "1",
  "description": "Remove option 1 from issues matched by '*', and replace with option 3",
  "status": "COMPLETE",
  "result": {
    "modifiedIssues": [
      10001,
      10010
    ],
    "unmodifiedIssues": [
      10005
    ],
    "errors": {
      "errors": {},
      "errorMessages": [
        "Option 2 cannot be set on issue MKY-5 as it is not in the correct scope"
      ],
      "httpStatusCode": {
        "empty": false,
        "present": true
      }
    }
  },
  "elapsedRuntime": 42
}

Request

Path Params

fieldKey

string

required

The field key is specified in the following format: $(a pp - k ey)__$ (field-key). For example, example-add-on__example-issue-field. To determine the fieldKey value, do one of the following:

open the app's plugin descriptor, then app-key is the key at the top and field-key is the key in the jiraIssueFields module. app-key can also be found in the app listing in the Atlassian Universal Plugin Manager.

run Get fields and in the field details the value is returned in key. For example, "key": "teams-add-on__team-issue-field"

optionId

integer

required

The ID of the option to be deselected.

Query Params

replaceWith

integer

optional

The ID of the option that will replace the currently selected option.

jql

string

optional

A JQL query that specifies the issues to be updated. For example, project=10000.

overrideScreenSecurity

string

optional

Whether screen security is overridden to enable hidden fields to be edited. Available to Connect and Forge app users with admin permission.

overrideEditableFlag

string

optional

Whether screen security is overridden to enable uneditable fields to be edited. Available to Connect and Forge app users with Administer Jira global permission.

Responses

🔵303Returned if the long-running task to deselect the option is started.

application/json

Body

Details about a task.

description

string

optional

The description of the task.

elapsedRuntime

integer <int64>

required

The execution time of the task, in milliseconds.

finished

integer <int64>

optional

A timestamp recording when the task was finished.

string

required

The ID of the task.

lastUpdate

integer <int64>

required

A timestamp recording when the task progress was last updated.

message

string

optional

Information about the progress of the task.

progress

integer <int64>

required

The progress of the task, as a percentage complete.

result

object

optional

The result of the task execution.

errors

object

optional

A collection of errors related to unchanged issues. The collection size is limited, which means not all errors may be returned.

modifiedIssues

array[integer <int64>]

optional

The IDs of the modified issues.

unmodifiedIssues

array[integer <int64>]

optional

The IDs of the unchanged issues, those issues where errors prevent modification.

self

string <uri>

required

The URL of the task.

started

integer <int64>

optional

A timestamp recording when the task was started.

status

enum<string>

required

The status of the task.

Allowed values:

ENQUEUEDRUNNINGCOMPLETEFAILEDCANCEL_REQUESTEDCANCELLEDDEAD

submitted

integer <int64>

required

A timestamp recording when the task was submitted.

submittedBy

integer <int64>

required

The ID of the user who submitted the task.

🟠400Returned if the request is not valid.

🟠403Returned if the user does not have the necessary permission.

🟠404Returned if the field is not found or does not support options, or the options to be replaced are not found.

Modified at 2023-07-13 03:27:27

Delete issue field option

Get all field configurations