R/tasks.R

In datacamp/asana: Access the Asana API

# DO NOT EDIT MANUALLY - This file is autogenerated from Asana API Specs
#' Tasks
#'
#'
#'  The _task_ is the basic object around which many operations in Asana are
#'  centered. In the Asana application, multiple tasks populate the middle pane
#'  according to some view parameters, and the set of selected tasks determines
#'  the more detailed information presented in the details pane.
#' @name asn_tasks
#' @rdname asn_tasks
#' @family tasks
#' @seealso \link{https://asana.com/developers/api-reference/tasks}
NULL

#' Creating a new task is as easy as POSTing to the `/tasks` endpoint
#' with a data block containing the fields you'd like to set on the task.
#' Any unspecified fields will take on default values.
#' 
#' Every task is required to be created in a specific workspace, and this
#' workspace cannot be changed once set. The workspace need not be set
#' explicitly if you specify `projects` or a `parent` task instead.
#' 
#' `projects` can be a comma separated list of projects, or just a single
#' project the task should belong to.
#'
#' @param ...  {Object} Data for the request
#'    [workspace] : {Id} The workspace to create a task in.
#' @export
#' @family tasks
asn_tasks_create = function(..., options = list()){
  path =  "/tasks"
  asn_post(endpoint = path, ..., options = options)
}


#' Creating a new task is as easy as POSTing to the `/tasks` endpoint
#' with a data block containing the fields you'd like to set on the task.
#' Any unspecified fields will take on default values.
#' 
#' Every task is required to be created in a specific workspace, and this
#' workspace cannot be changed once set. The workspace need not be set
#' explicitly if you specify a `project` or a `parent` task instead.
#'
#' @param workspace  {Id} The workspace to create a task in.#'
#' @param ...  {Object} Data for the request
#' @export
#' @family tasks
asn_tasks_create_in_workspace = function(workspace, ..., options = list()){
  path = sprintf("/workspaces/%s/tasks", workspace)
  asn_post(endpoint = path, ..., options = options)
}


#' Returns the complete task record for a single task.
#'
#' @param task  {Id} The task to get.#'
#' @param ...  {Object} Parameters for the request
#' @export
#' @family tasks
asn_tasks_find_by_id = function(task, ..., options = list()){
  path = sprintf("/tasks/%s", task)
  asn_get(endpoint = path, ..., options = options)
}


#' A specific, existing task can be updated by making a PUT request on the
#' URL for that task. Only the fields provided in the `data` block will be
#' updated; any unspecified fields will remain unchanged.
#' 
#' When using this method, it is best to specify only those fields you wish
#' to change, or else you may overwrite changes made by another user since
#' you last retrieved the task.
#' 
#' Returns the complete updated task record.
#'
#' @param task  {Id} The task to update.#'
#' @param ...  {Object} Data for the request
#' @export
#' @family tasks
asn_tasks_update = function(task, ..., options = list()){
  path = sprintf("/tasks/%s", task)
  asn_put(endpoint = path, ..., options = options)
}


#' A specific, existing task can be deleted by making a DELETE request on the
#' URL for that task. Deleted tasks go into the "trash" of the user making
#' the delete request. Tasks can be recovered from the trash within a period
#' of 30 days; afterward they are completely removed from the system.
#' 
#' Returns an empty data record.
#'
#' @param task  {Id} The task to delete.
#' @export
#' @family tasks
asn_tasks_delete = function(task, ..., options = list()){
  path = sprintf("/tasks/%s", task)
  asn_delete(endpoint = path, ..., options = options)
}


#' Returns the compact task records for all tasks within the given project,
#' ordered by their priority within the project.
#'
#' @param projectId  {Id} The project in which to search for tasks.#'
#' @param ...  {Object} Parameters for the request
#' @export
#' @family tasks
asn_tasks_find_by_project = function(project_id, ..., options = list()){
  path = sprintf("/projects/%s/tasks", project_id)
  asn_get(endpoint = path, ..., options = options)
}


#' Returns the compact task records for all tasks with the given tag.
#'
#' @param tag  {Id} The tag in which to search for tasks.#'
#' @param ...  {Object} Parameters for the request
#' @export
#' @family tasks
asn_tasks_find_by_tag = function(tag, ..., options = list()){
  path = sprintf("/tags/%s/tasks", tag)
  asn_get(endpoint = path, ..., options = options)
}


#' <b>Board view only:</b> Returns the compact section records for all tasks within the given section.
#'
#' @param section  {Id} The section in which to search for tasks.#'
#' @param ...  {Object} Parameters for the request
#' @export
#' @family tasks
asn_tasks_find_by_section = function(section, ..., options = list()){
  path = sprintf("/sections/%s/tasks", section)
  asn_get(endpoint = path, ..., options = options)
}


