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-user-guide/zephyr-test-automation/api-operations-for-automation-jobs.html

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:

Response code	Description

Response code	Description
200	The operation has been completed successfully.
400	Error in request data or parameters. For instance, the project or job with the specified id doesn’t exist.
401	Authentication error (authentication token is missing).
403	Error. You don’t have permissions to perform this operation.
500	Internal server error.

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.

Property	Description

Property	Description
`jobName`	String. The name of the new job. It will identify the job in the product UI. This parameter cannot be an empty string.
`projectId`	Integer. The identifier of the project, to which the new job will post the results. 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:
`releaseId`	Integer. The identifier of the release, to which the new job will post the results. 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:
`automatedFramework`	String. The automation framework to be used for the test run. Use the same values that the Automation Framework drop-down list in the product UI has.
`cycleName`	String. The name of the cycle to be used.
`phaseName`	String. The cycle phase to be used for the run.
`jobDetailTcrCatalogTreeId`	Integer. Id of the test case repository item.
`testRepositoryPath`	The Zephyr test repository that contains the tests to be executed. Use the names as they are shown in the product UI. Separate levels with the `>` symbol, for example, `"Release 1.0 > new"`.
`cycleStartDateStr`, `cycleEndDateStr`	Specifies the start and end dates of the cycle. as strings in the mm/dd/yyyy format.
`IsReuse`	`true` or `false`. Specifies if the test engine will use the same cycle for all the automation runs (`true`) or if it will create a new cycle for each run (`false`).
`assignResultsTo`	Integer. The id of the user to whom the test engine will assign results.

{
 "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.

{
    "id": 1,
    "projectId": 5,
    "releaseId": 9,
    "automationFramework": "junit",
    "jobCrationDate": 1643879564994,
    "createdBy": "test test",
    "cycleDuration": 18,
    "isTimeStamp": false,
    "createPackage": false,
    "assignResultsTo": 1,
    "cycleName": "cycle",
    "phaseName": "new",
    "isReuse": true,
    "jobName": "Demo123",
    "testRepositoryPath": "Release 1.0 > new",
    "jobDetailTcrCatalogTreeId": 32,
    "cycleStartDateStr": "02/03/2022",
    "cycleEndDateStr": "02/21/2022",
    "jobSource": 2,
    "fileUplaodJobPath": "junit.xml",
    "timeStamp": false
}

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.

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.

Zephyr Enterprise 8.1.0

API Operations for Automation Jobs

Base URL, authentication, data formats

Respose codes

Create an automation job

Request data

Response data

Schedule a job run

Request data

Response data

Create and execute a job

Request data

Response data