Create Cycle

Applies to Zephyr Squad Server 9.0.1 and 4.8, last modified on September 19, 2022

To create a new test cycle, send a POST request to /rest/zapi/latest/cycle with a JSON body containing properties of the created cycle.

Request URL

POST http://{base-URL}/rest/zapi/latest/cycle

Request body

The request body contains a JSON object that specifies properties of the new cycle, for example:

{
    "clonedCycleId": "",
    "name": "New cycle",
    "description": "Description of my new cycle",
    "projectId": "10600",
    "versionId": "-1",
    "sprintId": null,
    "build": "",
    "startDate": "29/Nov/22",
    "endDate": "4/Dec/22",
    "environment": ""
}

Property Description
clonedCycleId

Number. Use this parameter if you want to clone a cycle. In this case, it should specify the ID of the cycle to clone. Otherwise, this parameter must be an empty string.

name

String. The name of the new cycle.

description

String. An arbitrary string describing the cycle.

projectId

Number. The Jira ID of the project to which the new cycle will belong. See how to get this ID.

versionId

The Jira ID of the project version (version or release) to which the new cycle will belong. See how to get this ID.

To assign the new cycle to an unscheduled version, use "versionId": -1.

sprintId

Number. The Jira ID of the sprint to which the cycle will belong.

If you don’t want to add the cycle to any sprint, set "sprintId": -1.

build

String. The build to which the new cycle will belong.

startDate,
endDate

Strings that specify the start and end date of the new cycle in the DD/MMM/YY format.

endDate should be later than startDate. Else, the operation will fail.

environment

The string that specifies the environment for the new cycle.

Other request parameters

Every request must include authentication parameters. See Zephyr Squad Server REST API.

Operation reference

Example

curl --request POST http://15.20.184.119:8089/rest/zapi/latest/cycle ^
     --user "admin:password" ^
     --header "Content-Type:application/json" ^
     --data "{\"name\": \"New cycle\", \"build\": \"\", \"environment\": \"\", \"description\": \"Description of my new cycle\", \"startDate\": \"29/Nov/22\", \"endDate\": \"4/Dec/22\", \"projectId\": \"10600\", \"versionId\": \"-1\", \"sprintId\": null}"

Response

A successful response has the HTTP status 200 OK and contains the ID of the new cycle and a message about successful creation, for example:

{
    "id": "1506",
    "responseMessage": "Cycle New cycle created successfully."
}

In case of an error, the response code is 4xx or 5xx, and the response body contains the description of the error. Here are some examples:

  • If the request body doesn’t specify some required parameters, the operation returns the 406 Not Acceptable code and the description of the problem in the response body:

    {
        "versionId": "Version Id (versionId) is required."
    }

  • If the request body has invalid JSON, an error will occur on the server. In this case, the response code will be 500 Internal Server Error and the response body will include the exception text and call stack.

  • If the request doesn’t have authentication data, the response code will be 200 OK, and the response body will include the error message:

    {
        "errorDesc": "You do not have the permission to make this request. Login Required.",
        "errorId": "ERROR"
    }

Create a cycle by cloning

You can create a new cycle by cloning an existing one. To do this, use the same POST /rest/zapi/latest/cycle operation described above.

To specify the cycle to clone, pass its ID in the "cloneCycleId" parameter in the request body. You can get this ID from the response to the request that created the cycle. See also other ways to get this ID.

Here is an example of the request body:

{
    "clonedCycleId": 1500,
    "name": "New cycle",
    "projectId": 10600,
    "versionId": -1
}

Other parameters are –

Parameter Description
name

The name of the new cycle.

projectId

The identifier of the project to which the new cycle will belong. See how to get this ID.

versionId

The identifier of the version to which the new cycle will belong. See how to get this ID.

All these parameters are required. Other parameters will be copied from the source cycle.

Example

curl --request POST http://15.27.184.119:8089/rest/zapi/latest/cycle ^
     --user "admin:password" ^
     --header "Content-Type:application/json" ^
     --data "{\"cloneCycleId\": \"1500\", \"name\": \"New cycle\", \"projectId\": \"10600\", \"versionId\": \"-1\"}

Next steps

See Also

Zephyr Squad Server REST API

Highlight search results