Querying Fields

Function

This API is used to query the field list by page. Keywords, including title, field type, and creator, can be used for query.

Calling Method

For details, see Calling APIs.

URI

GET /v1/ipdprojectservice/projects/{project_id}/fields

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition: 32-character ID of a project, which must be unique. Obtain the value by calling the Querying the IPD Project List API. The value of id in the response message body is the project ID. Constraints: N/A Value range: N/A Default value: N/A

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
keyword	No	String	Definition: Keyword search by title, field type, and creator. Constraints: N/A Options: N/A Default value: N/A
offset	Yes	Integer	Definition: Pagination offset. Constraints: The value must be a multiple of limit. Options: Minimum value: 0. Default value: N/A
limit	Yes	Integer	Definition: Number of records displayed on each page Constraints: N/A Options: Minimum value: 1. Default value: N/A

Request Parameters

None

Response Parameters

Status code: 200

**Table 3** Response body parameters
Parameter	Type	Description
status	String	Definition: Returned status. Value range: success: The response is successful. error: The response failed.
message	String	Definition: Request failure information. Options: N/A
result	FieldListResult object	Definition: Field list.

**Table 4** FieldListResult
Parameter	Type	Description
data	Array of FieldEntity objects	Definition: Field list.
total	Integer	Definition: Total number of fields in a project. Options: N/A

**Table 5** FieldEntity
Parameter	Type	Description
display_name	String	Definition: Field name. Value range: N/A
code	String	Definition: Field code. Options: N/A
id	String	Definition: Field ID. Options: N/A
description	String	Definition: Field description. Options: N/A
created_by	String	Definition: Field creator name. Value range: N/A
created_date	String	Definition: Time when a field is created, in timestamp format, for example, 1715305846000. Value range: N/A
modified_by	String	Definition: Last updater name of a field. Value range: N/A
definition_type	String	Definition: Field level. Value range: 1, 2, and 3 (system-preset field) 4 (tenant-defined field) 5 (project-defined field)
field_type_name	String	Definition: Field type name. Options: N/A
required	Boolean	Definition: Whether the field is mandatory in the work item. If the field is inconsistent with the workflow configuration, the workflow prevails. Value range: true (mandatory) false (optional)
controlled	Boolean	Definition: Whether the field is controlled in the work item. If the controlled field in the baselined work item is changed, the change review process is required. If the field is inconsistent with the workflow configuration, the workflow prevails. Value range: true (controlled) false (non-controlled)
immutable	Boolean	Definition: Whether a field can be modified in the work item. If the value is inconsistent with the workflow configuration, the workflow prevails. Value range: true (cannot be modified) false (can be modified)
no	Integer	Definition: Field sequence number. Options: N/A
all_options	Array of OptionEntity objects	Definition: Field option.

**Table 6** OptionEntity
Parameter	Type	Description
id	String	Option ID.
code	String	Option code value.
display_value	String	Definition: Option name. Value range: N/A
value	String	Unique ID of an option.
level	Integer	Option level, which is used to distinguish field levels. A maximum of four levels are supported.
sequence	Integer	Option sequence.
parent_id	String	Parent option ID.

Example Requests

Querying fields by keyword

https://{endpoint}/v1/ipdprojectservice/projects/b54914d464d1498a97d683ef198ec448/fields?offset=0&limit=1

Example Responses

Status code: 200

{
  "status" : "success",
  "result" : {
    "data" : [ {
      "display_name" : "Subtitle",
      "code" : "c7186197833374113792",
      "id" : "994277015639076864",
      "description" : "222222222222",
      "created_by" : "Test alias",
      "created_date" : "1715305846000",
      "modified_by" : "Test alias",
      "definition_type" : "4",
      "field_type_name" : "Multi-line text",
      "required" : false,
      "controlled" : false,
      "immutable" : false,
      "no" : 9999
    } ],
    "total" : 1
  }
}