Documentation | 2025.1

# Workflows : Swarm workflows

## Get workflows

### Summary

Gets workflows

GET /api/v11/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:ticket" "https://myswarm-url/api/v11/workflows"

JSON Response:

The global workflow has an id of 0.

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "workflows": [
            {
                "on_submit":{
                    "with_review":{
                        "rule": "no_checking",
                        "mode": "default"
                    },
                    "without_review":{
                        "rule": "no_checking",
                        "mode": "policy"
                    }
                },
                "name": "Global Workflow",
                "description": "This is the Global workflow",
                "shared": "false",
                "owners": [
                    "swarm"
                ],
                "end_rules":{
                    "update":{
                        "rule":"no_checking",
                        "mode": "default"
                    }
                },
                "auto_approve":{
                    "rule": "never",
                    "mode": "default"
                },
                "counted_votes":{
                    "rule": "anyone",
                    "mode": "default"
                },
                "group_exclusions":{
                    "rule": [ ],
                    "mode": "policy"
                },
                "user_exclusions":{
                    "rule": [ ],
                    "mode": "policy"
                },
                "tests": [],
                "id": "0"
            },
            {
                "on_submit":{
                    "with_review":{
                        "rule": "no_checking",
                        "mode": "inherit"
                    },
                    "without_review":{
                        "rule": "no_checking",
                        "mode": "inherit"
                    }
                },
                "name": "myWorkflow 1",
                "description": "Another description",
                "shared": "true",
                "owners": [
                    "user3",
                    "user4"
                ],
                "end_rules":{
                    "update":{
                        "rule":"no_revision",
                        "mode": "inherit"
                    }
                },
                "auto_approve":{
                    "rule": "votes",
                    "mode": "inherit"
                },
                "counted_votes": {
                    "rule": "members",
                    "mode": "inherit"
                },
                "tests": [],
                "id": "1"
            },
        ]
    }

#### If a request fails

<error code>:

501 Workflows are not enabled. To enable workflows, see workflow

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

## Get a workflow by id

### Summary

Gets a workflow by id

GET /api/v11/workflows/{id}

### Description

Gets a workflow by id. The global workflow id is 0.

### 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:ticket" "https://my-swarm-host/api/v11/workflows/1"

JSON Response:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "workflows": [
            {
                "on_submit":{
                    "with_review":{
                        "rule": "no_checking",
                        "mode": "inherit"
                    },
                    "without_review":{
                        "rule": "no_checking",
                        "mode": "inherit"
                    }
                },
                "name": "myWorkflow 1",
                "description": "Another description",
                "shared": "true",
                "owners": [
                    "user3",
                    "user4"
                ],
                "end_rules":{
                    "update":{
                        "rule":"no_revision",
                        "mode": "inherit"
                    }
                },
                "auto_approve":{
                    "rule": "votes",
                    "mode": "inherit"
                },
                "counted_votes": {
                    "rule": "members",
                    "mode": "inherit"
                },
                "tests": [],
                "id": "1"
            },
        ]
    }

#### If a request fails

<error code>:

- 401 Insufficient permissions to view the workflow
- 404 Workflow does not exist
- 501 Workflows are not enabled. To enable workflows, see workflow

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

## Get workflow details by workflow name or test id

### Summary

Gets workflow details by workflow name or for workflows associated with a test id

GET /api/v11/workflows

### Description

Gets workflow details by workflow name or for workflows associated with a test id. You can enter multiple workflow names or test ids in the request if required.

If the name and testdefinitions parameters are both in the request, only name is used for the request and the testdefinitions parameter is ignored.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
name | Specify the workflow you want to return details for with the workflow name parameter. To request details for multiple workflows, enter the workflow names as a comma separated list. | string | query | No
testdefinitions | Get details of workflows associated with a test id with the testdefinitions parameter. To request multiple test ids, enter the test ids as a comma separated list. | string | query | No

### Example usage

#### Get details for myWorkflow 1

curl -u "username:ticket" "https://my-swarm-host/api/v11/workflows?name=myWorkflow 1"

JSON Response:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "workflows": [
            {
                "on_submit":{
                    "with_review":{
                        "rule": "no_checking",
                        "mode": "inherit"
                    },
                    "without_review":{
                        "rule": "no_checking",
                        "mode": "inherit"
                    }
                },
                "name": "myWorkflow 1",
                "description": "Another description",
                "shared": "true",
                "owners": [
                    "user3",
                    "user4"
                ],
                "end_rules":{
                    "update":{
                        "rule":"no_revision",
                        "mode": "inherit"
                    }
                },
                "auto_approve":{
                    "rule": "votes",
                    "mode": "inherit"
                },
                "counted_votes": {
                    "rule": "members",
                    "mode": "inherit"
                },
                "tests": [],
                "id": "1"
            },
        ]
    }

#### Get details for workflows associated with test id 1 or test id 2

curl -u "username:ticket" "https://my-swarm-host/api/v11/workflows?testdefinitions=1,2"

