TaskBulkOperations - Huddle/huddle-apis GitHub Wiki

Summary

Operation
Bulk create Tasks
Bulk edit Tasks
Bulk delete Tasks

Operations

Bulk create tasks

Limited to 200 Tasks and 50 Assignees at once. If any of the Tasks or Assignees are invalid/have insufficient permission then no Tasks will be created.

This endpoint allows the creation of multiple Tasks at once. Mandatory elements are title, type (must be FileRequest) and destination-folder link. Optional elements that are not supplied will have sensible defaults inferred by the server.

To specify an element value to be the same across all of the Tasks it should be added to the defaults element. The title element cannot be specified in the defaults element. The assignees element can be specified in both the 'defaults' and on individual tasks

The defaults can be overridden on a per Task basis. The validation is the same as creating a file request.

Example

JSON Request

POST /tasks/workspace/123/bulk-create HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: OAuth2 frootymcnooty/vonbootycherooty
{
  "message": "Hi please do this task",
  "defaults": {
    "type": "FileRequest",
    "status": "NotStarted",
    "dueDate": "2011-05-10",
    "assignees": [
      {
        "links": [
          {
            "rel": "assignee",
            "href": "..."
          }
        ]
      },
      {
        "links": [
          {
            "rel": "assignee",
            "href": "..."
          }
        ]
      },
      {
        "links": [
          {
            "rel": "team",
            "href": "..."
          }
        ]
      }
    ],
    "links": [
      {
        "rel": "destination-folder",
        "href": "..."
      }
    ]
  },
  "tasks": [
    {
      "title": "My first task",
      "status": "InProgress",
      "dueDate": "2020-08-10",
      "assignees": [
      {
        "links": [
          {
            "rel": "assignee",
            "href": "..."
          }
        ]
      }]
    },
    {
      "title": "My second task",
      "links": [
        {
          "rel": "destination-folder",
          "href": "..."
        }
      ]
    }
  ]
}

XML Request

POST /tasks/workspace/123/bulk-create HTTP/1.1
Accept: application/vnd.huddle.data+xml
Authorization: OAuth2 frootymcnooty/vonbootycherooty
<bulkCreateTasksOperation>
    <defaults>
        <type>FileRequest</type>
        <status>NotStarted</status>
        <dueDate>2011-05-10</dueDate>
        <link rel="destination-folder" href="..." />
    </defaults>
    <tasks>
        <task>
            <title>My first task</title>
            <status>InProgress</status>
            <dueDate>2020-08-10</dueDate>
        </task>
        <task>
            <title>My second task</title>
            <link rel="destination-folder" href="..." />
        </task>
    </tasks>
</bulkCreateTasksOperation>

Success Response

The server responds with a 202 Accepted, and provides a Location header with the URI of the progress endpoint for that operation. Values for the processingStatus are InProgress and Complete. Once complete the response will also include a list of the tasks created. Only users with workspace permissions can access this endpoint.

HTTP/1.1 202 Accepted
Location: /tasks/bulk-create/07ea5eb9-dde7-4e68-8868-3a57dc314b8f
Progress Endpoint JSON Response
{
    "processingStatus": "Complete",
    "tasks": [
      {
      "title": "A new task",
      "type": "FileRequest",
      "links": [ "..." ],
      "actors": [ "..." ],
      "status": "NotStarted",
      "created": "Thu, 18 May 2017 12:54:53 GMT",
      "updated": "Thu, 18 May 2017 12:54:53 GMT",
      "dueDate": "Thu, 18 May 2017 00:00:00 GMT"
    }
  ]
}
Progress Endpoint XML Response
<bulkCreateTasksOperation>
    <processingStatus>Complete</processingStatus>
    <tasks>
      <task title="A new task" type="FileRequest">
        <link rel="self" href="..."/>
        ... other task elements ...
      </task>
    </tasks>
</bulkCreateTasksOperation>

Error Response (invalid defaults)

If the defaults are invalid, then the errors will be shown as below using the standard error responses . If there are also invalid tasks, the errors for them will not be shown.

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "errorCode": "BulkOperationDefaultsInvalid",
  "errorMessages": [
    "The specified status is not valid."
  ]
}

Error Response (invalid tasks)

If there are invalid individual tasks, then the errors will be shown as below. The index in the request collection and the proposed task title are returned to aid identifying the erroneous task(s).

JSON Response

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "errorCode": "BulkOperationTasksInvalid",
  "errorMessages": [
    "There are one or more tasks with invalid fields."
  ],
  "errors": [
    {
      "index": 1,
      "title": "My second task",
      "errorCode": "Invalid",
      "errorMessages": [
        "The specified due date is not valid."
      ]
    }
  ]
}

