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.
|
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:
|
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.
|
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 |
---|---|---|---|---|
|
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
}