JSON Response:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "workflows": [
            {
                "on_submit":{
                    "with_review":{
                        "rule": "no_checking",
                        "mode": "default"
                    },
                    "without_review":{
                        "rule": "no_checking",
                        "mode": "policy"
                    }
                },
                "name": "Our Workflow",
                "description": "This is the our workflow and it is good",
                "shared": "true",
                "owners": [
                    "swarm"
                ],
                "end_rules":{
                    "update":{
                        "rule":"no_checking",
                        "mode": "default"
                    }
                },
                "auto_approve":{
                    "rule": "never",
                    "mode": "default"
                },
                "counted_votes":{
                    "rule": "anyone",
                    "mode": "default"
                },
                "group_exclusions":{
                    "rule": [ ],
                    "mode": "policy"
                },
                "user_exclusions":{
                    "rule": [ ],
                    "mode": "policy"
                },
                "tests": [
                    {
                         "id": 1,
                         "event": "onUpdate"
                         "blocks": "approved"
                    },
                    {
                         "id": 2,
                         "event": "onSubmit"
                         "blocks": "nothing"
                    }
                ],
                "id": "3"
            },
            {
                "on_submit":{
                    "with_review":{
                        "rule": "no_checking",
                        "mode": "inherit"
                    },
                    "without_review":{
                        "rule": "no_checking",
                        "mode": "inherit"
                    }
                },
                "name": "Another Workflow",
                "description": "Yet another workflow description",
                "shared": "false",
                "owners": [
                    "user3",
                    "user4"
                ],
                "end_rules":{
                    "update":{
                        "rule":"no_revision",
                        "mode": "inherit"
                    }
                },
                "auto_approve":{
                    "rule": "votes",
                    "mode": "inherit"
                },
                "counted_votes": {
                    "rule": "members",
                    "mode": "inherit"
                },
                "tests": [
                    {
                         "id": 2,
                         "event": "onSubmit"
                         "blocks": "approved"
                    },
                    {
                         "id": 5,
                         "event": "onSubmit"
                         "blocks": "approved"
                    }
                ],
                "id": "6"
            },
        ]
    }

#### If a request fails

<error code>:

- 401 Insufficient permissions to view the workflow
- 404 Workflow or id does not exist
- 501 Workflows are not enabled. To enable workflows, see workflow

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

## Create a workflow

### Summary

Create a workflow

POST /api/v11/workflows/

### Description

Create a new workflow.

The global workflow is present by default so it can only be edited.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
name | The workflow name. Will be compared against other workflows and rejected if not unique. | string | body | Yes
description | Description for the new workflow. | string | body | Yes
shared | Whether this workflow is shared for other users that do not own it. Defaults to not shared. | boolean | body | 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) | body | Yes
mode | Each workflow rule must have a mode parameter. The only valid value for mode is inherit. | string | body | Yes
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 | body | Yes
end_rules | Data for rules when changes are submitted. Valid values are no_checking, no_revision. | array | body | Yes
auto_approve | Data for rules when changes are submitted. Valid values are votes, never. | array | body | Yes
counted_votes | Data for rules when counting votes up. Valid values are anyone, members. | array | body | Yes
tests | A list of test ids for the workflow. Each test id has an event that determines when the test is run and a blocks value that determines whether a test failure blocks review approval. Valid values for event are onUpdate, onSubmit. Valid values for blocks are nothing and approved. | array | body | No

### Example usage

#### Create a workflow

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

The "mybodyfilename.txt" file contains the information for the new workflow:

    {
      "name": "My workflow"
      "description": "This is my workflow."
      "shared": "true"
      "owners": "Francois_Piccard,Anna_Schmidt"
      "on_submit":{
          "with_review":{
              "rule":"no_checking",
              "mode": "inherit"
          },
          "without_review":{
              "rule":"no_checking",
              "mode": "inherit"
          }
      },
      "end_rules": {
          "update":{
              "rule":"no_revision",
              "mode": "inherit"
          }
      },
      "auto_approve":{
          "rule": "never",
          "mode": "inherit"
      },
      "counted_votes": {
          "rule": "members",
          "mode": "inherit"
      },
      "tests": [
          {
               "id": 2,
               "event": "onUpdate"
               "blocks": "nothing"
          },
          {
               "id": 5,
               "event": "onSubmit"
               "blocks": "approved"
          }
      ]
    }

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "workflows": [
            {
                "on_submit":{
                    "with_review":{
                        "rule": "no_checking",
                        "mode": "inherit"
                    },
                    "without_review":{
                        "rule": "no_checking",
                        "mode": "inherit"
                    }
                },
                "name": "My workflow",
                "description": "This is my workflow.",
                "shared": "true",
                "owners": [
                    "Francois_Piccard",
                    "Anna_Schmidt"
                ],
                "end_rules":{
                    "update":{
                        "rule":"no_revision",
                        "mode": "inherit"
                    }
                },
                "auto_approve":{
                    "rule": "votes",
                    "mode": "inherit"
                },
                "counted_votes": {
                    "rule": "members",
                    "mode": "inherit"
                },
                "tests": [
                    {
                         "id": 2,
                         "event": "onUpdate"
                         "blocks": "nothing"
                    },
                    {
                         "id": 5,
                         "event": "onSubmit"
                         "blocks": "approved"
                    }
                ],
                "id": "2"
            },
        ]
    }

