Get Value for an Issue Custom Field

Last modified: 17 December 2019

Summary

To get a value of a specific custom field in an issue, send a GET request to the following endpoint:

/api/issues/{issueID}/customFields/{fieldID}[?fields={list of attributes}]

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 projects shortName is `SP`.

In the fields request parameter, we instruct the server to return the following attributes for each issue found:

id and idReadable - 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 id 2-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 of StateIssueCustomField. It binds a project custom field of the type StateProjectCustomField and a value. A StateProjectCustomField uses a bundle of values of the type StateBundle. And a StateBundle 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"
}

Get Value for an Issue Custom Field﻿

Use Case:

note

Summary﻿

Step-by-Step﻿

Get Value for an Issue Custom Field

Summary

Step-by-Step