Actions - Huddle/huddle-apis GitHub Wiki
Summary
Actions API is for retrieving the status, details and assignment status of actions (File Requests, To Do's, and Approvals). e.g. An approval with multiple assignees will return one record with the file name, mime-type, and other details along with status of each assignee.
Status
| Operation |
|---|
| Retrieve the actions summary collection |
| Retrieve the actions stats |
Operations
Retrieve actions summary
This endpoint returns the title, type, status, target, due date, and assignments of all Tasks in a Workspace.
Example
In this example, we request the workspace summary for workspace 123
Request
GET /tasks/actions/workspace/123 HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: OAuth2 frootymcnooty/vonbootycherooty
Response
HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json
{
"overview": [
{
"title": "The name of the File Request task",
"status": "InProgress",
"type": "FileRequest",
"targets": [
{
"title": "The name of the folder against which the file request was made",
"type": "folder",
"links": [
{ "rel": "paged-folder", "href": "https://api.huddle.local/files/pagedfolders/1234",
"rel": "alternate", "href": "https://my.huddle.local/workspace/54321/files/#/folders/1234", "type": "text/html",
"rel": "self", "href": "https://api.huddle.local/files/folders/1234"
}
]
},
],
"dueDate": "Thu, 28 June 2018 12:34:56 GMT",
"assignments": [
{
"status": "InProgress",
"actors": [
{
"name": "Andrew",
"email": "[email protected]",
"rel": "assignee",
"links": [
{ "rel": "self", "href": "https://api.huddle.local/users/56" },
{ "rel": "avatar", "href": "https://api.huddle.local/files/users/56/avatar" },
{ "rel": "alternate", "href": "https://my.huddle.local/user/id/56" }
]
},
{
"name": "Wing",
"email": "[email protected]",
"rel": "assignee",
"links": [
{ "rel": "self", "href": "https://api.huddle.local/users/58" },
{ "rel": "avatar", "href": "https://api.huddle.local/files/users/58/avatar" },
{ "rel": "alternate", "href": "https://my.huddle.local/user/id/58" }
]
}
]
}
],
"links": [
{ "rel": "self", "href": "https://api.huddle.local/tasks/10618" },
{ "rel": "parent", "href": "https://api.huddle.local/workspace/2145332871", "title": "Workspace Title" }
]
},
{
"title": "",
"status": "InProgress",
"type": "Approval",
"targets": [
{
"title": "Name of the document without file extension",
"mimeType": "application/msword",
"type": "document",
"links": [
{ "rel": "self", "href": "http://api.huddle.local/files/documents/789" },
{ "rel": "alternate", "href": "https://my.huddle.local/workspaces/2145332871/files/239310949" type="text/html"}
]
},
],
"dueDate": "Fri, 29 June 2018 12:34:56 GMT",
"assignments": [
{
"status": "Complete",
"actors": [
{
"name": "Jonny",
"email": "[email protected]",
"rel": "assignee",
"links": [
{ "rel": "self", "href": "https://api.huddle.local/users/60" },
{ "rel": "avatar", "href": "https://api.huddle.local/files/users/60/avatar" },
{ "rel": "alternate", "href": "https://my.huddle.local/user/id/60" }
]
}
]
}, {
"status": "InProgress",
"actors": [
{
"name": "George",
"email": "[email protected]",
"rel": "assignee",
"links": [
{ "rel": "self", "href": "https://api.huddle.local/users/62" },
{ "rel": "avatar", "href": "https://api.huddle.local/files/users/62/avatar" },
{ "rel": "alternate", "href": "https://my.huddle.local/user/id/62" }
]
}
]
}
]
},
{
"title": "The name of the Todo task",
"status": "NotStarted",
"type": "Todo",
"targets": [
{
"title": "Name of the document without file extension",
"mimeType": "application/msword",
"type": "document",
"links": [
{ "rel": "self", "href": "http://api.huddle.local/files/documents/789" },
{ "rel": "alternate", "href": "https://my.huddle.local/workspaces/2145332871/files/789" type="text/html"}
]
},
{
"title": "Name of a different document without file extension",
"mimeType": "application/msexcel",
"type": "document",
"links": [
{ "rel": "self", "href": "http://api.huddle.local/files/documents/148" },
{ "rel": "alternate", "href": "https://my.huddle.local/workspaces/2145332871/files/148" type="text/html"}
]
}
],
"dueDate": "Thu, 28 June 2018 12:34:56 GMT",
"plannedStartDate": "Sun, 01 Mar 2020 00:00:00 GMT",
"assignments": [
{
"status": "InProgress",
"actors": [
{
"name": "Andrew",
"email": "[email protected]",
"rel": "assignee",
"links": [
{ "rel": "self", "href": "https://api.huddle.local/users/56" },
{ "rel": "avatar", "href": "https://api.huddle.local/files/users/56/avatar" },
{ "rel": "alternate", "href": "https://my.huddle.local/user/id/56" }
]
},
{
"name": "Wing",
"email": "[email protected]",
"rel": "assignee",
"links": [
{ "rel": "self", "href": "https://api.huddle.local/users/58" },
{ "rel": "avatar", "href": "https://api.huddle.local/files/users/58/avatar" },
{ "rel": "alternate", "href": "https://my.huddle.local/user/id/58" }
]
}
]
}
],
"links": [
{ "rel": "self", "href": "https://api.huddle.local/tasks/10618" },
{ "rel": "parent", "href": "https://api.huddle.local/workspace/2145332871", "title": "Workspace Title" }
]
}
],
"links": [
{ "rel": "self", "href": "https://api.huddle.local/tasks/actions/workspace/2145332871" },
{ "rel": "parent", "href": "https://api.huddle.local/workspace/2145332871", "title": "Workspace Title" },
{ "rel": "current", "href": "https://api.huddle.local/tasks/actions/workspace/2145332871?types=all&sort=asc&skipItems=0&pagesize=200"}
]
}
The dueDate field is only returned in the response if it has been set.
Link relations
| Type | Name | Description | Methods |
|---|---|---|---|
| overview | self |
The current URI of this summary. | GET |
| overview | parent |
The URI of the Workspace. | GET |
| overview | current |
The URI of the current page, using the specified sort order and filters. | GET |
| overview | first |
The URI of the first page, using the specified sort order and filters. | GET |
| overview | next |
The URI of the next page, using the specified sort order and filters. | GET |
| overview | prev |
The URI of the previous page, using the specified sort order and filters. | GET |
| target | self |
The URI of the target i.e folder URI. | GET |
| assignees | self |
The URI of the User. | GET |
| assignees | avatar |
The URI for the User's avatar. | GET |
| assignees | alternate |
The URI for the web profile of the User | GET |
Filters
Filters are query string parameters that are used to filter the actions that are returned in the summary, e.g.
GET /tasks/actions/workspace/123?types=all&createdByUsers=123,456&assignedToUsers=me&statuses=notstarted,inprogress&title=my+tasks&rangestart=2020-03-01&rangeend=2020-03-31&sort=desc&skipItems=1
| Parameter | Default value | Additional notes |
|---|---|---|
types |
all |
Available fields: all, filerequest, todo, approval |
createdByUsers |
Comma separated list of user ids, e.g. 123,456,789 |
|
assignedToUsers |
any |
Available fields: me, none, any, or a comma separated list of user ids, e.g. 123,456,789 |
statuses |
any |
Available fields: notstarted,inprogress, or complete |
title |
Tasks with titles containing the text. Empty strings turn the filter off. | |
rangeStart |
Tasks with Planned Start Dates on or after this date this will be included unless rangeEnd is set and they fall after that date. e.g. 2020-03-03 |
|
rangeEnd |
Tasks with Due Dates before or on this date will be included. Additionally if rangeStart is set Tasks with Planned Start Dates between the two dates will be included. |
|
sort |
asc |
Due date desc or asc. No due date is considered to be end of time. |
skipItems |
0 |
|
pagesize |
10 |
Minimum value: 1; Maximum value: 500 |
Error Responses
| Case | Response Code | Error Code |
|---|---|---|
| User is not a member of the workspace | 403 Forbidden |
WorkspaceMembershipRequired |
| Workspace is locked | 403 Forbidden |
Workspace Locked |
| Workspace is deleted | 404 Not Found |
WorkspaceDeleted |
Retrieve actions stats
This endpoint returns totals and late counts for not started, in progress, and completed Actions in a Workspace.
Example
In this example, we request the action stats for workspace 123
Request
GET /tasks/actions/workspace/123/stats HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: OAuth2 frootymcnooty/vonbootycherooty
Response
HTTP/1.1 200 OK
Content-Type: application/vnd.huddle.data+json
{
"counts": {
"fileRequest": {
"notStarted": {
"total": 100,
"late": 12
},
"inProgress": {
"total": 100,
"late": 50
},
"complete": {
"total": 1337
}
},
"todo": {
"notStarted": {
"total": 50,
"late": 6
},
"inProgress": {
"total": 50,
"late": 25
},
"complete": {
"total": 1337
}
},
"approval" : {
"notStarted": {
"total": 25,
"late": 3
},
"inProgress": {
"total": 25,
"late": 12
},
"complete": {
"total": 1337
}
}
},
"links": [
{ "rel": "self", "href": "..." },
{ "rel": "parent", "href": "..." }
]
}
Link relations
| Name | Description | Methods |
|---|---|---|
self |
The current URI of this summary. | GET |
parent |
The URI of the Workspace. | GET |
Filters
Filters are query string parameters that are used to filter the Tasks that are returned in the summary, e.g.
GET /tasks/actions/workspace/123/stats?types=all&createdByUsers=123,456&assignedToUsers=me&statuses=NotStarted,InProgress&title=my+tasks&rangestart=2020-03-01&rangeend=2020-03-31
| Parameter | Default value | Additional notes |
|---|---|---|
types |
all |
Available fields: all, filerequest, todo, approval |
title |
Tasks with titles containing the text. Empty strings turn the filter off. | |
createdByUsers |
Comma separated list of user ids, e.g. 123,456,789 |
|
assignedToUsers |
any |
Available fields: me, none, any, or a comma separated list of user ids, e.g. 123,456,789 |
statuses |
any |
Available fields: notstarted,inprogress, or complete |
rangeStart |
Tasks with Planned Start Dates on or after this date this will be included unless rangeEnd is set and they fall after that date. e.g. 2020-03-03 |
|
rangeEnd |
Tasks with Due Dates before or on this date will be included. Additionally if rangeStart is set Tasks with Planned Start Dates between the two dates will be included. |
Error Responses
| Case | Response Code | Error Code |
|---|---|---|
| User is not a member of the workspace | 403 Forbidden |
WorkspaceMembershipRequired |
| Workspace is locked | 403 Forbidden |
Workspace Locked |
| Workspace is deleted | 404 Not Found |
WorkspaceDeleted |