Custom fields
- 1 General information
- 2 Get all custom fields information
- 3 Get configuration scheme for custom field
- 4 Remove configuration scheme for custom field
- 5 Get values for custom field configuration scheme
- 6 Add values into custom field configuration scheme
- 7 Change values in custom field configuration scheme
- 8 Remove values from custom field configuration scheme
- 9 Sort custom field values alphabetically
- 10 Add custom fields
- 11 Delete custom fields
- 12 Clear custom field schemes
- 13 Add custom fields scheme
- 14 Add custom fields schemes in bulk
- 15 Update custom fields schemes
- 15.1 Parameters
- 16 Update all custom fields schemes at once
- 16.1 Parameters
- 17 Get custom fields types
- 18 Get screens where a custom field appears
- 19 Pagination
- 20 Changes
General information
All REST APIs for custom fields are ONLY available for Jira Administrators
Get all custom fields information
Method type: GET
URL: {JIRA_URL}/rest/extender/1.0/customField/all
Respons format: JSON
Example response:
{
"customFields":[
{
"issuesWithValue": 0,
"lastValueUpdate": "never", //String value when never updated
"name":"Checkboxes",
"id": 10000,
"type":"Checkboxes",
"key":"com.atlassian.jira.plugin.system.customfieldtypes:multicheckboxes"
},
{
"issuesWithValue": 900,
"lastValueUpdate": 1234567890, //timestamp value
"name":"Radio Buttons",
"id": 10001,
"type":"Radio Buttons",
"key":"com.atlassian.jira.plugin.system.customfieldtypes:radiobuttons"
},
{
"issuesWithValue": 0,
"lastValueUpdate": "never",
"name":"Select List (cascading)",
"id": 10004,
"type":"Select List (cascading)",
"key":"com.atlassian.jira.plugin.system.customfieldtypes:cascadingselect"
},
{
"issuesWithValue": 0,
"lastValueUpdate": "never",
"name":"Select List (multiple choices)",
"id": 10003,
"type":"Select List (multiple choices)",
"key":"com.atlassian.jira.plugin.system.customfieldtypes:multiselect"
},
{
"issuesWithValue": 0,
"lastValueUpdate": "never",
"name":"Select List (single choice)",
"id": 10002,
"type":"Select List (single choice)",
"key":"com.atlassian.jira.plugin.system.customfieldtypes:select"
}
],
"startAt": 0,
"total": 10,
"maxResults": 100
}
Get configuration scheme for custom field
Method type - GET
URL: {JIRA_URL}/rest/extender/1.0/customField/configScheme/field/{customFieldId}
where {customFieldId} is custom field id
Example URL: {JIRA_URL}/rest/extender/1.0/customField/configScheme/field/10003
Respons format: JSON
Example response
{
"customFieldSchemes":[
{
"name":"Default Configuration Scheme for Select List (multiple choices)",
"description":"Example description",
"id": 10104,
"associatedProjects": [],
"issueTypes": [
{
"name": "Global (all issues)",
"id": "global"
}
]
},
{
"name":"Configuration Scheme for Select List",
"description":"Example description",
"id": 10105,
"associatedProjects": [],
"issueTypes": [
{
"name": "Epic",
"id": "10000"
},
{
"name": "Task",
"id": "10002"
}
]
},
{
"name":"Another configuration scheme",,
"description":"Example description",
"id": 10106,
"associatedProjects": [
{
"name": "PB",
"id": 10001,
"key": "PB"
}
],
"issueTypes": []
}
],
"startAt": 0,
"total": 10,
"maxResults": 100
}
Remove configuration scheme for custom field
Method type - DELETE
URL: {JIRA_URL}/rest/extender/1.0/customField/removeConfigScheme/{configSchemeId}
where {configSchemeId} is custom field configuration scheme
Example URL: {JIRA_URL}/rest/extender/1.0/customField/removeConfigScheme/10102
Response format - JSON
Example response
{
"message": "config scheme '10102' deleted"
}
Get values for custom field configuration scheme
Method type - GET
URL: {JIRA_URL}/rest/extender/1.0/customField/configScheme/getValue/{configSchemeId}
where {configSchemeId} is custom field configuration scheme
Example URL: {JIRA_URL}/rest/extender/1.0/customField/configScheme/getValue/10104
Response format - JSON
Example response
Example for standard fields (Radio buttons, Select list (sings/multiple choices), Checkboxes
{
"schemeOptions":[
{
"id": 10006,
"name":"Select List (multiple choices) Value 1",
"position": 1,
"disabled": false
},
{
"id": 10007,
"name":"Select List (multiple choices) Value 2",
"postion": 2,
"disabled": true
}
],
"startAt": 0,
"total": 10,
"maxResults": 100
}
Example for cascading field (Select list (cascading))
{
"schemeOptions":[
{
"id": 10008,
"name":"Select List (cascading) Parent Value 1",
"postion": 1,
"disabled": false,
"childOptions":[
{
"parentId": 10008,
"name":"Select List (cascading) Children Parent 1 Value 1",
"postion": 1,
"id": 10010,
"disabled": false
},
{
"parentId": 10008,
"name":"Select List (cascading) Children Parent 1 Value 2",
"postion": 2,
"id": 10011,
"disabled": false
},
{
"parentId": 10008,
"name":"Select List (cascading) Children Parent 1 Value 3",
"postion": 3,
"id": 10012,
"disabled": false
}
]
},
{
"id": 10009,
"name":"Select List (cascading) Parent Value 2",
"postion": 2,
"disabled": true,
"childOptions":[
{
"parentId": 10009,
"name":"Select List (cascading) Children Parent 2 Value 1",
"postion": 1,
"id": 10013,
"disabled": false
},
{
"parentId": 10009,
"name":"Select List (cascading) Children Parent 2 Value 2",
"postion": 2,
"id": 10014,
"disabled": false
}
]
}
],
"startAt": 0,
"total": 10,
"maxResults": 100
}
Add values into custom field configuration scheme
Method type - POST
URL: {JIRA_URL}/rest/extender/1.0/customField/configScheme/addValue/{configSchemeId}
where {configSchemeId} is custom field configuration scheme
Request format - JSON
Example request
Example for one value (Single List fields)
{
"optionName": ["New option"]
}
Example for several values (Single List fields)
{
"optionName": ["New option 1", "New Option 2", "New Option 3"]
}
Example for one value (Cascading fields)
{
"parentId": 10105,
"optionName": ["New option 1"]
}
Example for several values (Cascading fields)
{
"parentId": 10105,
"optionName": ["New option 1", "New Option 2", "New Option 3"]
}
Response format - JSON
Example response
{
"message": "values 'New value 1', 'New value 2' added to 10104 config scheme id",
"status": "done"
}
{
"message": "scheme config does not exist",
"status": "done"
}
Change values in custom field configuration scheme
Method type - POST
URL: {JIRA_URL}/rest/extender/1.0/customField/configScheme/editValue/{configSchemeId}/option/{optionId}
where {configSchemeId} is custom field configuration scheme
where {optionId} is custom field value id to change
Request format - JSON
Example request
All parameters
{
"parentId": 10303,
"disabled" : true,
"name": "New name",
"position": 10
}
Disable value in field
{
"disabled" : true
}
Rename value in Cascading field
{
"parentId": 10105,
"name": "New name - child"
}
Change value position
{
"position": 14
}
parentId - optional - only used in cascading fields when you need to change the value in the second checkbox
disable - optional - (true/false) - disable or enable field value
name - optional - a new name for the value if you want to change it
position - optional - number <1, ∞) - field value position on list
Response format - JSON
Example response
{
"message": "option '10307' changed (state: enabled, name: New name, position: 1)",
"status": "done"
}
Remove values from custom field configuration scheme
Method type - POST
URL: {JIRA_URL}/rest/extender/1.0/customField/configScheme/removeValue
Request format - JSON
Example request
Example for one value
{
"optionId": [10013]
}
Example for several values
{
"optionId": [10013, 10014]
}
Response format - JSON
Example response
{
"message": "all options deleted",
"skipped": [],
"deleted": [
"10013",
"10014"
]
}
{
"message": "options deleted, some options skipped",
"skipped": [
"1001300000"
],
"deleted": []
}
Sort custom field values alphabetically
Method type - POST
1) Sorting for the first level (e.g. for select lists, radio buttons, etc.)
URL:
{JIRA_URL}/rest/extender/1.0/customField/configScheme/sortValuesAlphabetically/{configSchemeId}
where {configSchemeId} is custom field configuration scheme
2) Sorting for the second level (e.g. for a cascading select list, etc.)
URL: {JIRA_URL}/rest/extender/1.0/customField/configScheme/sortValuesAlphabetically/{configSchemeId}/parentOptionId/{parentOptionId}
where {configSchemeId} is custom field configuration scheme
where {parentOptionId} is the identifier of the field value at the first level whose values at the second level should be changed
Example response
{
"message": "done"
}
Add custom fields
Method type - PUT
URL: {JIRA_URL}/rest/extender/1.0/customField/addCustomField
Request format - JSON
Example request (all parameters)
{
"fieldName": "FIELD NAME",
"fieldDescription": "FIELD DESCRIPTION",
"fieldTypeKey": "FIELD TYPE KEY",
"schemeName": "FIELD CONFIG SCHEME NAME",
"schemeDescription": "FIELD CONFIG SCHEME DESCRIPTION",
"issueTypes": ["ISSUE_TYPE_NAME", "ISSUE_TYPE_ID"],
"projects": ["PROJECT_KEY", "PROJECT_ID"],
"optionNames": ["OPTION_A", "OPTION_B"]
}
fieldName - required
fieldDescription - required
fieldTypeKey - required - uniq field type key; you can get all keys from Get custom fields types
schemeName - optional - custom field configuration scheme name - default value ("Default Configuration Scheme for {CUSTOM_FIELD_NAME}")
schemeDescription - optional - custom field configuration scheme description - default value ("Default configuration scheme generated by Extender for JIRA")
issueTypes - optional - issue types for field context - default value ("Global (all issues)")
projects - optional - project for field context - default value (all projects)
optionNames - optional - adding options to the field if they are supported
Response format - JSON
Example response
{
"customFieldId": "customfield_10008",
"configSchemeId": 10109,
"message": "custom field 'Field3' created"
}
Delete custom fields
Deleting several custom fields at once can take a long time or slow down the application
Method type - DELETE
URL: {JIRA_URL}/rest/extender/1.0/customField/deleteCustomField
Request format - JSON
Example request
Example for one custom field
{
"customField": ["FELD_NAME"]
}
Example for several custom fields
{
"customField": ["FELD_NAME", "FIELD_ID"];
}
Response format - JSON
{
"message": "custom fields deleted",
"skipped": [],
"deleted": ["Field Number Two (customfield_10004)"]
}
{
"message": "custom fields deleted, some custome fields skipped",
"skipped": ["10001"],
"deleted": ["Field Number One"]
}
Clear custom field schemes
API clears configurations of contexts that do not have any project mapping (global context is skipped).
Example context that will be removed:
Method type - DELETE
URL: {JIRA_URL}/rest/extender/1.0/customField/clearConfigSchemes/{customFieldId}
where {customFieldId} is custom field id
where {customFieldId} takes the value all for all custom fields
Example URL:
{JIRA_URL}/rest/extender/1.0/customField/clearConfigSchemes/10100
{JIRA_URL}/rest/extender/1.0/customField/clearConfigSchemes/all
Remember, in the case of executing the API for all custom fields, the execution time may be significantly longer
Response format - JSON
Example response
{
"message": "custom field schemes cleared"
}
Add custom fields scheme
Method type - PUT
URL: {JIRA_URL}/rest/extender/1.0/customField/addConfigScheme/{customFieldId}
where {customFieldId} is custom field id
Request format - JSON
Example request
Example (all parameters)
{
"schemeName": "FIELD CONFIG SCHEME NAME",
"schemeDescription": "FIELD CONFIG SCHEME DESCRIPTION",
"issueTypes": ["ISSUE_TYPE_NAME", "ISSUE_TYPE_ID"],
"projects": ["PROJECT_KEY", "PROJECT_ID"]
}
schemeName - optional - custom field configuration scheme name - default value ("Default Configuration Scheme for {CUSTOM_FIELD_NAME}")
schemeDescription - optional - custom field configuration scheme description - default value ("Default configuration scheme generated by Extender for JIRA")
issueTypes - optional - issue types for field context - default value ("Global (all issues)")
projects - optional - project for field context - default value (all projects)
Response format - JSON
Example response
{
"message": "config scheme id '10100' created for field '{CUTOME_FIELD_NAME}'",
"configSchemeId": 10100
}
Add custom fields schemes in bulk
Method type - PUT
URL: {JIRA_URL}/rest/extender/1.0/customField/addConfigSchemes/{customFieldId}
where {customFieldId} is custom field id
Request format - JSON
Example request
Example (all parameters)
{
"schemeName": "FIELD CONFIG SCHEME NAME",
"schemeDescription": "FIELD CONFIG SCHEME DESCRIPTION",
"issueTypes": [
[],
["ISSUE_TYPE_NAME", "ISSUE_TYPE_ID"]
],
"projects": [
["PROJECT_KEY", "PROJECT_ID"],
["PROJECT_KEY"]
],
"optionNames": [
["OPTION_NAME_A", "OPTION_NAME_B"],
[]
]
}
schemeName - optional - custom field configuration scheme name - default value ("Default Configuration Scheme for {CUSTOM_FIELD_NAME}")
schemeDescription - optional - custom field configuration scheme description - default value ("Default configuration scheme generated by Extender for JIRA")
issueTypes - required - array containing issue types configuration arrays for all contexts - default value for empty array ("Global (all issues)")
projects - required - array containing projects configuration arrays for all contexts - default value for empty array (all projects)
optionName - required - array containing arrays with option names for all contexts - leave array empty if field does not support options
Parameters issueTypes, projects and optionNames are a set of arrays in the array and their number must be equal in each parameter. If you do not want to set issue types, projects or options for a given context, insert an empty table in this place
Response format - JSON
Example response
{
"message": "config schemes created for field '{CUTOME_FIELD_NAME}'",
}
Example API call:
Result:
Update custom fields schemes
Method type - PUT
URL: {JIRA_URL}/rest/extender/1.0/customField/updateConfigScheme/{configSchemeId}
URL: {JIRA_URL}/rest/extender/1.0/customField/updateConfigScheme/{configSchemeId}?keepExistingConfigurations=true
where {configSchemeId} is config scheme id
Request format - JSON
Example request
Example (all parameters)
{
"schemeName": "FIELD CONFIG SCHEME NAME",
"schemeDescription": "FIELD CONFIG SCHEME DESCRIPTION",
"projects": ["PROJECT_KEY", "PROJECT_ID"],
"issueTypes": ["ISSUETYPE_ID_1", "ISSUETYPE_ID_2"]
}
schemeName - optional - custom field configuration scheme name - default value ("Default Configuration Scheme for {CUSTOM_FIELD_NAME}")
schemeDescription - optional - custom field configuration scheme description - default value ("Default configuration scheme generated by Extender for JIRA")
projects - optional - project for field context
Request without this parameter - API skips changes in project contexts
Request with empty array - API clear project contexts (set global for all project)
Request with non empty array and param keepExistingConfigurations - API will add the indicated projects to the existing configuration of project contexts
Request with non empty array and without param keepExistingConfigurations - API will overwrite the configuration only with the selected projects
issueTypes - optional - project for field context
Request without this parameter - API skips changes in issue type contexts
Request with empty array - API clear issue type contexts (set global for all project)
Request with non empty array and param keepExistingConfigurations - API will add the indicated issue types to the existing configuration of issue type contexts
Request with non empty array and without param keepExistingConfigurations - API will overwrite the configuration only with the selected issue types
Response format - JSON
Example response
{
"message": "config scheme id '10100' was changed"
}
Parameters
keepExistingConfigurations - optional - (true or empty) - sets the API working mode, whether new projects and request types are to be added to the current configuration or replaced
Update all custom fields schemes at once
Note, this api changes all contexts that are defined on the custom field, if you want to change only one particular we suggest using API Update custom fields schemes
Method type - PUT
URL: {JIRA_URL}/rest/extender/1.0/updateAllConfigSchemes/field/{customFieldId}
URL: {JIRA_URL}/rest/extender/1.0/updateAllConfigSchemes/field/{customFieldId}?keepExistingConfigurations=true
where {customFieldId} is custom field id
Request format - JSON
Example request
Example (all parameters)
{
"schemeName": "FIELD CONFIG SCHEME NAME",
"schemeDescription": "FIELD CONFIG SCHEME DESCRIPTION",
"projects": ["PROJECT_KEY", "PROJECT_ID"],
"issueTypes": ["ISSUETYPE_ID_1", "ISSUETYPE_ID_2"]
}
schemeName - optional - custom field configuration scheme name - default value ("Default Configuration Scheme for {CUSTOM_FIELD_NAME}")
schemeDescription - optional - custom field configuration scheme description - default value ("Default configuration scheme generated by Extender for JIRA")
projects - optional - project for field context
Request without this parameter - API skips changes in project contexts
Request with empty array - API clear project contexts (set global for all project)
Request with non empty array and param keepExistingConfigurations - API will add the indicated projects to the existing configuration of project contexts
Request with non empty array and without param keepExistingConfigurations - API will overwrite the configuration only with the selected projects
issueTypes - optional - project for field context
Request without this parameter - API skips changes in issue type contexts
Request with empty array - API clear issue type contexts (set global for all project)
Request with non empty array and param keepExistingConfigurations - API will add the indicated issue types to the existing configuration of issue type contexts
Request with non empty array and without param keepExistingConfigurations - API will overwrite the configuration only with the selected issue types
Response format - JSON
Example response
{
"message": "config schemes with id 10000, 10001 have been changed"
}
Parameters
keepExistingConfigurations - optional - (true or empty) - sets the API working mode, whether new projects and request types are to be added to the current configuration or replaced
Get custom fields types
Method type - GET
URL: {JIRA_URL}/rest/extender/1.0/customField/customFieldTypes
Response format - JSON
Example response
{
"customFieldTypes": [
{
"name": "Approvals",
"description": "Provides search options for Jira Service Management approvals information. This custom field is created programmatically and required by Jira Service Management.",
"descriptorKey": "sd-approvals",
"key": "com.atlassian.servicedesk.approvals-plugin:sd-approvals",
},
{
"name": "Bug Import Id",
"description": "A read-only custom field that points back to the previously imported bug id.",
"descriptorKey": "bug-importid",
"key": "com.atlassian.jira.plugins.jira-importers-plugin:bug-importid",
},
{
"name": "Checkboxes",
"description": "Choose multiple values using checkboxes.",
"descriptorKey": "multicheckboxes",
"key": "com.atlassian.jira.plugin.system.customfieldtypes:multicheckboxes",
}
]
}
Get screens where a custom field appears
Method type - GET
URL: {JIRA_URL}/rest/extender/1.0/customField/screen/field/{customFieldId}
where {customFieldId} is custom field id
Example URL: {JIRA_URL}/rest/extender/1.0/customField/screen/field/10118
Respons format: JSON
Example response
{
"screens": [
{
"tabId": 11407,
"tabName": "Default",
"name": "AANCSA: Jira Service Management: Problem Create Issue Screen",
"description": "",
"tabPosition": 0,
"id": 11207
},
{
"tabId": 11408,
"tabName": "Default",
"name": "AANCSA: Jira Service Management: Problem View/Edit Screen",
"description": "",
"tabPosition": 0,
"id": 11208
},
{
"tabId": 11920,
"tabName": "Default",
"name": "AAYTSA: Jira Service Management: Problem Create Issue Screen",
"description": "",
"tabPosition": 0,
"id": 11720
}
],
"startAt": 0,
"total": 3,
"maxResults": 100
}
Pagination
This REST API uses pagination to improve performance for all Jira users. Pagination is enforced for methods that could return a large collection of items. When you make a request to a paged API, the response will wrap the returned array of values in a JSON object with paging metadata, for example:
{
"startAt" : 0,
"maxResults" : 10,
"total": 200,
"boards": [
{ /* result 0 */ },
{ /* result 1 */ },
{ /* result 2 */ }
]
}
Where:
startAt
is the index of the first item returned in the page of results.maxResults
is the maximum number of items that can be returned per page. Each API endpoint may have a different limit for the number of items returned, and these limits may change without notice. (default value - 1000)total
is the total number of items contained in all pages. This number may change as the client requests the subsequent pages, therefore the client should always assume that the requested page can be empty.
Changes
Since v. 1.1.1
Get values for custom field configuration scheme - added flag “disabled” (true/false) for options
Since v. 1.5.0
New API - Delete custom fields
Since v. 1.6.0
New APIs - Add custom fields, Add custom fields schemes, Update custom fields schemes, Get custom fields types
Since v. 1.65.*
Get all custom fields informations - added “lastValueUpdate” and “issuesWithValue” value for Jira Data Center >= 8.16
Since v. 1.7.2
Get configuration scheme for custom field - added value “associatedProjects” and "issueTypes" for config scheme
Since v. 1.7.3
New API - Remove configuration scheme for custom field
Since v. 2.20.*
New API - Change values in custom field configuration scheme
Get values for custom field configuration scheme - added “position” value
Get all custom fields informations - added “description” value
Get configuration scheme for custom field - added “description” value
Get custom fields types - added “descriptorKey” value
Some fields in the JSON request / response in all APIs have been changed
id
(string) →id
(integer)id
for issue typesGlobal (all issues)
→global
(string)parent_id
(string) →parentId
(integer)disabled
(string) →disabled
(boolean)parentOptionId
(string) →parentId
(integer)configSchemeId
(string) →configSchemeId
(integer)
Since v. 4.2.*
Update custom fields schemes - changes in the functioning of the API and minor extensions
Since v. 4.4.*
New API - Update all custom fields schemes at once
Since v. 4.8.*
New API - Clear custom field schemes
New API - Add custom fields schemes in bulk
Added support for a new parameter optionNames in the API - Add custom fields scheme
Since v. 4.17.*
Added pagination to all GET methods
Since v. 5.4.*
New API - Get screens where a custom field appears
Since v. 5.6.*
New API - Sort custom field values alphabetically