R/projects.R

In datacamp/asana: Access the Asana API

# DO NOT EDIT MANUALLY - This file is autogenerated from Asana API Specs
#' Projects
#'
#'
#'  A _project_ represents a prioritized list of tasks in Asana or a board with
#'  columns of tasks represented as cards. It exists in a single workspace or
#'  organization and is accessible to a subset of users in that workspace or
#'  organization, depending on its permissions.
#'  
#'  Projects in organizations are shared with a single team. You cannot currently
#'  change the team of a project via the API. Non-organization workspaces do not
#'  have teams and so you should not specify the team of project in a regular
#'  workspace.
#' @name asn_projects
#' @rdname asn_projects
#' @family projects
#' @seealso \link{https://asana.com/developers/api-reference/projects}
NULL

#' Creates a new project in a workspace or team.
#' 
#' Every project is required to be created in a specific workspace or
#' organization, and this cannot be changed once set. Note that you can use
#' the `workspace` parameter regardless of whether or not it is an
#' organization.
#' 
#' If the workspace for your project _is_ an organization, you must also
#' supply a `team` to share the project with.
#' 
#' Returns the full record of the newly created project.
#'
#' @param ...  {Object} Data for the request
#'    workspace : {Id} The workspace or organization to create the project in.
#'    [team] : {Id} If creating in an organization, the specific team to create the
#'    project in.
#' @export
#' @family projects
asn_projects_create = function(..., options = list()){
  path =  "/projects"
  asn_post(endpoint = path, ..., options = options)
}


#' If the workspace for your project _is_ an organization, you must also
#' supply a `team` to share the project with.
#' 
#' Returns the full record of the newly created project.
#'
#' @param workspace  {Id} The workspace or organization to create the project in.#'
#' @param ...  {Object} Data for the request
#' @export
#' @family projects
asn_projects_create_in_workspace = function(workspace, ..., options = list()){
  path = sprintf("/workspaces/%s/projects", workspace)
  asn_post(endpoint = path, ..., options = options)
}


#' Creates a project shared with the given team.
#' 
#' Returns the full record of the newly created project.
#'
#' @param team  {Id} The team to create the project in.#'
#' @param ...  {Object} Data for the request
#' @export
#' @family projects
asn_projects_create_in_team = function(team, ..., options = list()){
  path = sprintf("/teams/%s/projects", team)
  asn_post(endpoint = path, ..., options = options)
}


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


#' A specific, existing project can be updated by making a PUT request on the
#' URL for that project. 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 project record.
#'
#' @param project  {Id} The project to update.#'
#' @param ...  {Object} Data for the request
#' @export
#' @family projects
asn_projects_update = function(project, ..., options = list()){
  path = sprintf("/projects/%s", project)
  asn_put(endpoint = path, ..., options = options)
}


#' A specific, existing project can be deleted by making a DELETE request
#' on the URL for that project.
#' 
#' Returns an empty data record.
#'
#' @param project  {Id} The project to delete.
#' @export
#' @family projects
asn_projects_delete = function(project, ..., options = list()){
  path = sprintf("/projects/%s", project)
  asn_delete(endpoint = path, ..., options = options)
}


#' Returns the compact project records for some filtered set of projects.
#' Use one or more of the parameters provided to filter the projects returned.
#'
#' @param ...  {Object} Parameters for the request
#'    [workspace] : {Id} The workspace or organization to filter projects on.
#'    [team] : {Id} The team to filter projects on.
#'    [archived] : {Boolean} Only return projects whose `archived` field takes on the value of
#'    this parameter.
#' @export
#' @family projects
asn_projects_find_all = function(..., options = list()){
  path =  "/projects"
  asn_get(endpoint = path, ..., options = options)
}


#' Returns the compact project records for all projects in the workspace.
#'
#' @param workspace  {Id} The workspace or organization to find projects in.#'
#' @param ...  {Object} Parameters for the request
#'    [archived] : {Boolean} Only return projects whose `archived` field takes on the value of
#'    this parameter.
#' @export
#' @family projects
asn_projects_find_by_workspace = function(workspace, ..., options = list()){
  path = sprintf("/workspaces/%s/projects", workspace)
  asn_get(endpoint = path, ..., options = options)
}


