Checklist definitions

On this page:

Create a checklist

Summary

Create a checklist.

POST /api/v11/checkListDefinitions

Description

Create a new checklist.

Parameters

Parameter	Description	Type	Parameter Type	Required
`name`	Name of the checklist definition.	string	body	Yes
`description`	Description of the checklist.	string	body	Yes
`owners`	Owners of the checklist.	array of strings	body	Yes
`reviewBlockingEnabled`	If `true`, `reviewBlockingStatuses` cannot be a blank array.	boolean	body	Yes
`reviewBlockingStatuses`	Array that is blank `[]` or that contains of any combination of these strings: `"fail"`, `"warning"`, `"error"`, `"inprogress`", `"pass"`, `"notapplicable"`.	array	body	Yes
`disallowAuthorChangeItemStatus`	Whether the review author is allowed to change the status of a checklist item in this checklist. Default is `false`.	boolean	body	No
`shared`	Whether the checklist is shared with other users. If `true`, all users can see and use the checklist, but only owners and super users can edit the checklist definition.	boolean	body	Yes
`items`	List of checklist items to include in the definition.	array	body	Yes

Example usage

Create a configuration

curl -X POST -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v11/checkListDefinitions/"

The mybodyfilename.txt file contains the create configuration details. Note that line 7 is optional unless you want to set disallowAuthorChangeItemStatus to false because by default the review author is blocked from changing the status of any checklist item in a checklist definition.

Copy

1
2
3
4
5
6
7
8
9
10
{
    "name": "checklist",
    "description": "this is functionality description",
    "owners": ["bruno", "dai"],
    "reviewBlockingEnabled": true,
    "reviewBlockingStatuses": ["fail"],
    "disallowAuthorChangeItemStatus": true,
    "shared": false,
    "items": []
}

JSON Response:

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
    "error": null,
    "messages": [],
    "data": {
        "checkListDefinition": [
            {
                "id": 11,
                "name": "checklist fpr invalid status",
                "description": "this is functionality description",
                "owners": [
                    "bruno",
                    "dai"
                ],
                "shared": false,
                "reviewBlockingEnabled": true,
                "reviewBlockingStatuses": [
                    "fail"
                ],
                "disallowAuthorChangeItemStatus": true,
                "items": [],
                "iterate": false
            }
        ]
    }
}

If the request fails

<error code>:

400 such as:

A check list definition with this name exists already.
owners value is required and can't be empty.
reviewBlockingStatuses cannot be empty when reviewBlockingEnabled is true.

Get a checklist definition

Summary

Get information about the specified checklist.

GET /api/v11/checkListDefinitions/2

Description

Returns information about the checklist definition corresponding to the specified checklist id number.

If shared is false (see line 15 in the example), the checklist definition is visible only to the owners of checklist definition. To learn more, see Hiding P4 Code Review storage from regular users.

Example usage

curl -u "username:password" "https://my-swarm-host/api/v11/checkListDefinitions/2

JSON Response:

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
    "error": null,
    "messages": [],
    "data": {
        "checkListDefinition": [
            {
                "id": 2,
                "name": "NewCheckList123",
                "description": "This is new checklist which will be used to review code from senior perspective",
                "owners": [
                    "Aruna_Gupta",
                    "bruno",
                    "dai"
                ],
                "shared": false,
                "reviewBlockingEnabled": true,
                "reviewBlockingStatuses": [
                    "fail",
                    "inprogress",
                    "warning",
                    "error"
                ],
                "workflows": [
                    {
                        "id": 1,
                        "name": "DummyDemoTest"
                    }
                ]
            }
        ]
    }
}

If a request fails

<error code>:

404 Cannot fetch entry. Id does not exist.

Get a list of checklist definitions

Summary

Get the list of checklist definitions.

Description

Returns information about the available checklist definitions.

GET /api/v11/checkListDefinitions

Example usage

GET /api/v11/checkListDefinitions

JSON Response:

Copy

{
    "error": null,
    "messages": [],
    "data": {
        "checkListDefinition": [
            {
                "id": 2,
                "name": "NewCheckList123",
                "description": "This is new checklist which will be used to review code from senior perspective",
                "owners": [
                    "Aruna_Gupta",
                    "bruno",
                    "dai"
                ],
                "shared": false,
                "reviewBlockingEnabled": true,
                "reviewBlockingStatuses": [
                    "fail",
                    "inprogress",
                    "warning",
                    "error"
                ],
                "totalWorkflowsCount": 1
            },
            {
                "id": 7,
                "name": "Another Checklist",
                "description": "This is another Checklist",
                "owners": [
                    "bruno"
                ],
                "shared": false,
                "reviewBlockingEnabled": false,
                "reviewBlockingStatuses": [],
                "totalWorkflowsCount": 1
            },
            {
                "id": 8,
                "name": "checklist 12345",
                "description": "this is functionality description",
                "owners": [
                    "bruno",
                    "dai"
                ],
                "shared": false,
                "reviewBlockingEnabled": true,
                "reviewBlockingStatuses": [
                    "fail",
                    "error"
                ],
                "totalWorkflowsCount": 0
            },
            {
                "id": 9,
                "name": "NewCheckListFor",
                "description": "",
                "owners": [
                    "bruno"
                ],
                "shared": false,
                "reviewBlockingEnabled": false,
                "reviewBlockingStatuses": [],
                "totalWorkflowsCount": 0
            },
            {
                "id": 10,
                "name": "DefaultFailAtCL",
                "description": "",
                "owners": [
                    "bruno"
                ],
                "shared": false,
                "reviewBlockingEnabled": true,
                "reviewBlockingStatuses": [
                    "error",
                    "fail"
                ],
                "totalWorkflowsCount": 0
            }
        ]
    }
}

Patch a checklist

Summary

Update a portion of the specified checklist definition.

PATCH /api/v11/checkListDefinitions/{id}

Description

Update a portion of the checklist definition, such as the name. Only the fields provided in the request body will be modified. All other fields on the resource remain unchanged. In this example, we update the name field.

Parameters

Parameter	Description	Type	Parameter Type	Required
`name`	Identifier for the checklist definition.	string	path	Yes

Example usage

curl -X PATCH -H "Content-Type: application/json" -u "username:ticket" -d "@mybodyfilename.txt" "https://myswarm-url/api/v11/checkListDefinitions/2

The mybodyfilename.txt file contains the fields to update:

Copy

{
    "name": "testPatchChecklist2"
}

JSON Response shows the updates on line 8:

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
    "error": null,
    "messages": [],
    "data": {
        "checkListDefinition": [
            {
                "id": 2,
                "name": "testPatchChecklist2",
                "description": "this is description",
                "owners": [
                    "bruno",
                    "mei"
                ],
                "reviewBlockingEnabled": false,
                "reviewBlockingStatuses": ["fail"],
                "shared": false,
                "items": [],
                "iterate": false
            }
        ]
    }
}

If a request fails

<error code>:

400 A check list definition with this name exists already.

Delete a checklist

Summary

Delete the specified checklist definition.

DELETE /api/v11/checkListDefinitions/{id}

Description

Deletes the specified checklist definition.

Parameters

Parameter	Description	Type	Parameter Type	Required
`id`	Identifier for the checklist definition.	string	path	Yes

Example usage

curl -X DELETE -H "Content-Type: application/json" -u "username:ticket" -d " "https://myswarm-url/api/v11/checkListDefinitions/1

JSON Response:

Copy

{
    "error": null,
    "messages": [
        "CheckList definition with id [1] was deleted"
    ],
    "data": null
}

If a request fails

<error code>:

404 means the check list definition with the specified ID was not found.