Helix Core is now P4 and Helix Swarm is now P4 Code Review. Learn more >>

Documentation | 2025.2

# Workflows : Controller for querying, creating and updating workflows

From P4 Code Review 2022.2, P4 Code Review no longer supports APIs older than v9.

## Get workflows

### Summary

Gets workflows

GET /api/v9/workflows/

### Description

Get all workflows

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
fields | An optional comma-separated list (or array) of fields to show for each workflow. Omitting this parameter or passing an empty value shows all fields. | string | query | No
noCache | If provided and has a value of 'true' a query will always be performed and the cache of workflows is ignored. Otherwise the cache will be used if it exists. | boolean | query | No

### Usage example

#### Get a list of workflows

    curl -u "username:password" "https://my-swarm-host/api/v9/workflows"

JSON Response:

    HTTP/1.1 200 OK

    {
        "workflows": [
            {
                "on_submit":{
                    "without_review":{
                        "rule": "no_checking"
                    },
                    "with_review":{
                        "rule": "no_checking"
                    }
                },
                "name": "myWorkflow",
                "description": "A description",
                "shared": "true",
                "owners": [
                    "user1",
                    "user2"
                ],
                "end_rules":{
                    "update":{
                        "rule":"no_revision"
                    }
                },
                "auto_approve":{
                    "rule": "never"
                },
                "counted_votes":{
                    "rule": "anyone"
                },
                "group_exclusions":{
                    "rule": [ ]
                },
                "user_exclusions":{
                    "rule": [ ]
                },
                "id": "1"
            },
            {
                "on_submit":{
                    "without_review":{
                        "rule": "no_checking"
                    },
                    "with_review":{
                        "rule": "no_checking"
                    }
                },
                "name": "myWorkflow 2",
                "description": "Another description",
                "shared": "true",
                "owners": [
                    "user3",
                    "user4"
                ],
                "end_rules":{
                    "update":{
                        "rule":"no_revision"
                    }
                },
                "auto_approve":{
                    "rule": "votes"
                },
                "counted_votes": {
                    "rule": "members"
                },
                "group_exclusions":{
                    "rule": [ ]
                },
                "user_exclusions":{
                    "rule": [ ]
                },
                "id": "2"
            },
        ]
    }

## Get a workflow by id

### Summary

Gets a workflow by id

GET /api/v9/workflows/{id}

### Description

Gets a workflow by id

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
fields | An optional comma-separated list (or array) of fields to show for each workflow. Omitting this parameter or passing an empty value shows all fields. | string | query | No

### Example usage

#### Get a workflows by id

    curl -u "username:password" "https://my-swarm-host/api/v9/workflows/1"

JSON Response:

    HTTP/1.1 200 OK

    {
        "workflows": [
            "on_submit":{
                "without_review":{
                    "rule": "no_checking"
                },
                "with_review":{
                    "rule": "no_checking"
                }
            },
            "name": "myWorkflow",
            "description": "A description",
            "shared": "true",
            "owners": [
                "user1",
                "user2"
            ],
            "end_rules":{
                "update":{
                    "rule":"no_revision"
                }
            },
            "auto_approve":{
                "rule": "never"
            },
            "counted_votes":{
                "rule": "anyone"
            },
            "group_exclusions":[ ],
                "rule": [ ]
            },
            "user_exclusions":[ ],
                "rule": [ ]
            },
            "id": "1"
        }
    }

## Create a workflow

### Summary

Create a workflow

POST /api/v9/workflows/

### Description

Create a new workflow.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
name | The workflow name. Will be compared against other workflows and rejected if not unique | string | form | Yes
description | Description for the new workflow | string | form | No
shared | Whether this workflow is shared for other users that do not own it. Defaults to not shared | boolean | form | No
owners | A list owners for the workflow. Can be users or group names (prefixed with swarm-group-). Users and group names must exist or the workflow will be rejected | array (of strings) | form | No
on_submit | Data for rules when changes are submitted. Valid values for with_review are no_checking, approved, strict. Valid values for without review are no_checking, auto_create, reject | array | form | No
end_rules | Data for rules when changes are submitted. Valid values are no_checking, no_revision. | array | form | No
auto_approve | Data for rules when changes are submitted. Valid values are votes, never. | array | form | No
counted_votes | Data for rules when counting votes up. Valid values are anyone, members. | array | form | No

### Example usage

