Base URL, authentication, data formats

The operations described below work for both Cloud and On-Premise instances of Zephyr Enterprise. They use the same authentication parameters and data formats that other Zephyr API operations use. For complete information on these, see Zephyr REST API.

Respose codes

The API operations described below use the following response codes:

Create an automation job

To create a new automation job, use this operation:

POST http://<zephyr-server-address>/flex/services/rest/v4/upload-file/automation/create-job-detail

Request data

The request body specifies proeprties of the job to be created.

...

{
 "releaseId": 5,
 "jobName": "Demo123",
 "automationFramework": "junit",
 "cycleName": "cycle",
 "jobDetailTcrCatalogTreeId": 32,
 "projectId": 9,
 "testRepositoryPath": "Release 1.0 > new",
 "cycleStartDateStr": "02/03/2022",
 "cycleEndDateStr": "02/21/2022",
 "isReuse": true,
 "assignResultsTo": "1",
 "phaseName": "new""
}

Response data

If the operation succeeded, the response has the 200 OK status and the response body contains the created job properties. The id property is the job's identifier. You can use it later in operations that update job properties or delete a job.

...

If the operation failed, it returns one of the error codes.

Schedule a job run

To schedule the run of one or multiple jobs, use the following operation:

POST http://<zephyr-server-address>/flex/services/rest/v4/upload-file/automation/execute-job

Request data

The request body contains an object with the ids property that is an array of job identifiers to be used for the run. You can find this identifier in the response of the operation that created the automation job.

{"ids":[1, 2, 3]}

Response data

If the operation succeeds, the response code is 200 OK and the response body contains information on the scheduled run. The id property is the identifier of the run. You can use it later to check the job status, or to stop or cancel a job.

...

If the operation fails, it returns of the error codes.

Create and execute a job

The following operation creates a new job and commands the test engine to run it:

POST http://<zephyr-server-address>/flex/services/rest/v4/upload-file/automation/create-and-execute-job

Request data

The request body specifies the name, project, release, cycle, and other properties of the created job. These are the values described above.

{
  "releaseId":11 ,
  "jobName": "Demo123111",
  "automationFramework": "junit",
  "cycleName": "cycle",
  "jobDetailTcrCatalogTreeId": 20,
  "projectId": 6,
  "testRepositoryPath": "Release 1.0 > new",
  "cycleEndDateStr": "02/21/2022",
  "cycleStartDateStr": "02/04/2022",
  "isReuse": true,
  "assignResultsTo": "1",
  "phaseName": "new"
}

Response data

If the operation succeeds, the response status is 200 OK and the response body contains information on the scheduled run:

...

If the operation fails, it returns of the error codes.

Get job status

Use this operation:

GET http://<zephyr-server-address>/flex/services/rest/v4/upload-file/automation/schedule/get-latest-job-progress?jobid={ID}

Request data and URL parameters

The request body is not used. The jobid parameter in the URL specifies the identifier of the job whose status you want to check. You get this identifier in the response to the operation that created the job.

Response data

If the operation succeeds, the response status is 200 OK and the response body has information on the job and its cycle.

...

In case of an error, the operation returns one of the error codes.

Stop or cancel a job

Use the following operation:

POST http://<zephyr-server-address>/flex/services/rest/v4/upload-file/automation/cancel/{ID}

Request data and URL parameters

The request body is not used. The ID parameter in the URL is the identifier of the scheduled run. You can find it in the response to the operation that scheduled the job run - it’s the id property of the object in the response body.

Response data

If the operation succeeds, the response status is 200 OK and the response body contains true.

If the operation fails, it returns one of the error codes.

Get job properties

Use the following operation to get properties of an automation job:

GET http://<zephyr-server-address>/flex/services/rest/v3/automation/job/detail?jobid={ID}

Request data and URL parameters

The request body is not used. The jobid parameter in the URL specifies the identifier of the desired job. You get this identifier in a response to the operation that created the job.

Response data

If the operation succeeded, the response status is 200 OK and the response body contains information on the specified job.

...

If the operation fails, it returns of the error codes.

Update job properties

Use the following operation:

POST http://<zephyr-server-address>/flex/services/rest/v4/upload-file/automation/update-execute-job

Request data

To specify new values of the job properties, you pass a JSON object in the request body. The id property of this object specifies the job to be updated. You can get this ID in the response of the operation that created the automation job. Other properties of the object specify new values of the job properties. For information on them see above.

{
  "id": 8, <-- job ID
  "releaseId": 18,
  "jobName": "Demo1",
  "automationFramework": "junit",
  "cycleName": "cycle",
  "jobDetailTcrCatalogTreeId": 34,
  "projectId": 7,
  "testRepositoryPath": "Release 1.0 > testrepo",
  "cycleEndDateStr": "02/21/2022",
  "cycleStartDateStr": "02/15/2022",
  "isReuse": true,
  "assignResultsTo": "1",
  "phaseName": "testrepo"
}

Response data

If the operation succeeds, the response status is 200 OK, and the response body contains a JSON object with updated job properties.

If the operation fails, it returns of the error codes.

Get properties of several jobs

Use the following operation to get all job linked to the specified project and release:

GET http://<zephyr-server-address>/flex/services/rest/v4/upload-file/automation/file-upload-job/list?projectId={projectID}&releaseId={releaseID}

Request data and URL parameters

The request body is not used. The URL has the following parameters:

Parameter	Description
projectID	Integer. The Jira identifier of the desired project (not the project key). Expand title How to get the project id Log in to Zephyr, and select your project from the drop-down list on the top. You will see the project id in the URL: Image Modified
releaseID	Integer. The Jira identifier of the desired release in that project. Expand title How to get the release id Log in to Zephyr and select your project and release from the drop-down lists on the top. You will see the release id in the URL: Image Modified

Response data

If the operation succeeds, the response status is 200 OK and the response body has a JSON array with information on all the jobs created for the specified project and release.

...

If the operation fails, it returns one of the error codes.

Delete a job

Use this operation:

POST  http://<zephyr-server-address>/flex/services/rest/v3/automation/job/delete

The request body specifies the jobs to be deleted.

Request data

The request body contains identifiers of jobs to be deleted. These are identifiers you get for a job in the response to the request that created that job:

...

{
  "ids": [
    12
  ]
}

Response data

The operation returns 200 OK, if the job or jobs have been deleted successfully. In case of an error, the operation returns one of the error codes.

See Also

ZBot Overview
Script Automation
Suite Automation
Folder Watcher
Create and Manage API Tokens in Zephyr