#### If a request fails

<error code>:

- 400 Invalid parameter data specified
- 401 Insufficient permissions to create a workflow
- 501 Workflows are not enabled. To enable workflows, see workflow

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

## Update a workflow

### Summary

Update a workflow

PUT /api/v11/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 updated | integer | path | Yes
name | The workflow name. Will be compared against other workflows and rejected if not unique | string | body | 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) | body | Yes
description | Description for the new workflow | string | body | Yes
shared | Whether this workflow is shared for other users that do not own it. Defaults to not shared | boolean | body | Yes
mode | Workflow rules: Each workflow rule must have a mode parameter. The only valid value for mode is inherit. Global workflow rules only: default applies the workflow rule setting to projects and project branches that don't have an associated workflow. If a project or project branch has an associated Swarm workflow, the global rule is ignored. policy applies a minimum workflow rule setting to all projects and project branches. If a project or project branch has an associated workflow, the global rule is merged with the workflow rule and the most restrictive setting is used. Displayed as Enforce on in the Swarm UI, see Global workflow. | string | body | Yes
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 | body | Yes
end_rules | Data for rules when changes are submitted. Valid values are no_checking, no_revision. | array | body | Yes
auto_approve | Data for rules when changes are submitted. Valid values are votes, never. | array | body | Yes
counted_votes | Data for rules when counting votes up. Valid values are anyone, members. | array | body | Yes
tests | A list of test ids for the workflow. Each test id has an event that determines when the test is run and a blocks value that determines whether a test failure blocks review approval. Valid values for event are onUpdate, onSubmit. Valid values for blocks are nothing and approved. | array | body | No

### Example usage

#### Update a workflow

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

The "mybodyfilename.txt" file contains the updated workflow information:

    {
      "name": "My workflow",
      "description": "This is my workflow and I have changed the description of it.",
      "shared": "true",
      "owners": ["Francois_Piccard,Anna_Schmidt"],
      "on_submit":{
          "with_review":{
              "rule":"no_checking",
              "mode": "inherit"
          },
          "without_review":{
              "rule":"no_checking",
              "mode": "inherit"
          }
      },
      "end_rules": {
          "update":{
              "rule":"no_revision",
              "mode": "inherit"
          }
      },
      "auto_approve":{
          "rule": "never",
          "mode": "inherit"
      },
      "counted_votes": {
          "rule": "members",
          "mode": "inherit"
      },
      "tests": [{
                    "id": 2,
                    "event": "onUpdate",
                    "blocks": "nothing"
                },
                {
                    "id": 5,
                    "event": "onSubmit",
                    "blocks": "approved"
                }
         ]
    }

JSON Response:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
              "workflows": [{
                      "on_submit":{
                              "with_review":{
                                      "rule": "no_checking",
                                      "mode": "inherit"
                              },
                              "without_review":{
                                      "rule": "no_checking",
                                      "mode": "inherit"
                              }
                },
                "name": "My workflow",
                "description": "This is my workflow and I have changed the description of it.",
                "shared": "true",
                "owners": [
                        "Francois_Piccard",
                        "Anna_Schmidt"
                ],
                "end_rules":{
                       "update":{
                               "rule":"no_revision",
                               "mode": "inherit"
                       }
                },
                "auto_approve":{
                        "rule": "votes",
                        "mode": "inherit"
                },
                "counted_votes": {
                        "rule": "members",
                        "mode": "inherit"
                },
                "tests": [
                {
                            "id": 2,
                            "event": "onUpdate",
                            "blocks": "nothing"
                         },
                         {
                         "id": 5,
                         "event": "onSubmit",
                         "blocks": "approved"
                         }
                ],
                "id": "2"
            }]
        }
    }

#### If a request fails

<error code>:

- 400 Invalid parameter data specified
- 401 Insufficient permissions to update the workflow
- 404 Workflow does not exist or you do not have permission to update the workflow
- 501 Workflows are not enabled. To enable workflows, see workflow

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

## Delete a workflow

### Summary

Delete a workflow

DELETE /api/v11/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. The global workflow cannot be deleted.

### Parameters

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

### Example usage

#### Delete a workflow that is not in use by a project

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

JSON Response

    HTTP/1.1 200

    {
      "error": null,
      "messages": [
        "Workflow [1] was deleted"
      ],
      "data": null
    }

#### If a request fails

<error code>:

- 401 Insufficient permissions to delete the workflow
- 403 Cannot delete the global workflow
- 404 Workflow does not exist or you do not have permission to view this workflow
- 501 Workflows are not enabled. To enable workflows, see workflow

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

Your search for returned results