Class IssueCustomFieldOptionsAppsService

This resource represents custom issue field select list options created by a Connect app. See Issue custom field options to manipulate options created in Jira or using the REST API.

A select list issue field is a type of issue field that enables a user to select an option from a list. Use it to add, remove, and update the options of a select list issue field.

See

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-custom-field-options-apps-

Hierarchy

  • CommonHttpService
    • IssueCustomFieldOptionsAppsService

Constructors

constructor

Methods

createIssueFieldOption deleteIssueFieldOption getAllIssueFieldOptions getIssueFieldOption getSelectableIssueFieldOptions getVisibleIssueFieldOptions replaceIssueFieldOption updateIssueFieldOption initialize

Constructors

constructor

Methods

createIssueFieldOption

  • createIssueFieldOption(params): Promise<IssueFieldOption>

  • Creates an option for a select list issue field.

    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.

    Each field can have a maximum of 10000 options, and each option can have a maximum of 10000 scopes.

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

    Parameters

    • params: {
          fieldKey: string;
          issueFieldOptionCreateBean: IssueFieldOptionCreateBean;
      }
      • fieldKey: string

        The field key is specified in the following format: $(app-key)__$(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"
      • issueFieldOptionCreateBean: IssueFieldOptionCreateBean

        Example

    Returns Promise<IssueFieldOption>

    Returned if the request is successful.

    example:

    {
      "id": 1,
      "value": "Team 1",
      "properties": {
        "leader": {
          "name": "Leader Name",
          "email": "lname@example.com"
        },
        "members": 42,
        "description": "The team's description",
        "founded": "2016-06-06"
      },
      "config": {
        "scope": {
          "projects": [],
          "projects2": [
            {
              "id": 1001,
              "attributes": [
                "notSelectable"
              ]
            },
            {
              "id": 1002,
              "attributes": [
                "notSelectable"
              ]
            }
          ],
          "global": {}
        },
        "attributes": []
      }
    }

    Path

    POST /rest/api/3/field/{fieldKey}/option @scopes-current manage:jira-configuration @scopes-beta write:field.option:jira

    See

    https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-custom-field-options-apps-#api-rest-api-3-field-fieldkey-option-post

deleteIssueFieldOption

  • deleteIssueFieldOption(params): Promise<void>

  • Deletes an option from a select list issue field.

    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.

    Parameters

    • params: {
          fieldKey: string;
          optionId: number;
      }
      • fieldKey: string

        The field key is specified in the following format: $(app-key)__$(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: number

        The ID of the option to be deleted.

    Returns Promise<void>

    Returned if the field option is deleted.

    Path

    DELETE /rest/api/3/field/{fieldKey}/option/{optionId} @scopes-current manage:jira-configuration @scopes-beta delete:field.option:jira

    See

    https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-custom-field-options-apps-#api-rest-api-3-field-fieldkey-option-optionid-delete

getAllIssueFieldOptions

  • getAllIssueFieldOptions(params): Promise<PageBeanIssueFieldOption>

  • Returns a paginated list of all the options of a select list issue field. A select list issue field is a type of issue field that enables a user to select a value from a list of options.

    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.

    Parameters

    • params: {
          fieldKey: string;
          maxResults?: number;
          startAt?: number;
      }
      • fieldKey: string

        The field key is specified in the following format: $(app-key)__$(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"
      • OptionalmaxResults?: number

        The maximum number of items to return per page.

      • OptionalstartAt?: number

        The index of the first item to return in a page of results (page offset).

    Returns Promise<PageBeanIssueFieldOption>

    Returned if the request is successful.

    example:

    {
      "isLast": false,
      "maxResults": 1,
      "nextPage": "https://your-domain.atlassian.net/rest/api/3/field/fieldKey/option?startAt=1&maxResults=1",
      "self": "https://your-domain.atlassian.net/rest/api/3/field/fieldKey/option?startAt=0&maxResults=1",
      "startAt": 0,
      "total": 10,
      "values": [
        {
          "id": 1,
          "value": "Team 1",
          "properties": {
            "leader": {
              "name": "Leader Name",
              "email": "lname@example.com"
            },
            "members": 42,
            "description": "The team's description",
            "founded": "2016-06-06"
          },
          "config": {
            "scope": {
              "projects": [],
              "projects2": [
                {
                  "id": 1001,
                  "attributes": [
                    "notSelectable"
                  ]
                },
                {
                  "id": 1002,
                  "attributes": [
                    "notSelectable"
                  ]
                }
              ],
              "global": {}
            },
            "attributes": []
          }
        }
      ]
    }

    Path

    GET /rest/api/3/field/{fieldKey}/option @scopes-current manage:jira-configuration @scopes-beta read:field.option:jira

    See

    https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-custom-field-options-apps-#api-rest-api-3-field-fieldkey-option-get

getIssueFieldOption

  • getIssueFieldOption(params): Promise<IssueFieldOption>

  • Returns an option from a select list issue field.

    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.

    Parameters

    • params: {
          fieldKey: string;
          optionId: number;
      }
      • fieldKey: string

        The field key is specified in the following format: $(app-key)__$(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: number

        The ID of the option to be returned.

    Returns Promise<IssueFieldOption>

    Returned if the requested option is returned.

    example:

    {
      "id": 1,
      "value": "Team 1",
      "properties": {
        "leader": {
          "name": "Leader Name",
          "email": "lname@example.com"
        },
        "members": 42,
        "description": "The team's description",
        "founded": "2016-06-06"
      },
      "config": {
        "scope": {
          "projects": [],
          "projects2": [
            {
              "id": 1001,
              "attributes": [
                "notSelectable"
              ]
            },
            {
              "id": 1002,
              "attributes": [
                "notSelectable"
              ]
            }
          ],
          "global": {}
        },
        "attributes": []
      }
    }

    Path

    GET /rest/api/3/field/{fieldKey}/option/{optionId} @scopes-current manage:jira-configuration @scopes-beta read:field.option:jira

    See

    https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-custom-field-options-apps-#api-rest-api-3-field-fieldkey-option-optionid-get

getSelectableIssueFieldOptions

  • getSelectableIssueFieldOptions(params): Promise<PageBeanIssueFieldOption>

  • Returns a paginated list of options for a select list issue field that can be viewed and selected by the user.

    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: Permission to access Jira.

    Parameters

    • params: {
          fieldKey: string;
          maxResults?: number;
          projectId?: number;
          startAt?: number;
      }
      • fieldKey: string

        The field key is specified in the following format: $(app-key)__$(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"
      • OptionalmaxResults?: number

        The maximum number of items to return per page.

      • OptionalprojectId?: number

        Filters the results to options that are only available in the specified project.

      • OptionalstartAt?: number

        The index of the first item to return in a page of results (page offset).

    Returns Promise<PageBeanIssueFieldOption>

    Returned if the request is successful.

    example:

    {
      "isLast": false,
      "maxResults": 1,
      "nextPage": "https://your-domain.atlassian.net/rest/api/3/field/fieldKey/option/suggestions?startAt=1&maxResults=1",
      "self": "https://your-domain.atlassian.net/rest/api/3/field/fieldKey/option/suggestions?startAt=0&maxResults=1",
      "startAt": 0,
      "total": 10,
      "values": [
        {
          "id": 1,
          "value": "Team 1",
          "properties": {
            "leader": {
              "name": "Leader Name",
              "email": "lname@example.com"
            },
            "members": 42,
            "description": "The team's description",
            "founded": "2016-06-06"
          }
        }
      ]
    }

    Path

    GET /rest/api/3/field/{fieldKey}/option/suggestions/edit @scopes-current read:jira-work @scopes-beta read:field.option:jira

    See

    https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-custom-field-options-apps-#api-rest-api-3-field-fieldkey-option-suggestions-edit-get

getVisibleIssueFieldOptions

  • getVisibleIssueFieldOptions(params): Promise<PageBeanIssueFieldOption>

  • Returns a paginated list of options for a select list issue field that can be viewed by the user.

    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: Permission to access Jira.

    Parameters

    • params: {
          fieldKey: string;
          maxResults?: number;
          projectId?: number;
          startAt?: number;
      }
      • fieldKey: string

        The field key is specified in the following format: $(app-key)__$(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"
      • OptionalmaxResults?: number

        The maximum number of items to return per page.

      • OptionalprojectId?: number

        Filters the results to options that are only available in the specified project.

      • OptionalstartAt?: number

        The index of the first item to return in a page of results (page offset).

    Returns Promise<PageBeanIssueFieldOption>

    Returned if the request is successful.

    example:

    {
      "isLast": false,
      "maxResults": 1,
      "nextPage": "https://your-domain.atlassian.net/rest/api/3/field/fieldKey/option/suggestions?startAt=1&maxResults=1",
      "self": "https://your-domain.atlassian.net/rest/api/3/field/fieldKey/option/suggestions?startAt=0&maxResults=1",
      "startAt": 0,
      "total": 10,
      "values": [
        {
          "id": 1,
          "value": "Team 1",
          "properties": {
            "leader": {
              "name": "Leader Name",
              "email": "lname@example.com"
            },
            "members": 42,
            "description": "The team's description",
            "founded": "2016-06-06"
          }
        }
      ]
    }

    Path

    GET /rest/api/3/field/{fieldKey}/option/suggestions/search @scopes-current read:jira-work @scopes-beta read:field.option:jira

    See

    https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-custom-field-options-apps-#api-rest-api-3-field-fieldkey-option-suggestions-search-get

replaceIssueFieldOption

  • replaceIssueFieldOption(params): Promise<void>

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

    Parameters

    • params: {
          fieldKey: string;
          jql?: string;
          optionId: number;
          overrideEditableFlag?: boolean;
          overrideScreenSecurity?: boolean;
          replaceWith?: number;
      }
      • fieldKey: string

        The field key is specified in the following format: $(app-key)__$(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"
      • Optionaljql?: string

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

      • optionId: number

        The ID of the option to be deselected.

      • OptionaloverrideEditableFlag?: boolean

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

      • OptionaloverrideScreenSecurity?: boolean

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

      • OptionalreplaceWith?: number

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

    Returns Promise<void>

    Path

    DELETE /rest/api/3/field/{fieldKey}/option/{optionId}/issue @scopes-current manage:jira-configuration @scopes-beta write:field.option:jira, delete:field.option:jira

    See

    https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-custom-field-options-apps-#api-rest-api-3-field-fieldkey-option-optionid-issue-delete

updateIssueFieldOption

  • updateIssueFieldOption(params): Promise<IssueFieldOption>

  • Updates or creates an option for a select list issue field. This operation requires that the option ID is provided when creating an option, therefore, the option ID needs to be specified as a path and body parameter. The option ID provided in the path and body must be identical.

    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.

    Parameters

    • params: {
          fieldKey: string;
          issueFieldOption: IssueFieldOption;
          optionId: number;
      }
      • fieldKey: string

        The field key is specified in the following format: $(app-key)__$(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"
      • issueFieldOption: IssueFieldOption

        Example

      • optionId: number

        The ID of the option to be updated.

    Returns Promise<IssueFieldOption>

    Returned if the option is updated or created.

    example:

    {
      "id": 1,
      "value": "Team 1",
      "properties": {
        "leader": {
          "name": "Leader Name",
          "email": "lname@example.com"
        },
        "members": 42,
        "description": "The team's description",
        "founded": "2016-06-06"
      },
      "config": {
        "scope": {
          "projects": [],
          "projects2": [
            {
              "id": 1001,
              "attributes": [
                "notSelectable"
              ]
            },
            {
              "id": 1002,
              "attributes": [
                "notSelectable"
              ]
            }
          ],
          "global": {}
        },
        "attributes": []
      }
    }

    Path

    PUT /rest/api/3/field/{fieldKey}/option/{optionId} @scopes-current manage:jira-configuration @scopes-beta write:field.option:jira

    See

    https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-custom-field-options-apps-#api-rest-api-3-field-fieldkey-option-optionid-put

Protected Staticinitialize

  • initialize(): void

  • Method to initialize the class. Normally used to set up validation rules.

    Returns void

Settings

Member Visibility

On This Page

Constructors
Methods