Add Folders to Cycles

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

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/create

Request 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
cycleId

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.

projectId

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

versionId

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 "versionId": -1.

name

String. The name of the new folder. It cannot coincide with the name of an existing folder in the cycle.

description

String. Arbitrary text describing the folder.

clonedFolderId

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 "clonedFolderId": -1.

Other request parameters

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

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\", \"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"
}

Property Description
Id

The ID of the new folder.

responseMessage

The message describing the result.

projectId,
versionId

The project and version identifiers (the same that you specified in the request).

projectKey

The “visual” ID of the project. This key is part of Jira’s issue keys. For instance, in PROJ-1234, the PROJ substring is the project key.

versionName

The name of the version (release).

cycleId

The ID of the cycle to which the new folder belongs.

cycleName

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 request and the response body will contain the error description:

    {
        "error": "Folder name - My Folder should be unique"
    }

  • 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 Unauthorized with 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
clonedFolderId

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.

name

String. The name of the new folder.

cycleId

Number. The target cycle ID (the cycle can differ from the cycle to which the source folder belongs). See how to get this ID.

projectId

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

versionId

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.

Next steps

See Also

Zephyr Squad Server REST API

Highlight search results