This topic describes the API operation you can use to perform advanced search in Zephyr Enterprise. To get started with Zephyr Enterprise REST API, see Zephyr Enterprise REST API Documentation.
Use the following operation to search for items in Zephyr Enterprise by using a filter:
GET /flex/services/rest/latest/advancesearch?word=&entitytype=&releaseid=&zql=&isascorder=&order=&firstresult=&maxresults=&is_cfield=&isOld=
Request format
To search for items, send a GET request to the following URL:
| Panel | ||||||
|---|---|---|---|---|---|---|
| ||||||
Starting October 11, 2024 (Zephyr Enterprise 8.2), the Zephyr Enterprise documentation moved from its current location on Atlassian to a dedicated, standalone Zephyr Enterprise documentation page. Please see: https://support.smartbear.com/zephyr-enterprise/docs/en/zephyr-enterprise/zephyr-rest-api/search-api.html |
You can use Zephyr Enterprise REST API to search for test cases, requirements, and executions programmatically.
Request URL
| Code Block | ||
|---|---|---|
| ||
GET http(s)://{ZEPHYR-SERVER}/flex/services/rest/latest/advancesearch? word=<text> &entitytype=<entitytype> &releaseid=<id> &zql= |
...
false &isascorder=true &order=<fieldname> &firstresult=0 &maxresults=100 &is_cfield= |
...
false |
Parameters
...
Value
...
Value type
Authentication
You can authenticate your requests by using one of the methods described in the Zephyr REST API topic.
Request parameters
Value | Type | Description |
|---|---|---|
word (required) | string | A string to search for. |
entitytype
string
The type of the entity to search for.
releaseid
long
The ID of the release the entity belongs to.
zql
Boolean
Specifies whether ZQL is used.
isascorder
Boolean
Switches the ascending order.
order
string
The column order. For example, the parameter value can be orderId: .../flex/services/rest/v3/advancesearch/?word=test&firstresult=0&maxresults=50&order=orderId&releaseid=1
firstresult
int
The starting point of the record.
maxresults
int
The number of records to be fetched.
is_cfield
Boolean
Custom field order.
isOld
Boolean
Specifies whether the test case is old.
Sample request
| Code Block |
|---|
{
"entityType": "testcase",
"isZql": true,
"releaseId": 1
} |
Sample response
...
| language | json |
|---|
...
You can specify some text or a ZQL query (in the latter case, you will have to specify
| ||
entitytype (required) | string | The type of the entity to search for. Possible values:
|
releaseid (required) | long | The ID of the release the entity belongs to. To see the release ID in Zephyr, click Manage Release in the top-right corner and take a look at the value of the ID column in the subsequent window:  |
zql (required) | boolean | Specifies whether ZQL is used. |
isascorder (optional) | boolean | Switches the ascending order. Specify |
order (optional) | string | The field to sort data by (this can be either a standard or a custom field). For example: |
firstresult (required) | integer | The first element of the retrieved results. The parameter is zero-based, which means you need to specify |
maxresults (required) | integer | The number of records to be fetched. The maximum number is 100. |
is_cfield (optional) | boolean | If the |
Pagination
You can specify the first element of the retrieved results and the number of items to show by using the firstresult and maxresults query parameters respectively. The firstresult parameter is zero-based, which means you need to specify 0 as the start position to begin with the first element. The sample request below will show a list of results starting from the first element, and the maximum number of retrieved items will be 100:
GET /flex/services/rest/latest/advancesearch?word=test&entitytype=testcase&releaseid=1&zql=false&firstresult=0&maxresults=100
Sample requests
ZQL is not used:
GET /flex/services/rest/latest/advancesearch?word=test&entitytype=testcase&releaseid=1&zql=false&firstresult=0&maxresults=100
ZQL is used:
GET /flex/services/rest/latest/advancesearch?word=creator="test.manager" and priority="P1"&entitytype=testcase&releaseid=1&zql=true&firstresult=0&maxresults=100
Sample response
On success, the operation returns status code 200 and a JSON object containing metadata and found results. The structure of these results varies depending on the sought-for entities, items and so on. Below is a sample response obtained when searching for an execution:
| Code Block | ||
|---|---|---|
| ||
[ { "firstResult": 0, "tcrCatalogTreeIdresultSize":30, 1, "revisionresults":9, [ "stateFlag":0,{ "lastModifiedOnid":1600168120466 147, "versionNumber":1, ----------------------------------- The RTS ID (the execution ID) "createDatetimeassignmentDate":1600168114777, "2020-09-15", "createdByIdactualTime":5 600, "versionId": "modifiedById1":5, "testcasecomment":{ "This is a comment", "customPropertiestesterId":{ 5, "executedBy": 5, }, "tcrTreeTestcase": { "customProcessedProperties":{ }, "id":165 308, ----------------------------------- The TCR testCatalog caseTree versionTestCase ID (tctid) "nametcrCatalogTreeId":"edited 159 testcase edit", 30, "revision": 9, "descriptionstateFlag":"", 0, "lastModifiedOn":1600169396082 1600168120466, "creationDateversionNumber":1600128000000 1, "createDatetime":1600168102437 1600168114777, "tcCreationDate":"09/15/2020", "createdById": 5, "commentsmodifiedById":"" 5, "isComplextestcase":false, { "estimatedTimecustomProperties":600, { "writerId":0}, "creatorIdcustomProcessedProperties":5, { "lastUpdaterId":5, }, "oldIdid":0, 165, ----------------------------------- The test case version ID "automated":false, "name": "edited 159 "customFieldProcessed":falsetestcase edit", "customFieldValuesdescription":[ "", "lastModifiedOn": 1600169396082, "creationDate": ]1600128000000, "testcaseSequencecreateDatetime":{ 1600168102437, "seqNumbertcCreationDate":159 "09/15/2020", } "comments": "", "testcaseIdisComplex":159, ----------------------------------- The test case ID false, "versionNumber":1"estimatedTime": 600, "projectIdwriterId":3 0, "testcaseTypecreatorId":"ORIGINAL" 5, "requirementIdslastUpdaterId":[ 5, "oldId": 0, "automated": ]false, "projectNamecustomFieldProcessed":"P1" false, "requirementIdsNewcustomFieldValues": [ ], "creatorNametestcaseSequence":"divya divya",{ "lastModifierNameseqNumber":"divya divya",159 "automatedDefault":false}, "testcaseSharedtestcaseId":false }, "projectId":3, 159, ----------------------------------- The test case ID "releaseIdversionNumber":5 1, "isDerivedFromBDDprojectId":false 3, "orderIdtestcaseType":453, "ORIGINAL", "maxVersionNumberrequirementIds":1, [ "projectIdParam":3, "original":false ], }, "cyclePhaseIdprojectName":7, "P1", "lastTestResultrequirementIdsNew":{ [ "id":58, "executionDate":1600169404251, ], "execDatecreatorName":"09/15/2020 "John Smith", "executionStatuslastModifierName": "4John Smith", "testerIdautomatedDefault":5 false, "releaseTestScheduleIdtestcaseShared":147, false "createDatetime":1600169404253}, "modifiedDatetimeprojectId":1600169404250 3, "createdByIdreleaseId": 5, "modifiedByIdisDerivedFromBDD":5 false, }, "orderId": 453, "defects":[ "maxVersionNumber": 1, "projectIdParam": 3, ], "attachmentCountoriginal":0, false "lastModifiedBy":5, }, "cyclePhaseId": 7, "lastTestResult": { "createdById":5, "lastModifiedOn":1600169404255, "createDatetime":1600168120467 } ], "type":"testSchedule" } ] |
Response codes
...
HTTP Status Code
...
Description
...
200
...
The request completed successfully.
...
400
...
Bad request. At least one releaseid or departmentid parameter is required.
...
401
...
The authentication token is missing.
...
403
...
The user has no permissions to perform this operation.
...
500
...
id": 58,
"executionDate": 1600169404251,
"execDate": "09/15/2020",
"executionStatus": "4",
"testerId": 5,
"releaseTestScheduleId": 147,
"createDatetime": 1600169404253,
"modifiedDatetime": 1600169404250,
"createdById": 5,
"modifiedById": 5
},
"defects": [
],
"attachmentCount": 0,
"lastModifiedBy": 5,
"createdById": 5,
"lastModifiedOn": 1600169404255,
"createDatetime": 1600168120467
}
],
"type": "testSchedule"
}
] |
If no items matching the specified criteria are found, an empty results array is returned:
| Code Block |
|---|
[
{
"firstResult": 0,
"resultSize": 0,
"results": [],
"type": "testcase"
}
] |
Response Codes
HTTP Status Code | Description |
|---|---|
200 | The request completed successfully. |
400 | Bad request. |
401 | The authentication token is missing. |
403 | The user has no permissions to perform this operation. |
500 | Unknown internal error. |
| Anchor | ||||
|---|---|---|---|---|
|
| Expand | ||
|---|---|---|
| ||
|
| Expand | ||
|---|---|---|
| ||
|
| Expand | ||
|---|---|---|
| ||
|