XML Response

HTTP/1.1 400 Bad Request
Content-Type: application/xml
<errorResult>
    <errorCode>BulkOperationTasksInvalid</errorCode>
    <errorMessages>
        <message>There are one or more tasks with invalid fields.</message>
    </errorMessages>
    <errors>
        <error>
            <link rel="task" href="..." />
            <errorCode>TaskDeleted</errorCode>
            <errorMessages>
                <message>The Task has been deleted.</message>
            </errorMessages>
        </error>
    </errors>
</errorResult>

Error Responses

Case Response Code Error Code
Any error with default values 400 Bad Request BulkOperationDefaultsInvalid
Any error with values in tasks 400 Bad Request BulkOperationTasksInvalid
Too many Tasks 400 Bad Request BulkOperationLimitExceeded
Too many Assignees (users or users in teams) 400 Bad Request BulkOperationLimitExceeded
User is not a member of the Workspace 403 Forbidden WorkspaceMembershipRequired
Workspace is archived 403 Forbidden WorkspaceArchived
Workspace is locked 403 Forbidden WorkspaceLocked
Workspace is deleted 404 Not Found WorkspaceDeleted

Refer to the error code documentation on the Create file request endpoint for individual field error codes.

Bulk edit tasks

Limited to 200 tasks at once. If any Tasks are failed to be updated, a status of CompleteWithErrors will be returned.

The Tasks to be updated are supplied in the links collection.

This endpoint allows updating the details or assignments of all supplied tasks at once, by specifying the updateDetails, addAssignees, removeAssignees, setAssignees, addAttachments, removeAttachments, or setAttachments element. Only one operation can be specified per request!

  • updateDetails: Update all the specified tasks at once to have the same values supplied in the updateDetails element. Values that are not supplied will not be updated. The validation is the same as when editing a Todo.
  • addAssignees: Add all assignments supplied in the addAssignees element to all specified tasks. If a user is already assigned to a task, the assignment remains unchanged. The validation is the same as when adding assignees to a task.
  • removeAssignees: Remove the assignments supplied in the removeAssignees element from all specified tasks, if they are assigned to the task.
  • setAssignees: Setting all specified tasks to have exactly the assignments supplied in the setAssignees element. This will add assignments if they don't already exist on the task and remove any assignments that are not contained in the setAssignees element. If the setAssignees collection is empty, all assignments will be removed. The validation is the same as when adding assignees to a task.
  • addAttachments: Add all attachments supplied in the addAttachments element to all specified tasks. The validation is the same as when attaching documents to a task.
  • removeAttachments: Remove the attachments supplied in the removeAttachments element from all specified tasks, if they are assigned to the task. The validation is the same as when deleting attachments from a task.
  • setAttachments: Setting all specified tasks to have exactly the attachments supplied in the setAttachments element. This will add attachments if they don't already exist on the task and remove any attachments that are not contained in the setAttachments element. If the setAttachments collection is empty, all attachments will be removed. The validation is the same as when attaching documents to a task.

Example

JSON Request

POST /tasks/workspace/123/bulk-edit HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: OAuth2 frootymcnooty/vonbootycherooty
{
  "links": [
    {
      "rel": "task",
      "href": "..."
    },
    {
      "rel": "task",
      "href": "..."
    }
  ],
  "updateDetails": {
    "title": {
      "value": "My new task"
    },
    "status": {
      "value": "InProgress"
    },
    "dueDate": {
      "value": "2011-05-10"
    },
    "plannedStartDate": {
      "value": "2009-05-15"
    }
  },
  "addAssignees": [
    {
      "links": [
        {
          "rel": "assignee",
          "href": "..."
        }
      ]
    },
    {
      "links": [
        {
          "rel": "assignee",
          "href": "..."
        }
      ]
    },
    {
      "links": [
        {
          "rel": "team",
          "href": "..."
        }
      ]
    }
  ],
  "removeAssignees": [
    {
      "rel": "assignee",
      "href": "..."
    },
    {
      "rel": "assignee",
      "href": "..."
    }
  ],
  "setAssignees": [
    {
      "links": [
        {
          "rel": "assignee",
          "href": "..."
        }
      ]
    },
    {
      "links": [
        {
          "rel": "assignee",
          "href": "..."
        }
      ]
    },
      {
        "links": [
          {
            "rel": "team",
            "href": "..."
          }
        ]
      }
  ],
  "addAttachments": [
    {
      "rel": "document",
      "href": "..."
    },
    {
      "rel": "document",
      "href": "..."
    }
  ],
  "removeAttachments": [
    {
      "rel": "document",
      "href": "..."
    },
    {
      "rel": "document",
      "href": "..."
    }
  ],
  "setAttachments": [
    {
      "links": [
        {
          "rel": "document",
          "href": "..."
        }
      ]
    },
    {
      "links": [
        {
          "rel": "document",
          "href": "..."
        }
      ]
    }
  ]
}

