Class: Asana::Resources::Project

Inherits:
Resource
  • Object
show all
Includes:
EventSubscription
Defined in:
lib/asana/resources/project.rb

Overview

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.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from EventSubscription

#events

Methods inherited from Resource

inherited, #initialize, #method_missing, #refresh, #respond_to_missing?, #to_h, #to_s

Methods included from ResponseHelper

#parse

Constructor Details

This class inherits a constructor from Asana::Resources::Resource

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Asana::Resources::Resource

Instance Attribute Details

#archived ⇒ Object (readonly) 



42
43
44
 
# File 'lib/asana/resources/project.rb', line 42

def archived
  @archived
end

#color ⇒ Object (readonly) 



54
55
56
 
# File 'lib/asana/resources/project.rb', line 54

def color
  @color
end

#created_at ⇒ Object (readonly) 



38
39
40
 
# File 'lib/asana/resources/project.rb', line 38

def created_at
  @created_at
end

#current_status ⇒ Object (readonly) 



30
31
32
 
# File 'lib/asana/resources/project.rb', line 30

def current_status
  @current_status
end

#custom_field_settings ⇒ Object (readonly) 



52
53
54
 
# File 'lib/asana/resources/project.rb', line 52

def custom_field_settings
  @custom_field_settings
end

#custom_fields ⇒ Object (readonly) 



50
51
52
 
# File 'lib/asana/resources/project.rb', line 50

def custom_fields
  @custom_fields
end

#due_date ⇒ Object (readonly) 



32
33
34
 
# File 'lib/asana/resources/project.rb', line 32

def due_date
  @due_date
end

#due_on ⇒ Object (readonly) 



34
35
36
 
# File 'lib/asana/resources/project.rb', line 34

def due_on
  @due_on
end

#followers ⇒ Object (readonly) 



48
49
50
 
# File 'lib/asana/resources/project.rb', line 48

def followers
  @followers
end

#gid ⇒ Object (readonly) 



22
23
24
 
# File 'lib/asana/resources/project.rb', line 22

def gid
  @gid
end

#html_notes ⇒ Object (readonly) 



58
59
60
 
# File 'lib/asana/resources/project.rb', line 58

def html_notes
  @html_notes
end

#id ⇒ Object (readonly) 



20
21
22
 
# File 'lib/asana/resources/project.rb', line 20

def id
  @id
end

#layout ⇒ Object (readonly) 



64
65
66
 
# File 'lib/asana/resources/project.rb', line 64

def layout
  @layout
end

#members ⇒ Object (readonly) 



46
47
48
 
# File 'lib/asana/resources/project.rb', line 46

def members
  @members
end

#modified_at ⇒ Object (readonly) 



40
41
42
 
# File 'lib/asana/resources/project.rb', line 40

def modified_at
  @modified_at
end

#name ⇒ Object (readonly) 



26
27
28
 
# File 'lib/asana/resources/project.rb', line 26

def name
  @name
end

#notes ⇒ Object (readonly) 



56
57
58
 
# File 'lib/asana/resources/project.rb', line 56

def notes
  @notes
end

#owner ⇒ Object (readonly) 



28
29
30
 
# File 'lib/asana/resources/project.rb', line 28

def owner
  @owner
end

#public ⇒ Object (readonly) 



44
45
46
 
# File 'lib/asana/resources/project.rb', line 44

def public
  @public
end

#resource_type ⇒ Object (readonly) 



24
25
26
 
# File 'lib/asana/resources/project.rb', line 24

def resource_type
  @resource_type
end

#start_on ⇒ Object (readonly) 



36
37
38
 
# File 'lib/asana/resources/project.rb', line 36

def start_on
  @start_on
end

#team ⇒ Object (readonly) 



62
63
64
 
# File 'lib/asana/resources/project.rb', line 62

def team
  @team
end

#workspace ⇒ Object (readonly) 



60
61
62
 
# File 'lib/asana/resources/project.rb', line 60

def workspace
  @workspace
end

Class Method Details

.create(client, workspace: required("workspace"), team: nil, options: {}, **data) ⇒ Object

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.

Parameters:

  • Returns —

    the full record of the newly created project.

  • workspace (Gid) (defaults to: required("workspace")) —

    The workspace or organization to create the project in.

  • team (Gid) (defaults to: nil) —

    If creating in an organization, the specific team to create the

  • project —

    in.

  • options (Hash) (defaults to: {}) —

    the request I/O options.

  • data (Hash) —

    the attributes to post.



90
91
92
93
 
# File 'lib/asana/resources/project.rb', line 90

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) ⇒ Object

Creates a project shared with the given team.

Parameters:

  • Returns —

    the full record of the newly created project.

  • team (Gid) (defaults to: required("team")) —

    The team to create the project in.

  • options (Hash) (defaults to: {}) —

    the request I/O options.

  • data (Hash) —

    the attributes to post.



115
116
117
118
 
# File 'lib/asana/resources/project.rb', line 115

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) ⇒ Object

If the workspace for your project is an organization, you must also supply a ‘team` to share the project with.

Parameters:

  • Returns —

    the full record of the newly created project.

  • workspace (Gid) (defaults to: required("workspace")) —

    The workspace or organization to create the project in.

  • options (Hash) (defaults to: {}) —

    the request I/O options.

  • data (Hash) —

    the attributes to post.



103
104
105
106
 
# File 'lib/asana/resources/project.rb', line 103

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: {}) ⇒ Object

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

Parameters:

  • workspace (Gid) (defaults to: nil) —

    The workspace or organization to filter projects on.

  • team (Gid) (defaults to: nil) —

    The team to filter projects on.

  • is_template (Boolean) (defaults to: nil) —

    **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) (defaults to: nil) —

    Only return projects whose ‘archived` field takes on the value of

  • this —

    parameter.

  • per_page (Integer) (defaults to: 20) —

    the number of records to fetch per page.

  • options (Hash) (defaults to: {}) —

    the request I/O options.



