Helix Swarm Guide (2019.1)

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

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

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

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 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

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.

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

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.

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

id

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

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.

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"
         ]
     }
}
  ```