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:

Tip

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.

Tip

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.

Tip

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
}