142
143
144
145
 
# File 'lib/asana/resources/project.rb', line 142

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: {}) ⇒ Object

Returns the complete project record for a single project.

Parameters:

  • id (Gid) —

    The project to get.

  • options (Hash) (defaults to: {}) —

    the request I/O options.



124
125
126
127
 
# File 'lib/asana/resources/project.rb', line 124

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: {}) ⇒ Object

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

Parameters:

  • team (Gid) (defaults to: required("team")) —

    The team to find projects in.

  • is_template (Boolean) (defaults to: nil) —

    Filters results to include only template projects.

  • archived (Boolean) (defaults to: nil) —

    Only return projects whose ‘archived` field takes on the value of

  • this —

    parameter.

  • per_page (Integer) (defaults to: 20) —

    the number of records to fetch per page.

  • options (Hash) (defaults to: {}) —

    the request I/O options.



173
174
175
176
 
# File 'lib/asana/resources/project.rb', line 173

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: {}) ⇒ Object

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

Parameters:

  • workspace (Gid) (defaults to: required("workspace")) —

    The workspace or organization to find projects in.

  • is_template (Boolean) (defaults to: nil) —

    **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) (defaults to: nil) —

    Only return projects whose ‘archived` field takes on the value of

  • this —

    parameter.

  • per_page (Integer) (defaults to: 20) —

    the number of records to fetch per page.

  • options (Hash) (defaults to: {}) —

    the request I/O options.



158
159
160
161
 
# File 'lib/asana/resources/project.rb', line 158

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 ⇒ Object

Returns the plural name of the resource.



68
69
70
 
# File 'lib/asana/resources/project.rb', line 68

def plural_name
  'projects'
end

Instance Method Details

#add_custom_field_setting(custom_field: required("custom_field"), is_important: nil, insert_before: nil, insert_after: nil, options: {}, **data) ⇒ Object

Create a new custom field setting on the project.

Parameters:

  • custom_field (Gid) (defaults to: required("custom_field")) —

    The id of the custom field to associate with this project.

  • is_important (Boolean) (defaults to: nil) —

    Whether this field should be considered important to this project.

  • insert_before (Gid) (defaults to: nil) —

    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) (defaults to: nil) —

    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) (defaults to: {}) —

    the request I/O options.

  • data (Hash) —

    the attributes to post.



295
296
297
298
 
# File 'lib/asana/resources/project.rb', line 295

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) ⇒ Object

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.

Parameters:

  • Returns —

    the updated project record.

  • followers (Array) (defaults to: required("followers")) —

    An array of followers to add to the project.

  • options (Hash) (defaults to: {}) —

    the request I/O options.

  • data (Hash) —

    the attributes to post.



246
247
248
249
 
# File 'lib/asana/resources/project.rb', line 246

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) ⇒ Object

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

Parameters:

  • members (Array) (defaults to: required("members")) —

    An array of user ids.

  • options (Hash) (defaults to: {}) —

    the request I/O options.

  • data (Hash) —

    the attributes to post.



267
268
269
270
 
# File 'lib/asana/resources/project.rb', line 267

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 ⇒ Object

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

Returns:

  • an empty data record.



200
201
202
203
 
# File 'lib/asana/resources/project.rb', line 200

def delete()

  client.delete("/projects/#{gid}") && true
end

#duplicate_project(name: required("name"), team: nil, include: nil, schedule_dates: nil, options: {}, **data) ⇒ Object

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

Parameters:

  • name (String) (defaults to: required("name")) —

    The name of the new project.

  • team (Gid) (defaults to: nil) —

    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) (defaults to: nil) —

    The elements that will be duplicated to the new project.

  • Tasks —

    are always included.

  • schedule_dates (String) (defaults to: nil) —

    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) (defaults to: {}) —

    the request I/O options.

  • data (Hash) —

    the attributes to post.



224
225
226
227
 
# File 'lib/asana/resources/project.rb', line 224

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) ⇒ Object

Remove a custom field setting on the project.

Parameters:

  • custom_field (Gid) (defaults to: nil) —

    The id of the custom field to remove from this project.

  • options (Hash) (defaults to: {}) —

    the request I/O options.

  • data (Hash) —

    the attributes to post.



305
306
307
308
 
# File 'lib/asana/resources/project.rb', line 305

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) ⇒ Object

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

Parameters:

  • Returns —

    the updated project record.

  • followers (Array) (defaults to: required("followers")) —

    An array of followers to remove from the project.

  • options (Hash) (defaults to: {}) —

    the request I/O options.

  • data (Hash) —

    the attributes to post.



257
258
259
260
 
# File 'lib/asana/resources/project.rb', line 257

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) ⇒ Object

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

Parameters:

  • members (Array) (defaults to: required("members")) —

    An array of user ids.

  • options (Hash) (defaults to: {}) —

    the request I/O options.

  • data (Hash) —

    the attributes to post.



277
278
279
280
 
# File 'lib/asana/resources/project.rb', line 277

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: {}) ⇒ Object

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.

Parameters:

  • per_page (Integer) (defaults to: 20) —

    the number of records to fetch per page.

  • options (Hash) (defaults to: {}) —

    the request I/O options.



234
235
236
237
 
# File 'lib/asana/resources/project.rb', line 234

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) ⇒ Object

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.

Parameters:

  • Returns —

    the complete updated project record.

  • options (Hash) (defaults to: {}) —

    the request I/O options.

  • data (Hash) —

    the attributes to post.



191
192
193
194
 
# File 'lib/asana/resources/project.rb', line 191

def update(options: {}, **data)

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