#' Returns the compact task records for some filtered set of tasks. Use one
#' or more of the parameters provided to filter the tasks returned. You must
#' specify a `project` or `tag` if you do not specify `assignee` and `workspace`.
#'
#' @param ...  {Object} Parameters for the request
#'    [assignee] : {String} The assignee to filter tasks on.
#'    [project] : {Id} The project to filter tasks on.
#'    [section] : {Id} The section to filter tasks on.
#'    [workspace] : {Id} The workspace or organization to filter tasks on.
#'    [completed_since] : {String} Only return tasks that are either incomplete or that have been
#'    completed since this time.
#'    [modified_since] : {String} Only return tasks that have been modified since the given time.
#' @export
#' @family tasks
asn_tasks_find_all = function(..., options = list()){
  path =  "/tasks"
  asn_get(endpoint = path, ..., options = options)
}


#' The search endpoint allows you to build complex queries to find and fetch exactly the data you need from Asana. For a more comprehensive description of all the query parameters and limitations of this endpoint, see our [long-form documentation](/developers/documentation/getting-started/search-api) for this feature.
#'
#' @param workspace  {Id} The workspace or organization in which to search for tasks.#'
#' @param ...  {Object} Parameters for the request
#' @export
#' @family tasks
asn_tasks_search = function(workspace, ..., options = list()){
  path = sprintf("/workspaces/%s/tasks/search", workspace)
  asn_get(endpoint = path, ..., options = options)
}


#' Returns the compact representations of all of the dependencies of a task.
#'
#' @param task  {Id} The task to get dependencies on.#'
#' @param ...  {Object} Parameters for the request
#' @export
#' @family tasks
asn_tasks_dependencies = function(task, ..., options = list()){
  path = sprintf("/tasks/%s/dependencies", task)
  asn_get(endpoint = path, ..., options = options)
}


#' Returns the compact representations of all of the dependents of a task.
#'
#' @param task  {Id} The task to get dependents on.#'
#' @param ...  {Object} Parameters for the request
#' @export
#' @family tasks
asn_tasks_dependents = function(task, ..., options = list()){
  path = sprintf("/tasks/%s/dependents", task)
  asn_get(endpoint = path, ..., options = options)
}


#' Marks a set of tasks as dependencies of this task, if they are not
#' already dependencies. *A task can have at most 15 dependencies.*
#'
#' @param task  {Id} The task to add dependencies to.#'
#' @param ...  {Object} Data for the request
#'    dependencies : {Array} An array of task IDs that this task should depend on.
#' @export
#' @family tasks
asn_tasks_add_dependencies = function(task, ..., options = list()){
  path = sprintf("/tasks/%s/addDependencies", task)
  asn_post(endpoint = path, ..., options = options)
}


#' Marks a set of tasks as dependents of this task, if they are not already
#' dependents. *A task can have at most 30 dependents.*
#'
#' @param task  {Id} The task to add dependents to.#'
#' @param ...  {Object} Data for the request
#'    dependents : {Array} An array of task IDs that should depend on this task.
#' @export
#' @family tasks
asn_tasks_add_dependents = function(task, ..., options = list()){
  path = sprintf("/tasks/%s/addDependents", task)
  asn_post(endpoint = path, ..., options = options)
}


#' Unlinks a set of dependencies from this task.
#'
#' @param task  {Id} The task to remove dependencies from.#'
#' @param ...  {Object} Data for the request
#'    dependencies : {Array} An array of task IDs to remove as dependencies.
#' @export
#' @family tasks
asn_tasks_remove_dependencies = function(task, ..., options = list()){
  path = sprintf("/tasks/%s/removeDependencies", task)
  asn_post(endpoint = path, ..., options = options)
}


#' Unlinks a set of dependents from this task.
#'
#' @param task  {Id} The task to remove dependents from.#'
#' @param ...  {Object} Data for the request
#'    dependents : {Array} An array of task IDs to remove as dependents.
#' @export
#' @family tasks
asn_tasks_remove_dependents = function(task, ..., options = list()){
  path = sprintf("/tasks/%s/removeDependents", task)
  asn_post(endpoint = path, ..., options = options)
}


#' Adds each of the specified followers to the task, if they are not already
#' following. Returns the complete, updated record for the affected task.
#'
#' @param task  {Id} The task to add followers to.#'
#' @param ...  {Object} Data for the request
#'    followers : {Array} An array of followers to add to the task.
#' @export
#' @family tasks
asn_tasks_add_followers = function(task, ..., options = list()){
  path = sprintf("/tasks/%s/addFollowers", task)
  asn_post(endpoint = path, ..., options = options)
}


#' Removes each of the specified followers from the task if they are
#' following. Returns the complete, updated record for the affected task.
#'
#' @param task  {Id} The task to remove followers from.#'
#' @param ...  {Object} Data for the request
#'    followers : {Array} An array of followers to remove from the task.
#' @export
#' @family tasks
asn_tasks_remove_followers = function(task, ..., options = list()){
  path = sprintf("/tasks/%s/removeFollowers", task)
  asn_post(endpoint = path, ..., options = options)
}