#### Create a workflow

    curl -u "username:password" \
         -X POST \
         -d "on_submit[with_review][rule]=no_checking" \
         -d "on_submit[without_review][rule]=no_checking" \
         -d "name=myWorkflow" \
         -d "description=A description" \
         -d "shared=true" \
         -d "owners[]=Francois_Piccard" \
         -d "owners[]=Anna_Schmidt" \
         -d "end_rules[update][rule]=no_checking" \
         -d "auto_approve:[rule]never" \
         -d "counted_votes:[rule]members" \
         "https://my-swarm-host/api/v9/workflows"

JSON Response:

    HTTP/1.1 200 OK

    {
        "workflow":{
            "on_submit":{
                "with_review":{
                    "rule":"no_checking"
                },
                "without_review":{
                    "rule":"no_checking"
                }
            },
            "name":"myWorkflow",
            "description":"A description",
            "shared":true,
            "owners":[
                "Anna_Schmidt",
                "Francois_Piccard"
            ],
            "end_rules":{
                "update":{
                    "rule":"no_checking"
                }
            },
            "auto_approve":{
                "rule":"never"
            },
            "counted_votes":{
                "rule":"members"
            },
            "group_exclusions":[ ],
                "rule": [ ]
            },
            "user_exclusions":[ ],
                "rule": [ ]
            },
            "id":1
        }
    }

## Patch a workflow

### Summary

Patch a workflow

PATCH /api/v9/workflows/{id}

### Description

Patch a workflow.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | The id of the workflow being patched | string | form | Yes
name | The workflow name. Will be compared against other workflows and rejected if not unique | string | form | No
description | Description for the new workflow | string | form | No
shared | Whether this workflow is shared for other users that do not own it. Defaults to not shared | boolean | form | No
owners | A list owners for the workflow. Can be users or group names (prefixed with swarm-group-). Users and group names must exist or the workflow will be rejected | array (of strings) | form | No
on_submit | Data for rules when changes are submitted. Valid values for with_review are no_checking, approved, strict. Valid values for without review are no_checking, auto_create, reject | array | form | No
end_rules | Data for rules when changes are submitted. Valid values are no_checking, no_revision. | array | form | No
auto_approve | Data for rules when changes are submitted. Valid values are votes, never. | array | form | No
counted_votes | Data for rules when counting votes up. Valid values are anyone, members. | array | form | No

### Example usage

#### Patch workflow name and description

    curl -u "username:password" \
         -X PATCH \
         -d "name=myWorkflow" \
         -d "description=A description" \
         "https://my-swarm-host/api/v9/workflows/1"

JSON Response:

    HTTP/1.1 200 OK

    {
        "workflow":{
            "on_submit":{
                "with_review":{
                    "rule":"no_checking"
                },
                "without_review":{
                    "rule":"no_checking"
                }
            },
            "name":"myWorkflow",
            "description":"A description",
            "shared":false,
            "owners":[
                "bruno"
            ],
            "end_rules":{
                "update":{
                    "rule":"no_revision"
                }
            },
            "auto_approve":{
                "rule":"votes"
            },
            "counted_votes":{
                "rule":"members"
            },
            "group_exclusions":[ ],
                "rule": [ ]
            },
            "user_exclusions":[ ],
                "rule": [ ]
            },
            "id":1
        }
    }

#### Patch on_submit with_review

    curl -u "username:password" \
         -X PATCH \
         -d "on_submit[with_review][rule]=no_checking" \
         "https://my-swarm-host/api/v9/workflows/1"

JSON Response:

    HTTP/1.1 200 OK

    {
        "workflow":{
            "on_submit":{
                "with_review":{
                    "rule":"no_checking"
                },
                "without_review":{
                    "rule":"no_checking"
                }
            },
            "name":"test",
            "description":"test line 2",
            "shared":false,
            "owners":[
                "bruno"
            ],
            "end_rules":{
                "update":{
                    "rule":"no_revision"
                }
            },
            "auto_approve":{
                "rule":"votes"
            },
            "counted_votes":{
                "rule":"members"
            },
            "group_exclusions":[ ],
                "rule": [ ]
            },
            "user_exclusions":[ ],
                "rule": [ ]
            },
            "id":1
        }
    }

#### Patch on_submit without_review

    curl -u "username:password" \
         -X PATCH \
         -d "on_submit[without_review][rule]=no_checking" \
         "https://my-swarm-host/api/v9/workflows/1"

