Workflows : Controller for querying, creating and updating workflows
Support for APIs older than v9 will be removed in the Swarm 2022.2 release.
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 Helix 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"
]
}