#' Returns the compact project records for all projects in the team.
#'
#' @param team  {Id} The team to find projects in.#'
#' @param ...  {Object} Parameters for the request
#'    [archived] : {Boolean} Only return projects whose `archived` field takes on the value of
#'    this parameter.
#' @export
#' @family projects
asn_projects_find_by_team = function(team, ..., options = list()){
  path = sprintf("/teams/%s/projects", team)
  asn_get(endpoint = path, ..., options = options)
}


#' Returns the compact task records for all tasks within the given project,
#' ordered by their priority within the project. Tasks can exist in more than one project at a time.
#'
#' @param project  {Id} The project in which to search for tasks.#'
#' @param ...  {Object} Parameters for the request
#' @export
#' @family projects
asn_projects_tasks = function(project, ..., options = list()){
  path = sprintf("/projects/%s/tasks", project)
  asn_get(endpoint = path, ..., options = options)
}


#' Adds the specified list of users as followers to the project. Followers are a subset of members, therefore if
#' the users are not already members of the project they will also become members as a result of this operation.
#' Returns the updated project record.
#'
#' @param project  {Id} The project to add followers to.#'
#' @param ...  {Object} Data for the request
#'    followers : {Array} An array of followers to add to the project.
#' @export
#' @family projects
asn_projects_add_followers = function(project, ..., options = list()){
  path = sprintf("/projects/%s/addFollowers", project)
  asn_post(endpoint = path, ..., options = options)
}


#' Removes the specified list of users from following the project, this will not affect project membership status.
#' Returns the updated project record.
#'
#' @param project  {Id} The project to remove followers from.#'
#' @param ...  {Object} Data for the request
#'    followers : {Array} An array of followers to remove from the project.
#' @export
#' @family projects
asn_projects_remove_followers = function(project, ..., options = list()){
  path = sprintf("/projects/%s/removeFollowers", project)
  asn_post(endpoint = path, ..., options = options)
}


#' Adds the specified list of users as members of the project. Returns the updated project record.
#'
#' @param project  {Id} The project to add members to.#'
#' @param ...  {Object} Data for the request
#'    members : {Array} An array of members to add to the project.
#' @export
#' @family projects
asn_projects_add_members = function(project, ..., options = list()){
  path = sprintf("/projects/%s/addMembers", project)
  asn_post(endpoint = path, ..., options = options)
}


#' Removes the specified list of members from the project. Returns the updated project record.
#'
#' @param project  {Id} The project to remove members from.#'
#' @param ...  {Object} Data for the request
#'    members : {Array} An array of members to remove from the project.
#' @export
#' @family projects
asn_projects_remove_members = function(project, ..., options = list()){
  path = sprintf("/projects/%s/removeMembers", project)
  asn_post(endpoint = path, ..., options = options)
}


#' Create a new custom field setting on the project.
#'
#' @param project  {Id} The project to associate the custom field with#'
#' @param ...  {Object} Data for the request
#'    custom_field : {Id} The id of the custom field to associate with this project.
#'    [is_important] : {Boolean} Whether this field should be considered important to this project.
#'    [insert_before] : {Id} An id of a Custom Field Settings on this project, before which the new Custom Field Settings will be added.
#'    `insert_before` and `insert_after` parameters cannot both be specified.
#'    [insert_after] : {Id} An id of a Custom Field Settings on this project, after which the new Custom Field Settings will be added.
#'    `insert_before` and `insert_after` parameters cannot both be specified.
#' @export
#' @family projects
asn_projects_add_custom_field_setting = function(project, ..., options = list()){
  path = sprintf("/projects/%s/addCustomFieldSetting", project)
  asn_post(endpoint = path, ..., options = options)
}


#' Remove a custom field setting on the project.
#'
#' @param project  {Id} The project to associate the custom field with#'
#' @param ...  {Object} Data for the request
#'    [custom_field] : {Id} The id of the custom field to remove from this project.
#' @export
#' @family projects
asn_projects_remove_custom_field_setting = function(project, ..., options = list()){
  path = sprintf("/projects/%s/removeCustomFieldSetting", project)
  asn_post(endpoint = path, ..., options = options)
}