This page describes REST API operations for managing custom fields in Zephyr for Jira Server.

1 Create a custom field
2 Update a custom filed
3 Get custom fields details by field ID
4 Get custom field details by entity type
5 Get custom field details by entity type and project
6 Delete a custom field
7 Enable or disable a custom field for a project

Create a custom field

This API creates a Zephyr custom field.

REQUEST

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

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.

Update a custom filed

This API updates an existing custom field.

REQUEST

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

Response Body

         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.

Get custom fields details by field ID

This API retrieves information about a Zephyr custom field by its ID.

REQUEST

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

Response Body

         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.

Get custom field details by entity type

This API retrieves all custom fields of the specified entity type.

REQUEST

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

Response Body

Zephyr custom field information:

         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.

Get custom field details by entity type and project

This API retrieves all custom fields that have a specific entity type and that are used in a specific project.

REQUEST

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

Response Body

Zephyr custom field information:

         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.

Delete a custom field

This API deletes a custom field by its ID.

REQUEST

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

Response Body

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.

Enable or disable a custom field for a project

This API enables or disables a custom field for a project.

REQUEST

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

Response Body

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.

Developer Zone

Custom Fields API

Create a custom field

REQUEST

RESPONSE

Update a custom filed

REQUEST

RESPONSE

Get custom fields details by field ID

REQUEST

RESPONSE

Get custom field details by entity type

REQUEST

RESPONSE

Get custom field details by entity type and project

REQUEST

RESPONSE

Delete a custom field

REQUEST

RESPONSE

Enable or disable a custom field for a project

REQUEST

RESPONSE