class Asana::Resources::Project

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.

Attributes

archived[R]
color[R]
created_at[R]
current_status[R]
custom_field_settings[R]
custom_fields[R]
due_date[R]
due_on[R]
followers[R]
gid[R]
html_notes[R]
layout[R]
members[R]
modified_at[R]
name[R]
notes[R]
owner[R]
public[R]
resource_type[R]
start_on[R]
team[R]
workspace[R]

Public Class Methods

create(client, workspace: required("workspace"), team: nil, options: {}, **data) click to toggle source

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.

workspace - [Gid] The workspace or organization to create the project in. team - [Gid] If creating in an organization, the specific team to create the project in.

options - [Hash] the request I/O options. data - [Hash] the attributes to post.

# File lib/asana/resources/project.rb, line 87
def create(client, workspace: required("workspace"), team: nil, options: {}, **data)
  with_params = data.merge(workspace: workspace, team: team).reject { |_,v| v.nil? || Array(v).empty? }
  self.new(parse(client.post("/projects", body: with_params, options: options)).first, client: client)
end
create_in_team(client, team: required("team"), options: {}, **data) click to toggle source

Creates a project shared with the given team.

Returns the full record of the newly created project.

team - [Gid] The team to create the project in. options - [Hash] the request I/O options. data - [Hash] the attributes to post.

# File lib/asana/resources/project.rb, line 112
def create_in_team(client, team: required("team"), options: {}, **data)

  self.new(parse(client.post("/teams/#{team}/projects", body: data, options: options)).first, client: client)
end
create_in_workspace(client, workspace: required("workspace"), options: {}, **data) click to toggle source

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.

workspace - [Gid] The workspace or organization to create the project in. options - [Hash] the request I/O options. data - [Hash] the attributes to post.

# File lib/asana/resources/project.rb, line 100
def create_in_workspace(client, workspace: required("workspace"), options: {}, **data)

  self.new(parse(client.post("/workspaces/#{workspace}/projects", body: data, options: options)).first, client: client)
end
find_all(client, workspace: nil, team: nil, is_template: nil, archived: nil, per_page: 20, options: {}) click to toggle source

Returns the compact project records for some filtered set of projects. Use one or more of the parameters provided to filter the projects returned.

workspace - [Gid] The workspace or organization to filter projects on. team - [Gid] The team to filter projects on. is_template - [Boolean] **Note: This parameter can only be included if a team is also defined, or the workspace is not an organization** Filters results to include only template projects.

archived - [Boolean] Only return projects whose `archived` field takes on the value of this parameter.

per_page - [Integer] the number of records to fetch per page. options - [Hash] the request I/O options.

# File lib/asana/resources/project.rb, line 139
def find_all(client, workspace: nil, team: nil, is_template: nil, archived: nil, per_page: 20, options: {})
  params = { workspace: workspace, team: team, is_template: is_template, archived: archived, limit: per_page }.reject { |_,v| v.nil? || Array(v).empty? }
  Collection.new(parse(client.get("/projects", params: params, options: options)), type: self, client: client)
end
find_by_id(client, id, options: {}) click to toggle source

Returns the complete project record for a single project.

id - [Gid] The project to get. options - [Hash] the request I/O options.

# File lib/asana/resources/project.rb, line 121
def find_by_id(client, id, options: {})

  self.new(parse(client.get("/projects/#{id}", options: options)).first, client: client)
end
find_by_team(client, team: required("team"), is_template: nil, archived: nil, per_page: 20, options: {}) click to toggle source

Returns the compact project records for all projects in the team.

team - [Gid] The team to find projects in. is_template - [Boolean] Filters results to include only template projects.

archived - [Boolean] Only return projects whose `archived` field takes on the value of this parameter.

per_page - [Integer] the number of records to fetch per page. options - [Hash] the request I/O options.

# File lib/asana/resources/project.rb, line 170
def find_by_team(client, team: required("team"), is_template: nil, archived: nil, per_page: 20, options: {})
  params = { is_template: is_template, archived: archived, limit: per_page }.reject { |_,v| v.nil? || Array(v).empty? }
  Collection.new(parse(client.get("/teams/#{team}/projects", params: params, options: options)), type: self, client: client)
end
find_by_workspace(client, workspace: required("workspace"), is_template: nil, archived: nil, per_page: 20, options: {}) click to toggle source

Returns the compact project records for all projects in the workspace.

workspace - [Gid] The workspace or organization to find projects in. is_template - [Boolean] **Note: This parameter can only be included if a team is also defined, or the workspace is not an organization** Filters results to include only template projects.

archived - [Boolean] Only return projects whose `archived` field takes on the value of this parameter.

per_page - [Integer] the number of records to fetch per page. options - [Hash] the request I/O options.

# File lib/asana/resources/project.rb, line 155
def find_by_workspace(client, workspace: required("workspace"), is_template: nil, archived: nil, per_page: 20, options: {})
  params = { is_template: is_template, archived: archived, limit: per_page }.reject { |_,v| v.nil? || Array(v).empty? }
  Collection.new(parse(client.get("/workspaces/#{workspace}/projects", params: params, options: options)), type: self, client: client)
end
plural_name() click to toggle source

Returns the plural name of the resource.

# File lib/asana/resources/project.rb, line 65
def plural_name
  'projects'
end

Public Instance Methods

add_custom_field_setting(custom_field: required("custom_field"), is_important: nil, insert_before: nil, insert_after: nil, options: {}, **data) click to toggle source

Create a new custom field setting on the project.

custom_field - [Gid] 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 - [Gid] 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 - [Gid] 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.

