How to retrieve available options for a multi-select customfield via Jira REST API
Platform Notice: Data Center - This article applies to Atlassian products on the Data Center platform.
Note that this knowledge base article was created for the Data Center version of the product. Data Center knowledge base articles for non-Data Center-specific features may also work for Server versions of the product, however they have not been tested. 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 JSWSERVER-25248 - Portfolio Team field should be a fully supported JIRA field.
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"
}
]
}
]
}