#' Returns a compact representation of all of the projects the task is in.
#'
#' @param task  {Id} The task to get projects on.#'
#' @param ...  {Object} Parameters for the request
#' @export
#' @family tasks
asn_tasks_projects = function(task, ..., options = list()){
  path = sprintf("/tasks/%s/projects", task)
  asn_get(endpoint = path, ..., options = options)
}


#' Adds the task to the specified project, in the optional location
#' specified. If no location arguments are given, the task will be added to
#' the end of the project.
#' 
#' `addProject` can also be used to reorder a task within a project or section that
#' already contains it.
#' 
#' At most one of `insert_before`, `insert_after`, or `section` should be
#' specified. Inserting into a section in an non-order-dependent way can be
#' done by specifying `section`, otherwise, to insert within a section in a
#' particular place, specify `insert_before` or `insert_after` and a task
#' within the section to anchor the position of this task.
#' 
#' Returns an empty data block.
#'
#' @param task  {Id} The task to add to a project.#'
#' @param ...  {Object} Data for the request
#'    project : {Id} The project to add the task to.
#'    [insert_after] : {Id} A task in the project to insert the task after, or `null` to
#'    insert at the beginning of the list.
#'    [insert_before] : {Id} A task in the project to insert the task before, or `null` to
#'    insert at the end of the list.
#'    [section] : {Id} A section in the project to insert the task into. The task will be
#'    inserted at the bottom of the section.
#' @export
#' @family tasks
asn_tasks_add_project = function(task, ..., options = list()){
  path = sprintf("/tasks/%s/addProject", task)
  asn_post(endpoint = path, ..., options = options)
}


#' Removes the task from the specified project. The task will still exist
#' in the system, but it will not be in the project anymore.
#' 
#' Returns an empty data block.
#'
#' @param task  {Id} The task to remove from a project.#'
#' @param ...  {Object} Data for the request
#'    project : {Id} The project to remove the task from.
#' @export
#' @family tasks
asn_tasks_remove_project = function(task, ..., options = list()){
  path = sprintf("/tasks/%s/removeProject", task)
  asn_post(endpoint = path, ..., options = options)
}


#' Returns a compact representation of all of the tags the task has.
#'
#' @param task  {Id} The task to get tags on.#'
#' @param ...  {Object} Parameters for the request
#' @export
#' @family tasks
asn_tasks_tags = function(task, ..., options = list()){
  path = sprintf("/tasks/%s/tags", task)
  asn_get(endpoint = path, ..., options = options)
}


#' Adds a tag to a task. Returns an empty data block.
#'
#' @param task  {Id} The task to add a tag to.#'
#' @param ...  {Object} Data for the request
#'    tag : {Id} The tag to add to the task.
#' @export
#' @family tasks
asn_tasks_add_tag = function(task, ..., options = list()){
  path = sprintf("/tasks/%s/addTag", task)
  asn_post(endpoint = path, ..., options = options)
}


#' Removes a tag from the task. Returns an empty data block.
#'
#' @param task  {Id} The task to remove a tag from.#'
#' @param ...  {Object} Data for the request
#'    tag : {Id} The tag to remove from the task.
#' @export
#' @family tasks
asn_tasks_remove_tag = function(task, ..., options = list()){
  path = sprintf("/tasks/%s/removeTag", task)
  asn_post(endpoint = path, ..., options = options)
}


#' Returns a compact representation of all of the subtasks of a task.
#'
#' @param task  {Id} The task to get the subtasks of.#'
#' @param ...  {Object} Parameters for the request
#' @export
#' @family tasks
asn_tasks_subtasks = function(task, ..., options = list()){
  path = sprintf("/tasks/%s/subtasks", task)
  asn_get(endpoint = path, ..., options = options)
}


#' Creates a new subtask and adds it to the parent task. Returns the full record
#' for the newly created subtask.
#'
#' @param task  {Id} The task to add a subtask to.#'
#' @param ...  {Object} Data for the request
#' @export
#' @family tasks
asn_tasks_add_subtask = function(task, ..., options = list()){
  path = sprintf("/tasks/%s/subtasks", task)
  asn_post(endpoint = path, ..., options = options)
}


#' Returns a compact representation of all of the stories on the task.
#'
#' @param task  {Id} The task containing the stories to get.#'
#' @param ...  {Object} Parameters for the request
#' @export
#' @family tasks
asn_tasks_stories = function(task, ..., options = list()){
  path = sprintf("/tasks/%s/stories", task)
  asn_get(endpoint = path, ..., options = options)
}


#' Adds a comment to a task. The comment will be authored by the
#' currently authenticated user, and timestamped when the server receives
#' the request.
#' 
#' Returns the full record for the new story added to the task.
#'
#' @param task  {Id} Globally unique identifier for the task.#'
#' @param ...  {Object} Data for the request
#'    text : {String} The plain text of the comment to add.
#' @export
#' @family tasks
asn_tasks_add_comment = function(task, ..., options = list()){
  path = sprintf("/tasks/%s/stories", task)
  asn_post(endpoint = path, ..., options = options)
}