YouTrack Standalone 2018.3 Help

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, POST

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. If empty, new value set will be created

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, POST, DELETE

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 let's you retrieve a list of supported types of custom fields.

Resource

api/admin/customFieldSettings/types

Supported methods

GET

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: 12 October 2018