Workflows : Controller for querying, creating and updating workflows
Get workflows
Summary
Gets workflows
GET /api/v9/workflows/
Description
Get all workflows
Parameters
Parameter | Description | Type | Parameter Type | Required |
---|---|---|---|---|
|
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 |
|
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 |
Example response
Successful Response:
HTTP/1.1 200 OK
{
"workflows": [{
"id": "1",
"name": "myWorkflow",
"description": "A description",
"on_submit": {
"with_review": {
"rule": "no_checking"
},
"without_review": {
"rule": "no_checking"
}
},
"auto_approve": {
"rule": "never"
},
"counted_votes": {
"rule": "anyone"
},
"shared": "true",
"owners": [
"user1",
"user2"
]
},
{
"id": "2",
"name": "myWorkflow 2",
"description": "A description" ,
"on_submit": {
"with_review": {
"rule": "no_checking"
},
"without_review": {
"rule": "no_checking"
}
},
"auto_approve": {
"rule": "votes"
},
"counted_votes": {
"rule": "members"
},
"shared": "true",
"owners": [
"user3",
"user4"
]
}
]
}
Usage example
Get a list of workflows
```bash
curl -u "username:password" \
"https://my-swarm-host/api/v9/workflows"
```
JSON Response:
```json
{
"workflows": [{
"id": "1",
"name": "myWorkflow",
"description": "A description",
"on_submit": {
"with_review": {
"rule": "no_checking"
},
"without_review": {
"rule": "no_checking"
}
},
"auto_approve": {
"rule": "never"
},
"counted_votes": {
"rule": "anyone"
},
"shared": "true",
"owners": [
"user1",
"user2"
]
},
{
"id": "2",
"name": "myWorkflow 2",
"description": "A description" ,
"on_submit": {
"with_review": {
"rule": "no_checking"
},
"without_review": {
"rule": "no_checking"
}
},
"auto_approve": {
"rule": "votes"
},
"counted_votes": {
"rule": "members"
},
"shared": "true",
"owners": [
"user3",
"user4"
]
}
]
}
```
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 |
---|---|---|---|---|
|
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 response
Successful Response:
HTTP/1.1 200 OK
{
"workflow": {
"id": "1",
"name": "myWorkflow",
"description": "A description",
"on_submit": {
"with_review": {
"rule": "no_checking"
},
"without_review": {
"rule": "no_checking"
}
},
"auto_approve": {
"rule": "never"
},
"counted_votes": {
"rule": "anyone"
},
"shared": "true",
"owners": [
"user1",
"user2"
]
}
}
Example usage
Get a list of workflows
```bash
curl -u "username:password" \
"https://my-swarm-host/api/v9/workflows/1"
```
JSON Response:
```json
{
"workflow": {
"id": "1",
"name": "myWorkflow",
"description": "A description",
"on_submit": {
"with_review": {
"rule": "no_checking"
},
"without_review": {
"rule": "no_checking"
}
},
"auto_approve": {
"rule": "never"
},
"counted_votes": {
"rule": "anyone"
},
"shared": "true",
"owners": [
"user1",
"user2"
]
}
}
```
Create a workflow
Summary
Create a workflow
POST /api/v9/workflows/
Description
Create a new workflow.
Parameters
Parameter | Description | Type | Parameter Type | Required |
---|---|---|---|---|
|
The workflow name. Will be compared against other workflows and rejected if not unique |
string |
form |
Yes |
|
Description for the new workflow |
string |
form |
No |
|
Whether this workflow is shared for other users that do not own it. Defaults to not shared |
boolean |
form |
No |
|
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 |
|
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 |
|
Data for rules when changes are submitted. Valid values are no_checking, no_revision. |
array |
form |
No |
|
Data for rules when changes are submitted. Valid values are votes, never. |
array |
form |
No |
|
Data for rules when counting votes up. Valid values are anyone, members. |
string |
form |
No |
Example response
Successful Response:
HTTP/1.1 200 OK
{
"workflow": {
"id": "1",
"name": "myWorkflow",
"description": "A description",
"on_submit": {
"with_review": {
"rule": "no_checking"
},
"without_review": {
"rule": "no_checking"
}
},
"auto_approve": {
"rule": "never"
},
"counted_votes": {
"rule": "members"
},
"shared": "true",
"owners": [
"user1",
"user2"
]
}
}
Example usage
Create a workflow
```bash
curl -u "<user>:<password>" \
-H "Content-Type: application/json" \
-X POST \
-d '"name": "myWorkflow", \
"owners": ["user1", "user2"], \
"description": "A description", \
"shared": true, \
"on_submit":{ \
"with_review":{"rule": "no_checking"},' \
"without_review":{"rule": "no_checking"}}' \
"auto_approve": "never", \
"counted_votes": "members", \
"https://my-swarm-host/api/v9/workflows"
```
JSON Response:
```json
{
"workflow": {
"id": "1",
"name": "myWorkflow",
"description": "A description",
"on_submit": {
"with_review": {
"rule": "no_checking"
},
"without_review": {
"rule": "no_checking"
}
},
"auto_approve": {
"rule": "never"
},
"counted_votes": {
"rule": "members"
},
"shared": "true",
"owners": [
"user1",
"user2"
]
}
}
```
Patch a workflow
Summary
Patch a workflow
PATCH /api/v9/workflows/{id}
Description
Patch a workflow.
Parameters
Parameter | Description | Type | Parameter Type | Required |
---|---|---|---|---|
|
The id of the workflow being patched |
string |
form |
Yes |
|
The workflow name. Will be compared against other workflows and rejected if not unique |
string |
form |
No |
|
Description for the new workflow |
string |
form |
No |
|
Whether this workflow is shared for other users that do not own it. Defaults to not shared |
boolean |
form |
No |
|
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 |
|
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 |
|
Data for rules when changes are submitted. Valid values are no_checking, no_revision. |
array |
form |
No |
|
Data for rules when changes are submitted. Valid values are votes, never. |
array |
form |
No |
|
Data for rules when counting votes up. Valid values are anyone, members. |
string |
form |
No |
Example response
Successful Response:
HTTP/1.1 200 OK
{
"workflow": {
"id": "1",
"name": "myWorkflow",
"description": "A description",
"on_submit": {
"with_review": {
"rule": "no_checking"
},
"without_review": {
"rule": "no_checking"
}
},
"auto_approve": {
"rule": "never"
},
"counted_votes": {
"rule": "anyone"
},
"shared": "true",
"owners": [
"user1",
"user2"
]
}
}
Example usage
Update a workflow
```bash
curl -u "username:password" \
-X PATCH \
-d "name=myWorkflow" \
-d "description=A description" \
"https://my-swarm-host/api/v9/workflows/1"
```
JSON Response:
```json
{
"workflow": {
"id": "1",
"name": "myWorkflow",
"description": "A description",
"on_submit": {
"with_review": {
"rule": "no_checking"
},
"without_review": {
"rule": "no_checking"
}
},
"auto_approve": {
"rule": "never"
},
"counted_votes": {
"rule": "anyone"
},
"shared": "true",
"owners": [
"user1",
"user2"
]
}
}
```
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
Parameters
Parameter | Description | Type | Parameter Type | Required |
---|---|---|---|---|
|
The id of the workflow being deleted |
string |
form |
Yes |
Example responses
Successful Response:
HTTP/1.1 200 OK
{
"isValid": true,
"messages": [
"Workflow [1] was deleted"
]
}
Successful Response:
HTTP/1.1 200 OK
{
"isValid": false,
"messages": [
"Cannot delete workflow [1], it is in use on project [project1, project2]"
]
}
Successful Response:
HTTP/1.1 200 OK
{
"isValid": false,
"messages": [
"Cannot delete workflow [1], it is in use on project [project1] and others"
]
}
Successful Response:
HTTP/1.1 200 OK
{
"isValid": false,
"messages": [
"Cannot delete workflow [1], it is in use"
]
}
Example usage
Delete a workflow not in use
curl -u "<user>:<password>" \
-X DELETE \
"https://my-swarm-host/api/v9/workflows/1"
Delete a workflow that is in use on public projects
curl -u "<user>:<password>" \
-X DELETE \
"https://my-swarm-host/api/v9/workflows/1"
Delete a workflow that is in use on a public and some private projects
curl -u "<user>:<password>" \
-X DELETE \
"https://my-swarm-host/api/v9/workflows/1"
Delete a workflow that is in use on only private projects
curl -u "<user>:<password>" \
-X DELETE \
"https://my-swarm-host/api/v9/workflows/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 |
---|---|---|---|---|
|
The id of the workflow being patched |
string |
form |
Yes |
|
The workflow name. Will be compared against other workflows and rejected if not unique |
string |
form |
Yes |
|
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 for the new workflow |
string |
form |
No |
|
Whether this workflow is shared for other users that do not own it. Defaults to not shared |
boolean |
form |
No |
|
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 |
|
Data for rules when changes are submitted. Valid values are no_checking, no_revision. |
array |
form |
No |
|
Data for rules when changes are submitted. Valid values are votes, never. |
array |
form |
No |
|
Data for rules when counting votes up. Valid values are anyone, members. |
string |
form |
No |
Example response
Successful Response:
HTTP/1.1 200 OK
{
"workflow": {
"id": "1",
"name": "myWorkflow",
"description": "A description",
"on_submit": {
"with_review": {
"rule": "no_checking"
},
"without_review": {
"rule": "no_checking"
}
},
"auto_approve": {
"rule": "votes"
},
"counted_votes": {
"rule": "anyone"
},
"shared": "true",
"owners": [
"user1",
"user2"
]
}
}
Example usage
Update a workflow
```bash
curl -u "<user>:<password>" \
-H "Content-Type: application/json" \
-X POST \
-d '"name": "myWorkflow", \
"owners": ["user1", "user2"], \
"description": "A description", \
"shared": true, \
"on_submit":{ \
"with_review":{"rule": "no_checking"},' \
"without_review":{"rule": "no_checking"}}' \
"https://my-swarm-host/api/v9/workflows/1"
```
JSON Response:
```json
{
"workflow": {
"id": "1",
"name": "myWorkflow",
"description": "A description",
"on_submit": {
"with_review": {
"rule": "no_checking"
},
"without_review": {
"rule": "no_checking"
}
},
"auto_approve": {
"rule": "votes"
},
"counted_votes": {
"rule": "anyone"
},
"shared": "true",
"owners": [
"user1",
"user2"
]
}
}
```
Your search for returned result(s).