Add Folders to Cycles
To create a folder in a test cycle, send a POST request to /rest/zapi/latest/folder/create with a JSON body containing properties of the created folder.
Request URL
POST /rest/zapi/latest/folder/createRequest body
The request body contains a JSON object that specifies properties of the new folder, for example:
{
"cycleId": 1508,
"name": "My Folder",
"description": "A test folder for the cycle",
"projectId": 10600,
"versionId": -1,
"clonedFolderId": -1
}Property description
Property | Description |
|---|---|
| Number. The identifier of the cycle to which the new folder will belong. You can get this ID in the response to the API request that created the cycle. See also other ways to get this ID. |
| Number. The ID of the Jira project to which the folder will belong. See how to get this ID. |
| Number. The Jira ID of the project version (version or release) to which the folder will belong. See how to get this ID. If you are not going to use any version, set |
| String. The name of the new folder. It cannot coincide with the name of an existing folder in the cycle. |
| String. Arbitrary text describing the folder. |
| Number. Use this parameter to clone some existing folder (see below for details). If you are not going to clone a folder, skip this parameter or use |
Other request parameters
Every request must include authentication parameters. See Zephyr Squad Server REST API.
Example
cURL(Windows)
curl --request POST
http://15.20.184.119:8089/rest/zapi/latest/folder/create ^ --user "admin:password" ^ --header "Content-Type:application/json" ^ --data "{\"cycleId\": 1500, \"name\": \"My Folder (cloned)\", \"projectId\": 10600, \"versionId\": -1, \"clonedFolderId\": 875}"curl --request POST http://15.20.184.119:8089/rest/zapi/latest/folder/create ^
--user "admin:password" ^
--header "Content-Type:application/json" ^
--data "{\"cycleId\": 1500, \"name\": \"My Folder\", \"description\": \"A new folder for the cycle\", \"projectId\": 10600, \"versionId\": -1, \"clonedFolderId\": -1}"
Operation reference
Response
A successful response has the HTTP status 200 OK. Its body contains the JSON object with properties of the created folder, for example:
{
"id": 872,
"responseMessage": "Folder My Folder created successfully.",
"projectId": 10600,
"versionId": -1,
"projectKey": "SAM",
"versionName": "Unscheduled",
"cycleId": 1508,
"cycleName": "Cycle1"
}Description of response properties
Property | Description |
|---|---|
| The ID of the new folder. |
| The message describing the result. |
| The project and version identifiers (the same that you specified in the request). |
| The “visual” ID of the project. This key is part of Jira’s issue keys. For instance, in |
| The name of the version (release). |
| The ID of the cycle to which the new folder belongs. |
| The name of the cycle to which the folder belongs. |
In case of an error, the server returns 4xx or 5xx response code. The response body contains the description of the error (with certain exceptions). Here are some examples:
If the request specifies the folder name that coincides with the name of another folder in the cycle, the response code will be
400 Bad requestand the response body will contain the error description:If the request body has invalid project ID or version ID, the response code will be
400 Bad request, and the response body will contain the error description:{ "error": "projectId is Invalid." }Invalid JSON data in the request body causes an error on the server. In this case, the response code will be
500 Internal Server Error, and the response body will contain the exception text and the call stack.If the request has invalid authentication parameters, the response will be
401 Unauthorizedwith no body.
Creating a folder by cloning
You can create a new folder by cloning some other existing folder. To do this, use the POST /rest/zapi/latest/folder/create request described above. In the response body, use the "clonedFolderId" property to set the identifier of the source folder, and specify the parameters needed for cloning, for example:
{
"cycleId": 1500,
"name": "(cloned) My Folder",
"projectId": 10600,
"versionId": -1,
"clonedFolderId": 875
}All these properties are required. Below is their description.
Property description
Property | Description |
|---|---|
| Number. The ID of the source folder. You can get this ID from the response to the API request that created this folder. See also other ways to get this ID. |
| String. The name of the new folder. |
| Number. The target cycle ID (the cycle can differ from the cycle to which the source folder belongs). See how to get this ID. |
| Number. The ID of the Jira project to which the cycle and new folder belong. See how to get this ID. |
| Number. The ID of the Jira project version (version or release) to which the cycle and new folder belong. See how to get this ID. |
Example
curl --request POST http://15.20.184.119:8089/rest/zapi/latest/folder/create ^
--user "admin:password" ^
--header "Content-Type:application/json" ^
--data "{\"cycleId\": 1500, \"name\": \"My Folder (cloned)\", \"projectId\": 10600, \"versionId\": -1, \"clonedFolderId\": 875}"Response
The request returns the 200 OK response with the following body:
{
"jobProgressToken": "0001638279127920-abc80545a0e-0001"
}The jobProgressToken field is the job ID that you pass to the GET /rest/zapi/latest/execution/jobProgress/{jobProgressToken}?type=bulk_execution_copy_move_job_progress request to get the result of the cloning.
