Custom Field Settings

This resource lets you manage the custom fields in the system.

System Custom Fields Settings

Resource	`api/admin/customFieldSettings/customFields`
Returned entity	CustomField. For details, see the Supported Fields section.
Supported methods	`GET`: read a list of available custom fields. `POST`: create a custom field.

Supported Fields

The following table describes all attributes of the CustomField entity.

Field	Type	Description
id	String	Unique ID of the custom field.
name	String	The name of a custom field.
fieldType	FieldType	Type of a custom field.
isDisplayedInIssueList	Boolean	True if field is visible in the Issues list by default
isAutoAttached	Boolean	If field should be automatically attached new projects
isPublic	Boolean	If true, then Read Issue/Update Issue permissions are required for updating field value, otherwise Private Read Issue/Private Update Issue are required.
ordinal	Integer	Used for fields reordering
localizedName	String?	If set, used for field presentation in UI
aliases	String?	A comma-separated list of aliases that can be used in search and commands
fieldDefaults	CustomFieldDefaults	Default project-related settings for the custom field. May contain different values for different for custom fields of different types
instances	Iterable<ProjectCustomField>	Project-related settings. May contain different values for custom fields of different types

Fields for fieldDefaults

Field	Type	Description
canBeEmpty	Boolean	If field can have empty values
emptyFieldText	String?	Label that would be shown for empty field
bundle	Bundle	Set of values that will be used for this field.
defaultValues	Iterable<ValueType>	Initial field values

Get a List of Custom Fields

Request syntax

GET /api/admin/customFieldSettings/customFields[?{fields}&{$top}&{$skip}

Request parameters

Parameter	Type	Description
fields	string	A list of project attributes that should be returned in the response. If no fields specified, only entityID is returned.
$skip	int	Optional. Lets you set a number of returned entities to skip before returning the first one.
$top	int	Optional. Lets you specify the maximum number of entries that are returned in the response.

Sample request

curl -X GET \
'https://example.myjetbrains.com/youtrack/api/admin/customFieldSettings/customFields?fields=id,name,fieldType%28presentation,id%29&$top=2' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json'

Sample response body

[
    {
        "fieldType": {
            "presentation": "ownedField[1]",
            "id": "ownedField[1]"
        },
        "name": "Subsystem",
        "id": "58-0"
    },
    {
        "fieldType": {
            "presentation": "enum[1]",
            "id": "enum[1]"
        },
        "name": "Priority",
        "id": "58-1"
    }
]

Create a Custom Field

Request syntax

POST /api/admin/customFieldSettings/customFields[?{fields}

Request parameters

Parameter	Type	Description
fields	string	A list of project attributes that should be returned in the response. If no fields specified, only entityID is returned.

Sample request

Let's create a custom field of enumeration type, with the name "Severity". It should be a single value field, public, displayed on the Issues list, and not attached automatically to projects.

curl -X POST \
'https://example.myjetbrains.com/youtrack/api/admin/customFieldSettings/customFields?fields=id,name,fieldType%28presentation,id%29' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json'\
-d '{
"fieldType": {"id":"enum[1]"},
"name" : "Severity",
"isDisplayedInIssueList":true,
"isAutoAttached":false,
"isPublic":true
}'

Operations with a Custom Field

This resource lets you operate a custom field with a specific ID.

Resource	`api/admin/customFieldSettings/customFields/<fieldID>`
Returned entity	CustomField. For details, see the Supported Fields section.
Supported methods	`GET`: reat a specific custom field. `POST`: update a specific custom field. `DELETE`: delete a specific custom field.

Get a Specific Custom Field

Get a custom field with the specified id.

Request syntax

GET /api/admin/customFieldSettings/customFields/<fieldID>[?{fields}]

request parameters

Parameter	Type	Description
fieldID	string	An entity ID of the custom field to get.
fields	string	A list of project attributes that should be returned in the response. If no fields specified, only entityID is returned.

Request sample

curl -X GET \
'https://example.myjetbrains.com/youtrack/api/admin/customFieldSettings/customFields/58-5?fields=id,name,fieldType%28id%29,fieldDefaults%28canBeEmpty,emptyFieldText,bundle%28id,name%29%29' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json'

Response body sample

{
    "fieldType": {
        "id": "version[*]"
    },
    "fieldDefaults": {
        "defaultValues": [],
        "bundle": {
            "name": "Versions",
            "id": "71-0",
            "$type": "jetbrains.charisma.customfields.complex.version.VersionBundle"
        },
        "canBeEmpty": true,
        "emptyFieldText": "Unscheduled",
        "$type": "jetbrains.charisma.customfields.complex.version.VersionBundleCustomFieldDefaults"
    },
    "name": "Fix versions",
    "id": "58-5"
}

Update a Specific Custom Field

Update a custom field with the specified id.

Request

POST /api/admin/customFieldSettings/customFields/<fieldID>[?{fields}]

Request parameters

Parameter	Type	Description
fieldID	string	An entity ID of the custom field to update.
fields	string	A list of project attributes that should be returned in the response. If no fields specified, only entityID is returned.

Request sample

curl -X POST \
'https://example.myjetbrains.com/youtrack/api/admin/customFieldSettings/customFields/58-5?fields=id,name,fieldType%28id%29,fieldDefaults%28canBeEmpty,emptyFieldText,bundle%28id,name%29%29' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{"fieldDefaults": { "emptyFieldText": "No version" } }'

Delete Specific Custom Field

Delete a custom field with the specified id.

Request syntax

DELETE /api/admin/customFieldSettings/customFields/<fieldID>

Request parameters

Parameter	Type	Description
fieldID	string	An entity ID of the custom field to delete.

Request sample

curl -X DELETE \
https://example.myjetbrains.com/youtrack/api/admin/customFieldSettings/customFields/58-9 \
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json'

Response body sample

For a DELETE method, you get a response with the status (200 OK, for a successful request) and an empty body.

Custom Field Types

A read-only resource that lets you retrieve a list of supported types of custom fields.

Resource	`api/admin/customFieldSettings/types`
Supported methods	`GET`: read a list of supported types of custom fields.

Fields

Field	Type	Description
id	String	Unique ID of a custom field type.
presentation	String	How the type name is shown in the UI.
isMultiValue	Boolean	True if field of this type can store several values.
valueType	String	Type of values for a custom field type.

Read Available Types of Custom Fields

Get the list of field types.

Request syntax

GET /api/admin/customFieldSettings/types[?{fields}&{$top}&{$skip}

Request parameters

Parameter	Type	Description
fields	string	A list of project attributes that should be returned in the response. If no fields specified, only entityID is returned.
$skip	int	Optional. Lets you set a number of returned entities to skip before returning the first one.
$top	int	Optional. Lets you specify the maximum number of entries that are returned in the response.

Request sample

curl -X GET \
'https://example.myjetbrains.com/youtrack/api/admin/customFieldSettings/types?fields=id,presentation,isMultiValue,valueType&$skip=4&$top=3' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json'

Response body sample

In accordance with the sample request, this response body contains 3 found entities ($top =3) starting with the fifth consequtive found entity ($skip=4).

[
    {
        "valueType": "string",
        "presentation": "string",
        "isMultiValue": false,
        "id": "string"
    },
    {
        "valueType": "float",
        "presentation": "float",
        "isMultiValue": false,
        "id": "float"
    },
    {
        "valueType": "group",
        "presentation": "group[1]",
        "isMultiValue": false,
        "id": "group[1]"
    }
]

Last modified: 7 March 2019