The app provides a set of REST Endpoints to perform operations such as add new customfield option value or set default value for the supported field types.
Rest API Explorer
With app version 1.2 we introduced the REST API Explorer which will help you to send REST requests to the API directly in the browser. This Screencast will show you how to use REST API Explorer:
Intoduction to REST API Explorer
Rest API Endpoint Documentation
This is the static documentation for the Customfield Editor for Jira's REST-API.
The baseUrl of the REST API might be one of the following URLs on your instance of Jira:
List all customfields [c1.3.0] /admin/customfields
List all available customfields. Not all of them will be editable with the Customfield Editor for Jira. See User Guide for supported FieldTypes. You need to be administrator or system administrator to use this endpoint.
Version History
New in 1.2
Changed in 1.3.0 Internal change so that normal admins can use endpoint too. Before only system administrators could use it.
Get global Permissions for Customfield [c1.3.0] /admin/customfields/{customFieldId}
You can get permissions of the specified customfield. Will return usernames and groupnames that have permission. You need to be administrator or system administrator to use this endpoint.
Version History
New in 1.2
Changed in 1.3.0 Internal change so that normal admins can use endpoint too. Before only system administrators could use it.
Set global Permissions on Customfield [c1.3.0] /admin/customfields/{customFieldId}
You can submit usernames or groupnames to give permissions on the specified customfield. Notice: Always provide the full list of usernames and groupnames! You cannot just add a username, what you submit will overwrite the previous values of usernames and groupnames fields. You need to be administrator or system administrator to use this endpoint.
Version History
New in 1.2
Changed in 1.3.0 Internal change so that normal admins can use endpoint too. Before only system administrators could use it.
Get all contexts of Customfield [c1.5.0] /admin/customfields/{customFieldId}/contexts
You can get all contexts of a customfield.
You can set the optional Query-Parameter ?expand=projects to get information on associated projects. You could also set ?expand=issueTypes to get information on associated issue types. Or set ?expand=projects,issueTypes to get information on both associated projects and issue types. Note that the containers will only show up when the corresponding expand parameter is set. See examples of all expand variants in issue CEP-31. When the expand parameter is not set the response will look like this:
Get all context permissions of Customfield [c1.3.0] /admin/customfields/{customFieldId}/contexts/permissions
You can get permissions of the specified customfield for each context. Will return usernames and groupnames that have permission for every context. Notice: If a user has global permissions on a field all context specific permissions will be overruled. You need to be administrator or system administrator to use this endpoint.
Version History
New in 1.2.1
Changed in 1.3.0 Internal change so that normal admins can use endpoint too. Before only system administrators could use it.
Set context permissions on Customfield [c1.3.0] /admin/customfields/{customFieldId}/contexts/permissions
You can submit usernames or groupnames to give permissions on the specified customfield contexts. Notice: If a user has global permissions on a field all context specific permissions will be overruled. Notice: Always provide the full list since it will get overwritten! You need to be administrator or system administrator to use this endpoint.
Version History
New in 1.2.1
Changed in 1.3.0 Internal change so that normal admins can use endpoint too. Before only system administrators could use it.
Lists all customfields the user has permission for [n1.2] /user/customfields
List all customfields accessable by the authenticated user. (Administrator needs to give the user permission first. Even jira-administrators need to be given permission)
List contexts of customfield [c1.5.0] /user/customfields/{customFieldId}/contexts
List all contexts and other information for customfield.
You can set the optional Query-Parameter ?expand=projects to get information on associated projects. You could also set ?expand=issueTypes to get information on associated issue types. Or set ?expand=projects,issueTypes to get information on both associated projects and issue types. Note that the containers will only show up when the corresponding expand parameter is set. See examples of all expand variants in issue CEP-31. When the expand parameter is not set the response will look like this:
Changed in 1.5.0 Added the expand Query-Parameter for projects and issueTypes.
Changed in 1.2.1 The contexts returned are filtered by context permissions now. If there are no context permissions set, you will still see all contexts.
Lists all options of the customfield for default context [c1.2] /user/customfields/{customFieldId}/contexts/default/options
list all options of a customfield for default context.
Version History
New in 1.1
Changed in 1.2 URL changed from /customfieldoptions/{customFieldId}. childOptions is no longer returned. Use special childOptions Endpoint to retrieve childOptions for cascadingSelect FieldType.
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
Creates a new option for the customfield in default context [c1.2] /user/customfields/{customFieldId}/contexts/default/options
Creates a new option for the customfield in default context .
When creating a new option try using the following and do not set sequence and id!
{ "optionvalue": "my option value" }
Version History
New in 1.1
Changed in 1.2 URL changed from /customfieldoption/{customFieldId} Request and Response Parameters/Schema mostly unchanged. childOptions removed. sequence is ignored; new options are always placed at the end of the list.
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
RestfulTableMoveModel is used for drag-and-drop sorting options using the AUI Restfultable. It is advised to not use it. Use the SORT Endpoint instead or you might break the internal order sequence.
After must contain the optionId to move the option after. In form of "/foo/bar/{optionid}" which is provided that way by AUI Restfultable.You can provide just the optionId too.
position
string
Special Case to move an option to the beginning of the option List. Specify position="First". (Notice: if after and position are defined together, after is ignored)
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
CustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
Property
Type
Description
optionvalue
string
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
defaultChildOption
object
CustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
Property
Type
Description
optionvalue
string
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
defaultOptions
array
The IDs and names of the options as default values. (null for fieldtypes other than multiselect or multicheckboxes)
array ofobject
Property
Type
Description
optionvalue
string
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
CustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
Property
Type
Description
optionvalue
string
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
defaultChildOption
object
CustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
Property
Type
Description
optionvalue
string
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
defaultOptions
array
The IDs and names of the options as default values. (null for fieldtypes other than multiselect or multicheckboxes)
array ofobject
Property
Type
Description
optionvalue
string
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
SortModel specifies in which way to sort the options of a customfield.You can sort ascending or descending. The sorting will be locale dependant, so you need to specify a locale like en-US. You can specify an optional collator strength.
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
RestfulTableMoveModel is used for drag-and-drop sorting options using the AUI Restfultable. It is advised to not use it. Use the SORT Endpoint instead or you might break the internal order sequence.
After must contain the optionId to move the option after. In form of "/foo/bar/{optionid}" which is provided that way by AUI Restfultable.You can provide just the optionId too.
position
string
Special Case to move an option to the beginning of the option List. Specify position="First". (Notice: if after and position are defined together, after is ignored)
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
CustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
Property
Type
Description
optionvalue
string
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
defaultChildOption
object
CustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
Property
Type
Description
optionvalue
string
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
defaultOptions
array
The IDs and names of the options as default values. (null for fieldtypes other than multiselect or multicheckboxes)
array ofobject
Property
Type
Description
optionvalue
string
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
CustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
Property
Type
Description
optionvalue
string
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
defaultChildOption
object
CustomFieldOptionModel represents all properties of an option.The id, value, order (sequence) and disabled/enabled state.
object
Property
Type
Description
optionvalue
string
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
defaultOptions
array
The IDs and names of the options as default values. (null for fieldtypes other than multiselect or multicheckboxes)
array ofobject
Property
Type
Description
optionvalue
string
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
SortModel specifies in which way to sort the options of a customfield.You can sort ascending or descending. The sorting will be locale dependant, so you need to specify a locale like en-US. You can specify an optional collator strength.
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
Creates a new child-option of a parent-option in default context [c1.2] /user/customfields/{customFieldId}/contexts/default/options/{optionId}/childoptions
This feature is only available for the customfield type Cascading Select Field.
Creates a new child-option of a parent-option for the customfield in default context.
When creating a new option try using the following and do not set sequence and id!
{ "optionvalue": "my option value" }
Version History
New in 1.1
Changed in 1.2 URL changed from /customfieldchildoption/{customfieldid}/{parentoptionid} Request and Response Parameters/Schema unchanged.
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
Updates an existing child-option of a parent-option in default context [c1.2] /user/customfields/{customFieldId}/contexts/default/options/{optionId}/childoptions/{childOptionId}
This feature is only available for the customfield type Cascading Select Field.
Updates the value of an existing child-option of a parent-option for the customfield in default context.
When updating an existing option try using the following and do not set sequence!
{ "id": 1, "optionvalue": "my option value" }
Version History
New in 1.1
Changed in 1.2 URL changed from /customfieldchildoption/{customfieldid}/{parentoptionid} Request and Response Parameters/Schema unchanged.
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
Deletes a child-option of a parent-option in default context [c1.2] /user/customfields/{customFieldId}/contexts/default/options/{optionId}/childoptions/{childOptionId}
This feature is only available for the customfield type Cascading Select Field.
Deletes a child-option of a parent-option of the customfield by its id in default context.
Version History
New in 1.1
Changed in 1.2 URL changed from /customfieldchildoption/{customfieldid}/{parentoptionid} Request and Response Parameters/Schema unchanged.
Moves the child-option of the parent-option in default context [c1.2] /user/customfields/{customFieldId}/contexts/default/options/{optionId}/childoptions/{childOptionId}/move
This feature is only available for the customfield type Cascading Select Field.
Change order for existing child-option of parent-option of customfield depending on values of RestfulTableMoveModel in default context.
Version History
New in 1.1
Changed in 1.2 URL changed from /customfieldchildoption/{customfieldid}/{parentoptionid}/move Request and Response Parameters/Schema unchanged.
RestfulTableMoveModel is used for drag-and-drop sorting options using the AUI Restfultable. It is advised to not use it. Use the SORT Endpoint instead or you might break the internal order sequence.
After must contain the optionId to move the option after. In form of "/foo/bar/{optionid}" which is provided that way by AUI Restfultable.You can provide just the optionId too.
position
string
Special Case to move an option to the beginning of the option List. Specify position="First". (Notice: if after and position are defined together, after is ignored)
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
Sorts the child-options of a parent-option for the customfield in default context [n1.2] /user/customfields/{customFieldId}/contexts/default/options/{optionId}/childoptions/sort
This feature is only available for the customfield type Cascading Select Field.
Sorts the child-options of a parent-option for the customfield in default context.
SortModel specifies in which way to sort the options of a customfield.You can sort ascending or descending. The sorting will be locale dependant, so you need to specify a locale like en-US. You can specify an optional collator strength.
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
Lists child-options of parent-option for specific context [n1.2] /user/customfields/{customFieldId}/contexts/{contextId}/options/{optionId}/childoptions
This feature is only available for the customfield type Cascading Select Field.
Lists child-options of parent-option for specific context.
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
Creates a new child-option of a parent-option in specific context [n1.2] /user/customfields/{customFieldId}/contexts/{contextId}/options/{optionId}/childoptions
This feature is only available for the customfield type Cascading Select Field.
Creates a new child-option of a parent-option for the customfield in default context.
When creating a new option try using the following and do not set sequence and id!
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
Updates an existing child-option of a parent-option for specific context [n1.2] /user/customfields/{customFieldId}/contexts/{contextId}/options/{optionId}/childoptions/{childOptionId}
This feature is only available for the customfield type Cascading Select Field.
Updates the value of an existing child-option of a parent-option for the customfield.
When updating an existing option try using the following and do not set sequence!
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
Deletes a child-option of a parent-option in specific context [n1.2] /user/customfields/{customFieldId}/contexts/{contextId}/options/{optionId}/childoptions/{childOptionId}
This feature is only available for the customfield type Cascading Select Field.
Deletes a child-option of a parent-option of the customfield by its id in specific context.
Moves the child-option of the parent-option in specific context [n1.2] /user/customfields/{customFieldId}/contexts/{contextId}/options/{optionId}/childoptions/{childOptionId}/move
This feature is only available for the customfield type Cascading Select Field.
Change order for existing child-option of parent-option of customfield depending on values of RestfulTableMoveModel in specific context.
RestfulTableMoveModel is used for drag-and-drop sorting options using the AUI Restfultable. It is advised to not use it. Use the SORT Endpoint instead or you might break the internal order sequence.
After must contain the optionId to move the option after. In form of "/foo/bar/{optionid}" which is provided that way by AUI Restfultable.You can provide just the optionId too.
position
string
Special Case to move an option to the beginning of the option List. Specify position="First". (Notice: if after and position are defined together, after is ignored)
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
Sorts the child-options of a parent-option for the customfield in specific context [n1.2] /user/customfields/{customFieldId}/contexts/{contextId}/options/{optionId}/childoptions/sort
This feature is only available for the customfield type Cascading Select Field.
Sorts the child-options of a parent-option for the customfield in specific context.
SortModel specifies in which way to sort the options of a customfield.You can sort ascending or descending. The sorting will be locale dependant, so you need to specify a locale like en-US. You can specify an optional collator strength.
The actual optionValue which is displayed to the user who uses the customField.
id
integer
The unique optionId.
sequence
integer
The OPTIONAL internal sequence. It is best to leave this value blank and let the plugin choose the right sequence. You can damage the sort-order by setting wrong values here. Use the SORT Endpoint instead, if you want to sort options.
disabled
boolean
The OPTIONAL disabled state. Defaults to false. If set to true, option is disabled and will not be displayed to the user when using the field in an Jira issue.
The REST API changes from time to time. We try to keep these changes as minimal as possible, but at some point technical debt needs to be dealt with. See in the version sections below which changes made to the API on the respective app version:
v1.5.0 to v1.7.1
No breaking changes.
v1.4.0 to v1.5.0
Breaking changes!
breaking:
[CEP-36] Rest-API: All Endpoints will return HTTP 403 instead of HTTP 500 on non existing custom field id.
non-breaking:
[CEP-31] Rest-API: Provide associated projects and issue types info for /*/customfields/{id}/contexts Endpoint.
v1.3.0 to v1.4.0
No breaking changes.
v1.2.3 to v1.3.0
No breaking changes.
breaking:
-
non-breaking:
[CEP-INT-8] base url is now /1/ not /1.2/ anymore. But will be backwards compatible. Please use /rest/jiracustomfieldeditorplugin/1/* as base URL now.
[CEP-INT-8] removed the "/1.1/ Compatibility Mode" completely. Please use /rest/jiracustomfieldeditorplugin/1/* as base URL now.
[CEP-12] added /extended Endpoints for admin context permissions that display users fullname in userlists.
v1.2.2 to v1.2.3
No breaking changes.
v1.2.1 to v1.2.2
No breaking changes.
v1.2.0 to v1.2.1
You don't really need to do anything. Everything should work as before since it is just a bugfixing release which also brings the new context security feature. See the administrator guide for more details.
v1.0.0/1.1.0 to v1.2.0
You are advised to migrate to the new v1.2 URLs but you can use the v1.1 compatibility mode until you fully migrated. Here are the changes to the API from v1.1 to v1.2:
new baseUrl (with version /1.2/)
the URL pattern changed for all endpoints. See the the above REST-API-Endpoint-Documentation.
CustomFieldId is now Long(1234) not String(customfield_1234) anymore.
childOptions are removed from GET Options Resource response. Use separate Request on GET childOptions Resource now.
XML Support is removed completely. Use JSON as body-payload instead.
Error Responses are a little different and there are more distinct Response codes. See the the above REST-API-Endpoint-Documentation for all details.
Added Support for Field Contexts (with contextIDs or defaultContext).
Added alphabetical Sorting Endpoint for Options and childOptions.
Added Setting of default Value Endpoint.
Added a REST API Explorer on URL http://server:port/jira/plugins/servlet/customfieldeditorplugin/restapi/. You can trigger API Calls to the API directly in the Browser
Added admin Endpoints to set permissions and list customfields (for jira-administrator only)
CORS (Cross-Origin Resource Sharing)
CORS is not provided by the app itself. You need to configure CORS to your needs in the Webserver (Nginx or Apache Webserver) that sits in front of Jira.
Note: codeclou does not recommend you to configure CORS in a specific way. You should consult a specalist to configure CORS to your needs. The config below is provided without any warranty
<VirtualHost *:80>ServerName api-proxy.codeclou.io
## SSL => You should use SSL in production#SSLEngine on#SSLCertificateKeyFile /etc/ssl.key/example.com.key#SSLCertificateFile /etc/ssl.crt/example.com.crt## CORS HeaderHeader always set Access-Control-Allow-Origin "*"Header always set Access-Control-Allow-Methods "POST, GET, OPTIONS, DELETE, PUT"Header always set Access-Control-Allow-Headers "x-requested-with, Content-Type, origin, authorization, accept, client-security-token"## Handle HTTP Options Preflight Request always with 200RewriteEngineOnRewriteCond%{REQUEST_METHOD} OPTIONS
RewriteRule ^(.*)$ $1 [R=200,L]## Proxy CEP REST Uris to Jira Server<LocationMatch "/rest/jiracustomfieldeditorplugin/1">ProxyPass http://jira-server:8080/rest/jiracustomfieldeditorplugin/1 disablereuse=OnProxyPassReverse http:///jira-server:8080/rest/jiracustomfieldeditorplugin/1
</LocationMatch></VirtualHost>
Use this demo config for NGINX v1+ to handle HTTP Options Preflight Requests and set correct CORS headers. Note that you still should abide Integrating Jira with Nginx.
nginx.conf
server {
listen api-proxy.codeclou.io:80;
server_name api-proxy.codeclou.io;
## SSL => You should use SSL in production#ssl_certificate www.example.com.crt;#ssl_certificate_key www.example.com.key;#ssl_protocols TLSv1 TLSv1.1 TLSv1.2;#ssl_ciphers HIGH:!aNULL:!MD5;location /rest/jiracustomfieldeditorplugin/1 {
## CORS Headeradd_header'Access-Control-Allow-Origin''*' always;
add_header'Access-Control-Allow-Methods''GET, POST, PUT, DELETE, OPTIONS' always;
add_header'Access-Control-Allow-Headers''x-requested-with, Content-Type, origin, authorization, accept, client-security-token' always;
## Handle HTTP Options Preflight Request always with 200if ($request_method = 'OPTIONS') {
return200;
}
## Proxy CEP REST Uris to Jira Serverproxy_pass http://jira-server:8080/rest/jiracustomfieldeditorplugin/1;
}
}
Now you can test your CORS config. The HTTP Options Preflight Request should have the following CORS Headers: