Help Center/ CodeArts Req/ API Reference/ API/ Work Items of the Scrum Project/ Querying Customized Fields of Scrum Work Items
Updated on 2025-09-10 GMT+08:00

Querying Customized Fields of Scrum Work Items

Function

This API is used to query the options of custom fields of Scrum work items. Fields that meet the custom_fields or names condition are returned. If neither of the two conditions is used, all custom fields are returned.

Calling Method

For details, see Calling APIs.

URI

POST /v4/projects/{project_id}/issues/custom-fields

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition:

32-character UUID of a project, which uniquely identifies a project. Obtain the value of this parameter from the project_id field in the response body of the Querying the Project List API.

Constraints:

Regular expression: [A-Za-z0-9]{32}

Options:

N/A

Default value:

N/A

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

Definition:

User token. Obtain the token by calling theObtaining a User TokenIAM API. In the returned response header, X-Subject-Token is the desired user token.

Constraints:

Mandatory.

Range:

Minimum length: 10 character. Maximum length: 32,768 characters.

Default value:

N/A

Table 3 Request body parameters

Parameter

Mandatory

Type

Description

custom_fields

No

Array of strings

Definition:

Custom field.

Constraints:

N/A

included_not_in_use

No

Boolean

Definition:

Whether unused custom fields are included in the query result. By default, only custom fields that are in use are queried.

Constraints:

false (not included)

true (included)

Options:

N/A

Default value:

N/A

names

No

Array of strings

Definition:

Custom field name.

Constraints:

N/A

Options:

N/A

Default value:

N/A

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

datas

Array of IssueCustomField objects

Definition:

Return data of custom fields.

Constraints:

N/A

Table 5 IssueCustomField

Parameter

Type

Description

create_time

String

Definition:

Creation time of a custom field.

Options:

N/A

custom_field

String

Definition:

Custom field.

Options:

N/A

name

String

Definition:

Display meaning of a custom field.

Options:

N/A

options

String

Definition:

Value options for custom fields. Separate multiple values by commas (,).

Options:

N/A

tracker_ids

Array of integers

Definition:

Work item types supported by custom fields.

Options:

2 (task)

3 (bug)

5 (epic)

6 (feature)

7 (story)

type

String

Definition:

Custom field type.

Value range:

textArea: multi-line text, containing letters, digits, underscore (), and hyphen (-). The length cannot exceed 500 characters. text: single-line text, containing letters, digits, underscore (), and hyphen (-). The length cannot exceed 500 characters.

select: drop-down list, containing letters, digits, underscore (), and hyphen (-). An option contains a maximum of 40 characters. A maximum of 60 options can be customized. number: number whose value range is set by users during custom field creation. date (The date is accurate to year, month, and day, and time_date is accurate to hour, minute, and second. The value is a long integer timestamp.) checkbox: check box, containing letters, digits, underscore (), and hyphen (-). An option contains a maximum of 40 characters and a maximum of 60 options can be customized.

radio: radio box, containing letters, digits, underscore (_), and hyphen (-). An option contains a maximum of 40 characters. A maximum of 60 options can be customized.

Status code: 400

Table 6 Response body parameters

Parameter

Type

Description

error_code

String

Error Codes

error_msg

String

Description

Status code: 401

Table 7 Response body parameters

Parameter

Type

Description

error_code

String

Error Codes

error_msg

String

Description

Example Requests

Post https://{endpoint}/v4/projects/0792b7d26cb74bd799cbae80063dc74a/issues/custom-fields

{
  "included_not_in_use" : true,
  "names" : [ "Drop-down list demo" ]
}

Example Responses

Status code: 200

OK

{
  "datas" : [ {
    "name" : "selectName",
    "custom_field" : "custom_field16",
    "options" : "selectName1,selectName2",
    "type" : "ratio",
    "tracker_ids" : [ 7 ],
    "create_time" : "2023-05-17T09:50:04+08:00"
  } ]
}

SDK Sample Code

The SDK sample code is as follows.

Java

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
package com.huaweicloud.sdk.test;

import com.huaweicloud.sdk.core.auth.ICredential;
import com.huaweicloud.sdk.core.auth.BasicCredentials;
import com.huaweicloud.sdk.core.exception.ConnectionException;
import com.huaweicloud.sdk.core.exception.RequestTimeoutException;
import com.huaweicloud.sdk.core.exception.ServiceResponseException;
import com.huaweicloud.sdk.projectman.v4.region.ProjectManRegion;
import com.huaweicloud.sdk.projectman.v4.*;
import com.huaweicloud.sdk.projectman.v4.model.*;

import java.util.List;
import java.util.ArrayList;

public class ListIssueCustomFieldsSolution {

    public static void main(String[] args) {
        // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        String ak = System.getenv("CLOUD_SDK_AK");
        String sk = System.getenv("CLOUD_SDK_SK");

        ICredential auth = new BasicCredentials()
                .withAk(ak)
                .withSk(sk);

        ProjectManClient client = ProjectManClient.newBuilder()
                .withCredential(auth)
                .withRegion(ProjectManRegion.valueOf("<YOUR REGION>"))
                .build();
        ListIssueCustomFieldsRequest request = new ListIssueCustomFieldsRequest();
        request.withProjectId("{project_id}");
        ListIssueCustomFieldsRequestBody body = new ListIssueCustomFieldsRequestBody();
        List<String> listbodyNames = new ArrayList<>();
        listbodyNames.add("Drop-down list demo");
        body.withIncludedNotInUse(true);
        body.withNames(listbodyNames);
        request.withBody(body);
        try {
            ListIssueCustomFieldsResponse response = client.listIssueCustomFields(request);
            System.out.println(response.toString());
        } catch (ConnectionException e) {
            e.printStackTrace();
        } catch (RequestTimeoutException e) {
            e.printStackTrace();
        } catch (ServiceResponseException e) {
            e.printStackTrace();
            System.out.println(e.getHttpStatusCode());
            System.out.println(e.getRequestId());
            System.out.println(e.getErrorCode());
            System.out.println(e.getErrorMsg());
        }
    }
}

Python

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
# coding: utf-8

import os
from huaweicloudsdkcore.auth.credentials import BasicCredentials
from huaweicloudsdkprojectman.v4.region.projectman_region import ProjectManRegion
from huaweicloudsdkcore.exceptions import exceptions
from huaweicloudsdkprojectman.v4 import *

if __name__ == "__main__":
    # The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    # In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak = os.environ["CLOUD_SDK_AK"]
    sk = os.environ["CLOUD_SDK_SK"]

    credentials = BasicCredentials(ak, sk)

    client = ProjectManClient.new_builder() \
        .with_credentials(credentials) \
        .with_region(ProjectManRegion.value_of("<YOUR REGION>")) \
        .build()

    try:
        request = ListIssueCustomFieldsRequest()
        request.project_id = "{project_id}"
        listNamesbody = [
            "Drop-down list demo"
        ]
        request.body = ListIssueCustomFieldsRequestBody(
            included_not_in_use=True,
            names=listNamesbody
        )
        response = client.list_issue_custom_fields(request)
        print(response)
    except exceptions.ClientRequestException as e:
        print(e.status_code)
        print(e.request_id)
        print(e.error_code)
        print(e.error_msg)

Go

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
package main

import (
	"fmt"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/basic"
    projectman "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/projectman/v4"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/services/projectman/v4/model"
    region "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/projectman/v4/region"
)

func main() {
    // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak := os.Getenv("CLOUD_SDK_AK")
    sk := os.Getenv("CLOUD_SDK_SK")

    auth := basic.NewCredentialsBuilder().
        WithAk(ak).
        WithSk(sk).
        Build()

    client := projectman.NewProjectManClient(
        projectman.ProjectManClientBuilder().
            WithRegion(region.ValueOf("<YOUR REGION>")).
            WithCredential(auth).
            Build())

    request := &model.ListIssueCustomFieldsRequest{}
	request.ProjectId = "{project_id}"
	var listNamesbody = []string{
        "Drop-down list demo",
    }
	includedNotInUseListIssueCustomFieldsRequestBody:= true
	request.Body = &model.ListIssueCustomFieldsRequestBody{
		IncludedNotInUse: &includedNotInUseListIssueCustomFieldsRequestBody,
		Names: &listNamesbody,
	}
	response, err := client.ListIssueCustomFields(request)
	if err == nil {
        fmt.Printf("%+v\n", response)
    } else {
        fmt.Println(err)
    }
}

More

For SDK sample code of more programming languages, see the Sample Code tab in API Explorer. SDK sample code can be automatically generated.

Status Codes

Status Code

Description

200

OK

400

Bad Request

401

Unauthorized

Error Codes

See Error Codes.