Get Value for an Issue Custom Field
Use Case:
Use the REST API to retrieve the current value of a specific custom field in an issue.
Summary
To get a value of a specific custom field in an issue, send a GET
request to the following endpoint:
To form this request correctly, you need the following data:
An ID of the issue, for which you get the custom field.
An ID of the issue custom field, for which you get its value.
A list of attributes of the value that you wish to receive from the server.
To obtain IDs of the target issue and the field, you can use a single GET
request for a list of issues.
To form a list of value attributes, refer to the list of supported attributes for a value entity depending on the $type
of the target custom field in an issue.
Step-by-Step
-
Get the list of issues in a target project. Also, let's request the list of available custom fields with their names.
curl -X GET \ 'https://example.myjetbrains.com/youtrack/api/issues?query=in:SP&fields=id,idReadable,summary,customFields(id,projectCustomField(field(name)))' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer perm:amFuZS5kb2U=.UkVTVCBBUEk=.wcKuAok8cHmAtzjA6xlc4BrB4hleaX' \ -H 'Cache-Control: no-cache' \ -H 'Content-Type: application/json'The
query
request parameter lets us filter the list of issues by the target project, in the sample the projectsshortName
is `SP`.In the
fields
request parameter, we instruct the server to return the following attributes for each issue found:id
andidReadable
- both database entity ID and an ID of the issue in the project, respectively.summary
- issue's summary may help to identify the target issue.customFields
- a list of custom fields for each issue. To help us identify the target custom field, we also request the name of each field which is defined through the project custom field and its "prototype" - the generic custom field.
In the response to this request, the server returns the following data:
[ { "summary": "Issue from REST #1", "idReadable": "SP-8", "customFields": [ { "projectCustomField": { "field": { "name": "Priority", "$type": "CustomField" }, "$type": "EnumProjectCustomField" }, "id": "92-1", "$type": "SingleEnumIssueCustomField" }, { "projectCustomField": { "field": { "name": "Type", "$type": "CustomField" }, "$type": "EnumProjectCustomField" }, "id": "92-2", "$type": "SingleEnumIssueCustomField" }, { "projectCustomField": { "field": { "name": "State", "$type": "CustomField" }, "$type": "StateProjectCustomField" }, "id": "92-3", "$type": "StateIssueCustomField" }, { "projectCustomField": { "field": { "name": "Assignee", "$type": "CustomField" }, "$type": "UserProjectCustomField" }, "id": "94-0", "$type": "SingleUserIssueCustomField" }, { "projectCustomField": { "field": { "name": "Subsystem", "$type": "CustomField" }, "$type": "OwnedProjectCustomField" }, "id": "92-0", "$type": "SingleOwnedIssueCustomField" }, { "projectCustomField": { "field": { "name": "Fix versions", "$type": "CustomField" }, "$type": "VersionProjectCustomField" }, "id": "92-4", "$type": "MultiVersionIssueCustomField" }, { "projectCustomField": { "field": { "name": "Affected versions", "$type": "CustomField" }, "$type": "VersionProjectCustomField" }, "id": "92-5", "$type": "MultiVersionIssueCustomField" }, { "projectCustomField": { "field": { "name": "Fixed in build", "$type": "CustomField" }, "$type": "BuildProjectCustomField" }, "id": "92-6", "$type": "SingleBuildIssueCustomField" } ], "id": "2-7", "$type": "Issue" }, { "summary": "Sprint 3. Task 2", "idReadable": "SP-38", "customFields": [ ... ], "id": "2-42", "$type": "Issue" }, { "summary": "Sprint3. Task 1", "idReadable": "SP-37", "customFields": [ ... ], "id": "2-40", "$type": "Issue" }, ... ] -
Locate the ID of the target issue. For the sample, let's take the issue
SP-8
with the entity id2-7
. -
Locate the ID of a target custom field. Let's get the current State of the issue. In the sample, the ID if the State field is
92-3
. -
Form a list of attributes that you want to get for the State field.
A list of supported attributes for a custom field depends entirely on its type.
A State field has
$type
ofStateIssueCustomField
. It binds a project custom field of the typeStateProjectCustomField
and a value. A StateProjectCustomField uses a bundle of values of the type StateBundle. And aStateBundle
stores values of the type StateBundleElement. Thus, to form a list of attributes that we want to get for the current value of the State field, we need to check the JSON schema and see what attributes does the StateBundleElement entity contain.For the sample, we picked these:
Attribute
Description
name
The name of the value. It represents the actual State that users see in UI: Open, In Progress, Fixed, and so on.
localizedName
If the server does not use the default locale, this attribute stores the name of the value in the selected locale.
isResolved
Indicates if the value - the state - is considered as resolved.
id
The entity ID of the value.
To verify that we get the correct field in the sample, we also request the name of the the field and its ID.
So, when we put together all the attributes that we want to receive from the server, the request parameter
fields
looks as follows:fields=id,projectCustomField(id,field(name)),value(id,isResolved,localizedName,name) -
Now that we collected all the data that is required for the request, this is the resulting request for the field value:
curl -X GET \ 'https://example.myjetbrains.com/youtrack/api/issues/SP-8/customFields/92-3?fields=id,projectCustomField%28id,field%28id,name%29%29,value%28id,isResolved,localizedName,name%29' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer perm:amFuZS5kb2U=.UkVTVCBBUEk=.wcKuAok8cHmAtzjA6xlc4BrB4hleaX' \ -H 'Cache-Control: no-cache' \ -H 'Content-Type: application/json'For this request, the server returns the following response body:
{ "projectCustomField": { "field": { "name": "State", "id": "58-3", "$type": "CustomField" }, "id": "92-3", "$type": "StateProjectCustomField" }, "value": { "isResolved": true, "localizedName": null, "name": "Fixed", "id": "69-7", "$type": "StateBundleElement" }, "id": "92-3", "$type": "StateIssueCustomField" }