Creating a local queue field

Written by

Updated at February 19, 2024

Request format
Response format

Use this request to create a local issue field linked to a given queue.

Request format

Before making the request, get permission to access the API.

To create a local field, use an HTTP POST request. Request parameters are provided in the request body in JSON format:

POST /v2/queues/<queue_id_or_key>/localFields
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID: <organization ID>

{
    "name":
    {
        "en": "Name in English",
        "ru": "Name in Russian"
    },
    "id": "loc_field_key",
    "category": "0000000000000003********",
    "type": "ru.yandex.startrek.core.fields.StringFieldType"
}

Headers

Host

Address of the node that provides the API:
```
https://api.tracker.yandex.net
```
Authorization

OAuth token in OAuth <OAuth_token> format, e.g.:
```
OAuth 0c4181a7c2cf4521964a72ff********
```
X-Org-ID or X-Cloud-Org-ID

Organization ID. You can find it out on the Tracker organizations page.
- If a Yandex 360 for Business organization is the only one linked to Tracker, the X-Org-ID header is used.
- If a Yandex Cloud Organization organization is the only one linked to Tracker, the X-Cloud-Org-ID header is used.
- If both Yandex 360 for Business and Yandex Cloud Organization organizations are linked to Tracker at the same time, the X-Org-ID header and the Yandex 360 for Business organization ID are used.

Resource

Parameter	Description	Data type
<queue_ID_or_key>	Queue ID or key. The queue key is case-sensitive.	String

Request body parameters

Required parameters

Parameter	Description	Data type
name	Local field name `en`: In English `ru`: In Russian	String
id	Local field ID.	String
category	Object with information about the field category. To get a list of all categories, use the HTTP request: `GET /v2/fields/categories`	String
type	Local field type: `ru.yandex.startrek.core.fields.DateFieldType`: Date `ru.yandex.startrek.core.fields.DateTimeFieldType`: Date/time `ru.yandex.startrek.core.fields.StringFieldType`: One-line text field `ru.yandex.startrek.core.fields.TextFieldType`: Multi-line text field `ru.yandex.startrek.core.fields.FloatFieldType`: Fractional number `ru.yandex.startrek.core.fields.IntegerFieldType`: Integer `ru.yandex.startrek.core.fields.UserFieldType`: User's name `ru.yandex.startrek.core.fields.UriFieldType`: Link	String

Additional parameters

Parameter	Description	Data type
optionsProvider	Object with information about the list items	Object
order	Sequence number in the list of organization fields: https://tracker.yandex.com/admin/fields	Number
description	Local field description	String
readonly	Shows if the field value is editable: `true`: Non-editable `false`: Editable	Logical
visible	Indicates if the field is visible in the interface: `true`: Always visible `false`: Not visible	Logical
hidden	Indicates if the field should be hidden in the interface: `true`: Hide the field even if it is not empty `false`: Do not hide the field	Logical
container	Indicates if you can specify multiple values in the field (like in the Tags field): `true`: You can specify multiple values in the field `false`: You can only specify one value in the field This parameter can be used for the following types of fields: `ru.yandex.startrek.core.fields.StringFieldType`: One-line text field `ru.yandex.startrek.core.fields.UserFieldType`: User's name Drop-down list (see the `optionsProvider` description)	Logical

optionsProvider object fields

Parameter	Description	Data type
type	Type of drop-down list: `FixedListOptionsProvider`: List of strings or numbers (for the `ru.yandex.startrek.core.fields.StringFieldType` or `ru.yandex.startrek.core.fields.IntegerFieldType` field types) `FixedUserListOptionsProvider`: List of users (for the `ru.yandex.startrek.core.fields.UserFieldType` field type)	String
values	Drop-down list values	Array of strings

Example: Create a local field of the Drop-down list type with a fixed set of string values:

An HTTP POST method is used.
A local field is created for the DESIGN queue.
Field type: FixedListOptionsProvider.
Drop-down list values: list item 1, list item 2, list item 3.

POST /v2/queues/DESIGN/localFields
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth token>
X-Org-ID: <organization ID>

{
"name":
{
   "en": "Name in English",
   "ru": "Name in Russian"
},
"id": "loc_field_key",
"category": "0000000000000003********",
"type": "ru.yandex.startrek.core.fields.StringFieldType",
"optionsProvider": {
   "type": "FixedListOptionsProvider",
   "values": [
       "list item 1",
       "list item 2",
       "list item 3"
   ]
}
}

Response format

Request executed successfully

Request failed

If the request is successful, the API returns a response with code 200 OK.

The response body contains information about the local queue field in JSON format.

 {
    "type": "local",
    "self": "https://https://api.tracker.yandex.net/v2/queues/ORG/localFields/loc_field_key",
    "id": "6054ae3a2b6b2c7f********--loc_field_key",
    "name": "Field name in Russian",
    "description": "Local field description",
    "key": "loc_field_key",
    "version": 1,
    "schema": {
        "type": "string",
        "required": false
    },
    "readonly": true,
    "options": false,
    "suggest": false,
    "queryProvider": {
        "type": "StringOptionalQueryProvider"
    },
    "order": 100,
    "category": {
        "self": "https://https://api.tracker.yandex.net/v2/fields/categories/0000000000000003********",
        "id": "0000000000000003********",
        "display": "category_name"
    }    
 }

Response parameters

Parameter	Description	Data type
type	Field type	String
self	Address of the API resource with information about the field	String
id	Unique field ID	String
name	Field name	String
description	Field description	String
key	Field key	String
version	Field version; each change to the field increases the version number	Number
schema	Object with information about the field value's data type	Object
readonly	Shows if the field value is editable: `true`: Non-editable `false`: Editable	Logical
options	Shows if the list of values is restricted: `true`: The list of values is not restricted, you can set any value `false`: The list of values is restricted by the organization's settings	Logical
suggest	Enables/disables search suggestions when entering field values: `true`: Enabled `false`: Disabled	Logical
optionsProvider	Object with information about the drop-down list items	Object
queryProvider	Object with information about the query language class. You cannot change the class using the API.	Object
order	Sequence number in the list of organization fields: https://tracker.yandex.com/admin/fields	Number
category	Object with information about the field category. To get a list of all categories, use the HTTP request: `GET /v2/fields/categories`	Object

schema object fields

Parameter	Description	Data type
type	Field value type Possible data types: `string`: String; available for fields with a single value `array`: Array; available for fields with multiple values	String
items	Value type; available for fields with multiple values	String
required	Shows if the field is required: `true`: Required `false`: Optional	Logical

optionsProvider object fields

Parameter	Description	Data type
type	Type of drop-down list	String
needValidation	Indicates if a list value requires validation: `true`: Yes `false`: Do not validate the field value	Logical
values	List items	Array of strings

queryProvider object fields

Parameter	Description	Data type
type	Query language type	String

category object fields

Parameter	Description	Data type
self	Address of the API resource with information about the field category	String
id	Field category ID	String
display	Category name displayed	String

If the request is processed incorrectly, the API returns a response with an error code:

400: One or more request parameters have an invalid value.

401: The user isn't authorized. Make sure to perform the actions described in API access.

403: Insufficient rights to perform this action. You can check what rights you have in the Tracker interface. The same rights are required to perform an action via the API and interface.

404: The requested object was not found. You may have specified an invalid object ID or key.

422: JSON validation error, the request is rejected.

500: Internal service error. Try resending your request in a few minutes.

503: The API service is temporarily unavailable.

Creating a local queue field

Request formatRequest format

Response formatResponse format

Was the article helpful?

Request format

Response format