How to retrieve available options for a multi-select customfield via Jira REST API
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-1847Getting 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:
- Get create issue meta (Deprecated) (Server/DC)
- Get edit issue meta (Server/DC)
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"
}
]
}
]
}