This page describes REST API operations for managing custom fields in Zephyr for Jira Server.
This API creates a Zephyr custom field.
POST https://<client server base URL>/rest/zapi/latest/customfield/create
Content-Type: application/json
Authentication type: Basic
Request Body
{ "name": "first CF", "description": "My custom field", "defaultValue": "", "isActive": true, "fieldType": "TEXT", "aliasName": "", "projectId": "", "displayName": "", "displayFieldType": "Text Field (single line)", "entityType": "EXECUTION" } |
name: The name of the custom field.
description: The description of the custom field.
defaultValue: The default value of the custom field.
isActive: Indicates whether the custom field is active (at the project level).
fieldType: The type of the custom field.
aliasName: The short name of the custom field.
projectId: The project ID.
displayName: The displayed name of the custom field.
displayFieldType: The type of the displayed field.
entityType: The entity type. Either EXECUTION or TESTSTEP.
Allowed field types:
TEXT, LARGE_TEXT, NUMBER, RADIO_BUTTON, SINGLE_SELECT, MULTI_SELECT, DATE, DATE_TIME
Response Body
{ "name": "", "description": "", "defaultValue": null, "isActive": false, "fieldType": "", "aliasName": "", "projectId": null, "displayName": null, "createdOn": "", "createdBy": "", "entityType": "", "fieldOptions": null, "displayFieldType": null, "id": "", "responseMessage": "", "customFieldOptionValues": null, "modifiedBy": "", "active": false } |
id: The ID of the field that has just been created.
name: The name of the custom field.
description: The description of the custom field.
defaultValue: The default value of the custom field.
isActive: Indicates whether the custom field is active (at the project level).
fieldType: The type of the custom field.
aliasName: The short name of the custom field.
projectId: The project ID.
displayName: The displayed name of the custom field.
displayFieldType: The type of the displayed field.
entityType: The entity type. Either EXECUTION or TESTSTEP.
createdOn: The date the custom field was created.
createdBy: The user who created the custom field.
fieldOptions: The options of the custom field.
responseMessage: The response message of the created custom field.
customFiledOptionValues: The option values of the custom field.
modifiedBy: The user who modified the custom field.
active: The status of the custom field.
Response Codes
200: The request has been accepted and processed successfully.
400: Bad request or it is not configured properly. See the error message in the response body.
401: Unauthorized. Make sure you have specified the correct username and password.
403: Forbidden. Make sure you have the required permissions to perform this action.
404: Not found. The API URL was not found or it was not configured properly.
500: Make sure the server is up and running and Zephyr is configured properly before using the API.
This API updates an existing custom field.
PUT https://<client server base URL>/rest/zapi/latest/customfield/{customfieldId}
Content-Type: application/json
Authentication type: Basic
Parameters:
customfieldId: The ID of the custom field to be updated.
POST Body
{ "key1": "value1", "key2": "value2", ... "keyN": "valueN" } |
The fields the user can change:
Name: The name of the custom field to be updated.
Description: The description of the custom field to be updated.
Response Body
{ "name": "", "description": "", "defaultValue": null, "isActive": false, "fieldType": "", "aliasName": "", "projectId": null, "displayName": null, "createdOn": "", "createdBy": "", "entityType": "", "fieldOptions": null, "displayFieldType": null, "id": "", "responseMessage": "", "customFieldOptionValues": null, "modifiedBy": "", "modifiedDate": "", "active": false } |
id: The ID of the custom field.
name: The name of the custom field.
description: The description of the custom field.
defaultValue: The default value of the custom field.
isActive: Indicates whether the custom field is active (at the project level).
fieldType: The type of the custom field.
aliasName: The short name of the custom field.
projectId: The project ID.
displayName: The displayed name of the custom field.
displayFieldType: The type of the displayed text field.
entityType: The entity type. Either EXECUTION or TESTSTEP.
createdOn: The date the custom field was created.
createdBy: The user who created the custom field.
fieldOptions: The options of the custom field.
responseMessage: The response massage of the created custom field.
customFiledOptionValues: The option values of the custom field.
modifiedBy: The user who modified the custom field.
modifedDate: The date the custom field was modified.
active: The status of the custom field.
Response Codes
200: The request has been accepted and processed successfully.
400: Bad request or it is not configured properly. See the error message in the response body.
401: Unauthorized. Make sure you have specified the correct username and password.
403: Forbidden. Make sure you have the required permissions to perform this action.
404: Not found. The API URL was not found or it was not configured properly.
500: Make sure the server is up and running and Zephyr is configured properly before using the API.
This API retrieves information about a Zephyr custom field by its ID.
GET https://<client server base URL>/rest/zapi/latest/customfield/{id}
Authentication type: Basic
Parameters:
id: The ID of the custom field, information about which will be retrieved.
Response Body
{ "name": "", "description": "", "defaultValue": null, "isActive": false, "fieldType": "", "aliasName": "", "projectId": null, "displayName": null, "createdOn": "", "createdBy": "", "entityType": "", "fieldOptions": null, "displayFieldType": null, "id": "", "customFieldOptionValues": null, "active": false } |
id: The ID of the custom field.
name: The name of the custom field.
description: The description of the custom field.
defaultValue: The default value of the custom field.
isActive: Indicates whether the custom field is active (at the project level).
fieldType: The type of the custom field.
aliasName: The short name of the custom field.
projectId: The project ID.
displayName: The displayed name of the custom field.
displayFieldType: The type of the displayed field.
entityType: The entity type. Either EXECUTION or TESTSTEP.
createdOn: The date the custom field was created.
createdBy: The user who created the custom field.
fieldOptions: The options of the custom field.
customFiledOptionValues: The option values of the custom field.
active: The status of the custom field.
Response Codes
200: The request has been accepted and processed successfully.
400: Bad request. No custom field with the specified ID was found.
401: Unauthorized. Make sure you have specified the correct username and password.
403: Forbidden. Make sure you have the required permissions to perform this action.
404: Not found. The API URL was not found or it was not configured properly.
500: Make sure the server is up and running and Zephyr is configured properly before using the API.
This API retrieves all custom fields of the specified entity type.
GET https://<client server base URL>/rest/zapi/latest/customfield/entity?entityType=
Authentication type: Basic
Note: Query parameters are mandatory.
Query Parameters:
entityType: The entity type of the custom field. Possible values: EXECUTION, TESTSTEP.
Response Body
[ { Zephyr custom field information in the JSON format }, { Zephyr custom field information in the JSON format }, ... { Zephyr custom field information in the JSON format } ] |
Zephyr custom field information:
{ "name": "", "description": "", "defaultValue": null, "isActive": false, "fieldType": "", "aliasName": "", "projectId": null, "displayName": null, "createdOn": "", "createdBy": "", "entityType": "", "fieldOptions": null, "displayFieldType": null, "id": "", "customFieldOptionValues": null, "active": false } |
id: The ID of the custom field.
name: The name of the custom field.
description: The description of the custom field.
defaultValue: The default value of the custom field.
isActive: Indicates whether the custom field is active (at the project level).
fieldType: The type of the custom field.
aliasName: The short name of the custom field.
projectId: The project ID.
displayName: The displayed name of the custom field.
displayFieldType: The type of the displayed field.
entityType: The entity type. Either EXECUTION or TESTSTEP.
createdOn: The date the custom field was created.
createdBy: The user who created the custom field.
fieldOptions: The options of the custom field.
customFiledOptionValues: The option values of the custom field.
active: The status of the custom field.
Response Codes
200: The request has been accepted and processed successfully.
400: Bad request. No entity type with the specified ID was found.
401: Unauthorized. Make sure you have specified the correct username and password.
403: Forbidden. Make sure you have the required permissions to perform this action.
404: Not found. The API URL was not found or it was not configured properly.
500: Make sure the server is up and running and Zephyr is configured properly before using the API.
This API retrieves all custom fields that have a specific entity type and that are used in a specific project.
GET https://<client server base URL>/rest/zapi/latest/customfield/byEntityTypeAndProject?entityType=&projectId=
Authentication type: Basic
Note: Both query parameters are mandatory.
Query Parameters:
entityType: The entity type of the custom field. Possible values: EXECUTION, TESTSTEP.
projectId: The project ID.
Response Body
[ { Zephyr custom field information in the JSON format }, { Zephyr custom field information in the JSON format }, ... { Zephyr custom field information in the JSON format } ] |
Zephyr custom field information:
{ "name": "", "description": "", "defaultValue": null, "isActive": false, "fieldType": "", "aliasName": "", "projectId": null, "displayName": null, "createdOn": "", "createdBy": "", "entityType": "", "fieldOptions": null, "displayFieldType": null, "id": "", "customFieldOptionValues": null, "active": false } |
id: The ID of the custom field.
name: The name of the custom field.
description: The description of the custom field.
defaultValue: The default value of the custom field.
isActive: Indicates whether the custom field is active (at the project level).
fieldType: The type of the custom field.
aliasName: The short name of the custom field.
projectId: The project ID.
displayName: The displayed name of the custom field.
displayFieldType: The type of the displayed text field.
entityType: The entity type. Either EXECUTION or TESTSTEP.
createdOn: The date the custom field was created.
createdBy: The user who created the custom field.
fieldOptions: The options of the custom field.
customFiledOptionValues: The option values of the custom field.
active: The status of the custom field.
Response Codes
200: The request has been accepted and processed successfully.
400: Bad request. No entity type with the specified ID was found.
401: Unauthorized. Make sure you have specified the correct username and password.
403: Forbidden. Make sure you have the required permissions to perform this action.
404: Not found. The API URL was not found or it was not configured properly.
500: Make sure the server is up and running and Zephyr is configured properly before using the API.
This API deletes a custom field by its ID.
DELETE https://<client server base URL>/rest/zapi/latest/customfield/{customfieldId}
Authentication type: Basic
Parameters:
customfieldId: The ID of the custom field to be deleted.
Response Body
{ "message": "" } |
message: The message to be sent if the field cannot be deleted or if it has been deleted successfully.
Response Codes
200: The request has been accepted and processed successfully.
400: Bad request. No custom field with the specified ID was found.
401: Unauthorized. Make sure you have specified the correct username and password.
403: Forbidden. Make sure you have the required permissions to perform this action.
404: Not found. The API URL was not found or it was not configured properly.
500: Make sure the server is up and running and Zephyr is configured properly before using the API.
This API deletes several custom fields by their IDs.
DELETE https://<client server base URL>/rest/zapi/latest/customfield/delete-customfields
Authentication type: Basic
Parameters:
customfieldIds: The IDs of the custom fields to be deleted.
Sample payload:
{ "customfields":["3","14"] } |
3 and 14 - the IDs of the fields to be deleted.
Response Body
{ "message": "" } |
message: The message to be sent if the field cannot be deleted or if it has been deleted successfully.
Response Codes
200: The request has been accepted and processed successfully.
400: Bad request. No custom field with the specified ID was found.
401: Unauthorized. Make sure you have specified the correct username and password.
403: Forbidden. Make sure you have the required permissions to perform this action.
404: Not found. The API URL was not found or it was not configured properly.
500: Make sure the server is up and running and Zephyr is configured properly before using the API.
This API enables or disables a custom field for a project.
DELETE https://<client server base URL>/rest/zapi/latest/customfield/{customFieldId}/{projectId}?enable
Authentication type: Basic
Path parameters:
customFieldId: The ID of the custom filed.
projectId: The project ID.
Note: The query parameter enable is mandatory.
Query parameters:
enable: false or true. If false, the custom field will be disabled for the project. Else, the custom field will be enabled.
Response Body
{ "message": "" } |
message: The details based on the input value.
Response Codes
200: The request has been accepted and processed successfully.
400: Bad request. Either the custom field or the project with the specified ID was not found.
401: Unauthorized. Make sure you have specified the correct username and password.
403: Forbidden. Make sure you have the required permissions to perform this action.
404: Not found. The API URL was not found or it was not configured properly.
500: Make sure the server is up and running and Zephyr is configured properly before using the API.