options - [Hash] the request I/O options. data - [Hash] the attributes to post.

# File lib/asana/resources/project.rb, line 292
def add_custom_field_setting(custom_field: required("custom_field"), is_important: nil, insert_before: nil, insert_after: nil, options: {}, **data)
  with_params = data.merge(custom_field: custom_field, is_important: is_important, insert_before: insert_before, insert_after: insert_after).reject { |_,v| v.nil? || Array(v).empty? }
  Resource.new(parse(client.post("/projects/#{gid}/addCustomFieldSetting", body: with_params, options: options)).first, client: client)
end
add_followers(followers: required("followers"), options: {}, **data) click to toggle source

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.

followers - [Array] An array of followers to add to the project. options - [Hash] the request I/O options. data - [Hash] the attributes to post.

# File lib/asana/resources/project.rb, line 243
def add_followers(followers: required("followers"), options: {}, **data)
  with_params = data.merge(followers: followers).reject { |_,v| v.nil? || Array(v).empty? }
  refresh_with(parse(client.post("/projects/#{gid}/addFollowers", body: with_params, options: options)).first)
end
add_members(members: required("members"), options: {}, **data) click to toggle source

Adds the specified list of users as members of the project. Returns the updated project record.

members - [Array] An array of user ids. options - [Hash] the request I/O options. data - [Hash] the attributes to post.

# File lib/asana/resources/project.rb, line 264
def add_members(members: required("members"), options: {}, **data)
  with_params = data.merge(members: members).reject { |_,v| v.nil? || Array(v).empty? }
  refresh_with(parse(client.post("/projects/#{gid}/addMembers", body: with_params, options: options)).first)
end
delete() click to toggle source

A specific, existing project can be deleted by making a DELETE request on the URL for that project.

Returns an empty data record.

# File lib/asana/resources/project.rb, line 197
def delete()

  client.delete("/projects/#{gid}") && true
end
duplicate_project(name: required("name"), team: nil, include: nil, schedule_dates: nil, options: {}, **data) click to toggle source

Creates and returns a job that will asynchronously handle the duplication.

name - [String] The name of the new project. team - [Gid] Sets the team of the new project. If team is not defined, the new project will be in the same team as the the original project.

include - [Array] The elements that will be duplicated to the new project. Tasks are always included.

schedule_dates - [String] A dictionary of options to auto-shift dates. `task_dates` must be included to use this option. Requires either `start_on` or `due_on`, but not both. `start_on` will set the first start date of the new project to the given date, while `due_on` will set the last due date to the given date. Both will offset the remaining dates by the same amount of the original project.

options - [Hash] the request I/O options. data - [Hash] the attributes to post.

# File lib/asana/resources/project.rb, line 221
def duplicate_project(name: required("name"), team: nil, include: nil, schedule_dates: nil, options: {}, **data)
  with_params = data.merge(name: name, team: team, include: include, schedule_dates: schedule_dates).reject { |_,v| v.nil? || Array(v).empty? }
  Resource.new(parse(client.post("/projects/#{gid}/duplicate", body: with_params, options: options)).first, client: client)
end
remove_custom_field_setting(custom_field: nil, options: {}, **data) click to toggle source

Remove a custom field setting on the project.

custom_field - [Gid] The id of the custom field to remove from this project. options - [Hash] the request I/O options. data - [Hash] the attributes to post.

# File lib/asana/resources/project.rb, line 302
def remove_custom_field_setting(custom_field: nil, options: {}, **data)
  with_params = data.merge(custom_field: custom_field).reject { |_,v| v.nil? || Array(v).empty? }
  Resource.new(parse(client.post("/projects/#{gid}/removeCustomFieldSetting", body: with_params, options: options)).first, client: client)
end
remove_followers(followers: required("followers"), options: {}, **data) click to toggle source

Removes the specified list of users from following the project, this will not affect project membership status. Returns the updated project record.

followers - [Array] An array of followers to remove from the project. options - [Hash] the request I/O options. data - [Hash] the attributes to post.

# File lib/asana/resources/project.rb, line 254
def remove_followers(followers: required("followers"), options: {}, **data)
  with_params = data.merge(followers: followers).reject { |_,v| v.nil? || Array(v).empty? }
  refresh_with(parse(client.post("/projects/#{gid}/removeFollowers", body: with_params, options: options)).first)
end
remove_members(members: required("members"), options: {}, **data) click to toggle source

Removes the specified list of members from the project. Returns the updated project record.

members - [Array] An array of user ids. options - [Hash] the request I/O options. data - [Hash] the attributes to post.

# File lib/asana/resources/project.rb, line 274
def remove_members(members: required("members"), options: {}, **data)
  with_params = data.merge(members: members).reject { |_,v| v.nil? || Array(v).empty? }
  refresh_with(parse(client.post("/projects/#{gid}/removeMembers", body: with_params, options: options)).first)
end
tasks(per_page: 20, options: {}) click to toggle source

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.

per_page - [Integer] the number of records to fetch per page. options - [Hash] the request I/O options.

# File lib/asana/resources/project.rb, line 231
def tasks(per_page: 20, options: {})
  params = { limit: per_page }.reject { |_,v| v.nil? || Array(v).empty? }
  Collection.new(parse(client.get("/projects/#{gid}/tasks", params: params, options: options)), type: Task, client: client)
end
update(options: {}, **data) click to toggle source

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.

options - [Hash] the request I/O options. data - [Hash] the attributes to post.

# File lib/asana/resources/project.rb, line 188
def update(options: {}, **data)

  refresh_with(parse(client.put("/projects/#{gid}", body: data, options: options)).first)
end