JSON Response:

    HTTP/1.1 200 OK

    {
        "workflow":{
            "on_submit":{
                "with_review":{
                    "rule":"no_checking"
                },
                "without_review":{
                    "rule":"no_checking"
                }
            },
            "name":"test",
            "description":"test line 2",
            "shared":false,
            "owners":[
                "bruno"
            ],
            "end_rules":{
                "update":{
                    "rule":"no_revision"
                }
            },
            "auto_approve":{
                "rule":"votes"
            },
            "counted_votes":{
                "rule":"members"
            },
            "group_exclusions":[ ],
                "rule": [ ]
            },
            "user_exclusions":[ ],
                "rule": [ ]
            },
            "id":1
        }
    }

#### Patch Auto_approve

    curl -u "username:password" \
         -X PATCH \
         -d "auto_approve[rule]=never" \
         "https://my-swarm-host/api/v9/workflows/1"

JSON Response:

    HTTP/1.1 200 OK

    {
        "workflow":{
            "on_submit":{
                "with_review":{
                    "rule":"no_checking"
                },
                "without_review":{
                    "rule":"no_checking"
                }
            },
            "name":"test",
            "description":"test line 2",
            "shared":false,
            "owners":[
                "bruno"
            ],
            "end_rules":{
                "update":{
                    "rule":"no_revision"
                }
            },
            "auto_approve":{
                "rule":"never"
            },
            "counted_votes":{
                "rule":"members"
            },
            "group_exclusions":[ ],
                "rule": [ ]
            },
            "user_exclusions":[ ],
                "rule": [ ]
            },
            "id":1
        }
    }

#### Patch counted_votes

    curl -u "username:password" \
         -X PATCH \
         -d "counted_votes[rule]=anyone" \
         "https://my-swarm-host/api/v9/workflows/1"

JSON Response:

    HTTP/1.1 200 OK

    {
        "workflow":{
            "on_submit":{
                "with_review":{
                    "rule":"no_checking"
                },
                "without_review":{
                    "rule":"no_checking"
                }
            },
            "name":"test",
            "description":"test line 2",
            "shared":false,
            "owners":[
                "bruno"
            ],
            "end_rules":{
                "update":{
                    "rule":"no_revision"
                }
            },
            "auto_approve":{
                "rule":"never"
            },
            "counted_votes":{
                "rule":"anyone"
            },
            "group_exclusions":[ ],
                "rule": [ ]
            },
            "user_exclusions":[ ],
                "rule": [ ]
            },
            "id":1
        }
    }

#### Patch end_rules

    curl -u "username:password" \
         -X PATCH \
         -d "end_rules[update][rule]=no_checking" \
         "https://my-swarm-host/api/v9/workflows/1"

JSON Response:

    HTTP/1.1 200 OK

    {
        "workflow":{
            "on_submit":{
                "with_review":{
                    "rule":"no_checking"
                },
                "without_review":{
                    "rule":"no_checking"
                }
            },
            "name":"test",
            "description":"test line 2",
            "shared":false,
            "owners":[
                "bruno"
            ],
            "end_rules":{
                "update":{
                    "rule":"no_checking"
                }
            },
            "auto_approve":{
                "rule":"never"
            },
            "counted_votes":{
                "rule":"members"
            },
            "group_exclusions":[ ],
                "rule": [ ]
            },
            "user_exclusions":[ ],
                "rule": [ ]
            },
            "id":1
        }
    }

#### Patch shared

    curl -u "username:password" \
         -X PATCH \
         -d "shared=true" \
         "https://my-swarm-host/api/v9/workflows/1"

JSON Response:

    HTTP/1.1 200 OK

    {
        "workflow":{
            "on_submit":{
                "with_review":{
                    "rule":"no_checking"
                },
                "without_review":{
                    "rule":"no_checking"
                }
            },
            "name":"test",
            "description":"test line 2",
            "shared":true,
            "owners":[
                "bruno"
            ],
            "end_rules":{
                "update":{
                    "rule":"no_checking"
                }
            },
            "auto_approve":{
                "rule":"never"
            },
            "counted_votes":{
                "rule":"anyone"
            },
            "group_exclusions":[ ],
                "rule": [ ]
            },
            "user_exclusions":[ ],
                "rule": [ ]
            },
            "id":1
        }
    }

#### Patch Owners

    curl -u "username:password" \
         -X PATCH \
         -d "owners[]=Francois_Piccard" \
         -d "owners[]=Anna_Schmidt" \
         -d "owners[]=bruno" \
         "https://my-swarm-host/api/v9/workflows/1"

