How to retrieve available options for a multi-select customfield via Jira REST API

Still need help?

The Atlassian Community is here for you.

Ask the community

Platform notice: Server and Data Center only. This article only applies to Atlassian products on the Server and Data Center platforms.

Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.

*Except Fisheye and Crucible

Purpose

Jira Server/Data Center REST API doesn't provide a method to simply retrieve all the options available to a multi-option custom field, except if you're trying to retrieve a specific option via its ID using rest/api/2/customFieldOption/{id} (ie. you enter the option ID and it returns the value). This may be because Jira's flexibility actually makes it possible to configure different custom field contexts, and a different set of options for a custom field depending on the Custom Field context.

Being able to retrieve the options available to a multi-option custom field may be useful if you're trying to provide a value for this field when creating or editing issues via the REST API. This article provides a workaround to retrieve all custom field option data before creating or editing issues via the REST API.

Disclaimer

This workaround does not apply to the Team field of Advanced Roadmaps. A request for this to be changed is part of  JPOSERVER-1847 - Getting issue details... STATUS .
Also, other custom-type fields of third-party apps may have the same limitation.


Solution

The Create Issue and Edit Issue meta APIs may provide a workaround for retrieving custom field options in a specific or relevant context:

The metadata provided by either of the calls mentioned above would return a full list of all the available or editable fields for creating or editing an issue, including all the options for multi-option fields in the relevant context.


So for example, if you have an issue key of BIZ-1, you can make a curl REST call of

curl -u admin:password -X GET "http://localhost:8181/rest/api/2/issue/BIZ-1/editmeta"

In the results, you can see

"customfield_10112":{
"required":false,"schema":{
"type":"array","items":"option","custom":"com.atlassian.jira.plugin.system.customfieldtypes:multiselect","customId":10112},
"name":"selectmulti","fieldId":"customfield_10112","operations":["add","set","remove"],
"allowedValues":[{
"self":"http://localhost:8181/rest/api/2/customFieldOption/10000","value":"abc","id":"10000","disabled":false},
{"self":"http://localhost:8181/rest/api/2/customFieldOption/10001","value":"444","id":"10001","disabled":false},
{"self":"http://localhost:8181/rest/api/2/customFieldOption/10002","value":"asdf","id":"10002","disabled":false}]},

In this case, the valid values for that field are abc, asdf, and 444.



An alternative to this endpoint is to call the GET rest/api/2/issue/{IssueKeyorId} endpoint and expand both editmeta and field parameters. If you use this method you need to specify which fields to look for.  For example, in Jira Server/DC 8.18.1, you can make a REST API call such as

curl -u admin:password -X GET "http://localhost:8181/rest/api/2/issue/BIZ-1?expand=editmeta&fields=customfield_10112"

Where customfield_10112 is the id of this multiselect field. 

Running that command has an output of

"editmeta":{"fields":{"customfield_10112":{"required":false,"schema":{
"type":"array","items":"option","custom":"com.atlassian.jira.plugin.system.customfieldtypes:multiselect","customId":10112},
"name":"selectmulti","fieldId":"customfield_10112","operations":["add","set","remove"],
"allowedValues":[{"self":"http://localhost:8181/rest/api/2/customFieldOption/10000","value":"abc","id":"10000","disabled":false},
{"self":"http://localhost:8181/rest/api/2/customFieldOption/10001","value":"444","id":"10001","disabled":false},
{"self":"http://localhost:8181/rest/api/2/customFieldOption/10002","value":"asdf","id":"10002","disabled":false}]}}}}

Look for the "allowedValues" array to find what values are valid here.  In this case, the values are abc, asdf, and 444.


The following is another sample JSON for a cascading select list, extracted from the metadata JSON object returned by any of the methods described above. It shows all the child lists and their options

"customfield_11200": {
      "required": false,
      "schema": {
        "type": "array",
        "items": "string",
        "custom": "com.atlassian.jira.plugin.system.customfieldtypes:cascadingselect",
        "customId": 11200
      },
      "name": "cascade",
      "operations": [
        "set"
      ],
      "allowedValues": [
        {
          "self": "http://localhost:8641/rest/api/2/customFieldOption/10200",
          "value": "A",
          "id": "10200",
          "children": [
            {
              "self": "http://localhost:8641/rest/api/2/customFieldOption/10202",
              "value": "A1",
              "id": "10202"
            },
            {
              "self": "http://localhost:8641/rest/api/2/customFieldOption/10203",
              "value": "A2",
              "id": "10203"
            }
          ]
        },
        {
          "self": "http://localhost:8641/rest/api/2/customFieldOption/10201",
          "value": "B",
          "id": "10201",
          "children": [
            {
              "self": "http://localhost:8641/rest/api/2/customFieldOption/10204",
              "value": "B1",
              "id": "10204"
            },
            {
              "self": "http://localhost:8641/rest/api/2/customFieldOption/10205",
              "value": "B2",
              "id": "10205"
            }
          ]
        }
      ]
    }



Last modified on Sep 19, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.