Workflows : Controller for querying, creating and updating workflows

Important

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.

Tip
  • 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"
    ]
}