JSON Response:

    HTTP/1.1 200 OK

    {
        "workflow":{
            "on_submit":{
                "with_review":{
                    "rule":"no_checking"
                },
                "without_review":{
                    "rule":"no_checking"
                }
            },
            "name":"test",
            "description":"test line 2",
            "shared":true,
            "owners":[
                "Anna_Schmidt",
                "Francois_Piccard",
                "bruno"
            ],
            "end_rules":{
                "update":{
                    "rule":"no_checking"
                }
            },
            "auto_approve":{
                "rule":"never"
            },
            "counted_votes":{
                "rule":"anyone"
            },
            "group_exclusions":[ ],
                "rule": [ ]
            },
            "user_exclusions":[ ],
                "rule": [ ]
            },
            "id":1
        }
    }

## Update a workflow

### Summary

Update a workflow

PUT /api/v9/workflows/{id}

### Description

Update a workflow. All values should be provided in the request. If not provided any missing values are reverted to default.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | The id of the workflow being patched | string | form | Yes
name | The workflow name. Will be compared against other workflows and rejected if not unique | string | form | Yes
owners | A list owners for the workflow. Can be users or group names (prefixed with swarm-group-). Users and group names must exist or the workflow will be rejected | array (of strings) | form | No
description | Description for the new workflow | string | form | No
shared | Whether this workflow is shared for other users that do not own it. Defaults to not shared | boolean | form | No
on_submit | Data for rules when changes are submitted. Valid values for with_review are no_checking, approved, strict. Valid values for without review are no_checking, auto_create, reject | array | form | No
end_rules | Data for rules when changes are submitted. Valid values are no_checking, no_revision. | array | form | No
auto_approve | Data for rules when changes are submitted. Valid values are votes, never. | array | form | No
counted_votes | Data for rules when counting votes up. Valid values are anyone, members. | array | form | No

### Example usage

#### Update a workflow

    curl -u "username:password" \
         -X PUT \
         -d "on_submit[with_review][rule]=no_checking" \
         -d "on_submit[without_review][rule]=no_checking" \
         -d "name=myWorkflow" \
         -d "description=A description" \
         -d "shared=true" \
         -d "owners[]=Francois_Piccard" \
         -d "owners[]=Anna_Schmidt" \
         "https://my-swarm-host/api/v9/workflows/1"

JSON Response:

    HTTP/1.1 200 OK

    {
        "workflow":{
            "on_submit":{
                "with_review":{
                    "rule":"no_checking"
                },
                "without_review":{
                    "rule":"no_checking"
                }
            },
            "name":"myWorkflow",
            "description":"A description",
            "shared":true,
            "owners":[
                "Anna_Schmidt",
                "Francois_Piccard"
            ],
            "end_rules":{
                "update":{
                    "rule":"no_checking"
                }
            },
            "auto_approve":{
                "rule":"never"
            },
            "counted_votes":{
                "rule":"anyone"
            },
            "group_exclusions":[ ],
                "rule": [ ]
            },
            "user_exclusions":[ ],
                "rule": [ ]
            },
            "id":1
        }
    }

## Delete a workflow

### Summary

Delete a workflow

DELETE /api/v9/workflows/{id}

### Description

Delete a workflow for the provided id. This call must be authenticated and the user must have permission to edit the workflow. If the workflow is in use it cannot be deleted and an error message will be returned.

- Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the P4 Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
- Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | The id of the workflow being deleted | string | form | Yes

### Example usage

#### Delete a workflow not in use

    curl -u "username:password" -X DELETE "https://my-swarm-host/api/v9/workflows/1"

JSON Response

    HTTP/1.1 200 OK

    {
        "isValid": true,
        "messages": [
            "Workflow [1] was deleted"
        ]
    }

#### Delete a workflow that is in use on public projects

    curl -u "username:password" -X DELETE "https://my-swarm-host/api/v9/workflows/1"

JSON Response

    HTTP/1.1 200 OK

    {
        "isValid": false,
        "messages": [
            "Cannot delete workflow [1], it is in use on project [project1, project2]"
        ]
    }

#### Delete a workflow that is in use on a public and some private projects

    curl -u "username:password" -X DELETE "https://my-swarm-host/api/v9/workflows/1"

JSON Response

    HTTP/1.1 200 OK

    {
        "isValid": false,
        "messages": [
            "Cannot delete workflow [1], it is in use on project [project1] and others"
        ]
    }

#### Delete a workflow that is in use on only private projects

    curl -u "username:password" -X DELETE "https://my-swarm-host/api/v9/workflows/1"

JSON Response

    HTTP/1.1 200 OK

    {
        "isValid": false,
        "messages": [
            "Cannot delete workflow [1], it is in use"
        ]
    }

Your search for returned results