Cascading Select - Options API
On this page
Cascading Select API settings
You’ll find the API setting below the fields table on the admin dashboard (Jira Settings > Apps > Awesome Custom Fields).
1. Enable API
Enable the API by toggling the switch to 'on' on the right. If you have multiple Cascading Select fields, you can use the API for all of them.
2. Create token
After enabling the API, you’ll find a unique URL for your instance and a button to create a custom token for authentication.
3. Manage token
You can now copy the token using the icon on the left. To revoke it, click the trash can icon on the right and create a new token.
Retrieve parameters
To use the Cascading Select API you need four parameters and the actual options data
Some browsers have a bug that causes an error when copying a value. If this happens, please click next to the copy button to focus on the current window, then try copying again. Alternatively, you can manually select the text and copy it.
1. URL and token
Copy the URL and token using the buttons on the left before the input field.
2. Field Id
Navigate to the Cascading Select field you want to populate via API, click the gear icon on the right, and select 'Copy field id'. The field ID will look something like 'customfield_123456'.
3.1 Context configuration id
To retrieve the context id. Navigate to the field configuration.
Select the context you want to update the options for.
Copy the configuration id by clicking the button on the top right.
REST API documentation
See Cascading Select - Options API | FAQ: breaking changes
The API is inspired by the Atlassian Cloud field options API: https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-custom-field-options/#api-group-issue-custom-field-options
Download Cascading Select options
To retrieve the current options use “Download options“ .
POST Create Cascading Select options
Creates new Cascading Select options and returns a list of all options for a context.
Request
Header
authorization: string (token)
Query Parameters
fieldId: string requriedconfigurationId: string requried saveInStorage: boolean optional
Body
Response
200 OK
Returned if the request is successful
413 Configuration is too big
You have too many options. If you haven’t already set the saveInStorage parameter, you may try to rerun your command adding &saveInStorage=true.
Please note, that this setting won’t work with JSM
500
Please read the error message or contact support
Example
const body = {
options: [{
name: "Option 3",
children: [{
name: "Option 3.1",
children: [{
name: "Option 3.1.1"
}]
}],
}, {
optionId: "3",
name: "Option 1.1.2"
}]
}
const response = await fetch(`${url}?fieldId=${fieldId}&configurationId=${configurationId}`, {
method: "POST",
headers: {
authorization: `${token}`,
accept: "application/json",
},
body: JSON.stringify(body)
});
console.log(await response.json());
put Update Cascading Select options
Updates Cascading Select options and returns a list of all options for a context.
Due to technical restrictions, this call won’t work in a browser (https://ecosystem.atlassian.net/browse/FRGE-1434 )
Request
Header
authorization: string (token)
Query Parameters
fieldId: string requriedconfigurationId: string requried saveInStorage: boolean optional
Body
Response
200 OK
Returned if the request is successful
413 Configuration is too big
You have too many options. If you haven’t already set the saveInStorage parameter, you may try to rerun your command adding &saveInStorage=true.
Please note, that this setting won’t work with JSM
500
Please read the error message or contact support
Example
const body = {
options: [{
id: "1",
name: "Option One"
}]
}
const response = await fetch(`${url}?fieldId=${fieldId}&configurationId=${configurationId}`, {
method: "PUT",
headers: {
authorization: `${token}`,
accept: "application/json",
},
body: JSON.stringify(body)
});
console.log(await response.json());
Technical details
The API is implemented using the Forge webtrigger module, which generates a URL accessible from outside the cloud context.
It is essential to keep this URL confidential. For additional security, a token is required for authentication. Ensure this token is not committed to repositories or included in configuration files.
FAQ: breaking changes
Is there a remaining way to fetch the current configuration options?
Yes, you can download the whole configuration in the UI.
You’ll find the options in the JSON object
[{
"id": "0",
"name": "Option 1",
"children": ["2"]
}, {
"id": "1",
"name": "Option 2"
}]
Will the feature allowing manual copying of config options still be available?
Yes, see question above
Do you have exact dates that this feature will be removed?
As we wait for a release from Atlassian, we can’t tell exactly.