Success Response

The server responds with a 202 Accepted, and provides a Location header with the URI of the progress endpoint for that operation. Values for the processingStatus are InProgress, Complete, and CompleteWithErrors.

HTTP/1.1 202 Accepted
Location: /tasks/bulk-edit/07ea5eb9-dde7-4e68-8868-3a57dc314b8f
{
    "processingStatus": "Complete"
}

If there are errors during the process the response will list the errors:

{
  "processingStatus": "CompleteWithErrors",
  "errors": [
    {
      "link": 
      { 
        "rel": "task", 
        "href": "..." 
      },
      "errorCode": "TasksNotFound",
      "errorMessage": ""
    }
  ]
}

Possible partial errors

Case Error Code
Any permission errors InsufficientPermissions
One of the Tasks not in the same Workspace InsufficientPermissions
One of the Tasks was deleted TasksNotFound
One of the Tasks does not exist TasksNotFound

Error Response (invalid operation element)

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "errorCode": "BulkOperationEditTaskInvalid",
  "errorMessages": [
    "The specified status is not valid."
  ]
}

Error Responses

Case Response Code Error Code
Any error with operation values 400 Bad Request BulkOperationEditTaskInvalid
Any permission errors 403 Forbidden InsufficientPermissions
Too many Tasks 400 Bad Request BulkOperationLimitExceeded
Too many Assignees (users or users in teams) 400 Bad Request BulkOperationLimitExceeded
User is not a member of the Workspace 403 Forbidden WorkspaceMembershipRequired
Workspace is archived 403 Forbidden WorkspaceArchived
Workspace is locked 403 Forbidden WorkspaceLocked
Workspace is deleted 404 Not Found WorkspaceDeleted

Bulk delete Tasks

Limited to deleting 500 Tasks at once. If any Tasks are failed to be deleted a status of CompleteWithErrors will be returned.

The Tasks to be updated are supplied in the links collection.

Example

POST /tasks/workspace/123/bulk-delete HTTP/1.1
Accept: application/vnd.huddle.data+json
Authorization: OAuth2 frootymcnooty/vonbootycherooty
{
  "links": [
    {
      "rel": "task",
      "href": "..."
    },
    {
      "rel": "task",
      "href": "..."
    }
  ]
}

Success Response

The server response with a 202 Accepted, and provides a Location header with the URI of the progress endpoint for that operation. Values for the processingStatus are InProgress, Complete, and CompleteWithErrors.

HTTP/1.1 202 Accepted
Location: /tasks/bulk-delete/1410ae96-858d-11eb-8dcd-0242ac130003
{
  "processingStatus": "Complete"
}

If there are errors during the process the response will list the errors:

{
  "processingStatus": "CompleteWithErrors",
  "errors": [
    {
      "link": 
      { 
        "rel": "task", 
        "href": "..." 
      },
      "errorCode": "InsufficientPermissions",
      "errorMessage": "User does not have permission to delete Task."
    }
  ]
}

Possible errors

Case Error Code
Any permission errors InsufficientPermissions

Error Response

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "errorCode": "BulkOperationDeleteTaskInvalid",
  "errorMessages": [
    "One or more of the Task links was invalid."
  ]
}

Error Responses

Case Response Code Error Code
Invalid Task link 400 Bad Request BulkOperationDeleteTaskInvalid
One or more Tasks does not exist 400 Bad Request BulkOperationDeleteTaskInvalid
Not all Tasks in the same Workspace 400 Bad Request BulkOperationWorkspacesInvalid
Not all Tasks are of the same type 400 Bad Request BulkOperationDeleteTaskInvalid
No Tasks supplied 400 Bad Request NoTasksSupplied
Too many Tasks 400 Bad Request BulkOperationLimitExceeded
User is not a Member of the Workspace 403 Forbidden WorkspaceMembershipRequired
Workspace is archived 403 Forbidden WorkspaceArchived
Workspace is locked 403 Forbidden WorkspaceLocked
Workspace is deleted 404 Not Found WorkspaceDeleted
⚠️ **GitHub.com Fallback** ⚠️