Class: Asana::Resources::Portfolio

Inherits:
Resource
  • Object
show all
Defined in:
lib/asana/resources/portfolio.rb

Overview

A portfolio gives a high-level overview of the status of multiple initiatives in Asana. Portfolios provide a dashboard overview of the state of multiple items, including a progress report and the most recent [project status](/developers/api-reference/project_statuses) update.

Portfolios have some restrictions on size. Each portfolio has a maximum of 250 items and, like projects, a maximum of 20 custom fields.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

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

#color ⇒ Object (readonly) 



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

def color
  @color
end

#created_at ⇒ Object (readonly) 



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

def created_at
  @created_at
end

#created_by ⇒ Object (readonly) 



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

def created_by
  @created_by
end

#custom_field_settings(options: {}) ⇒ Object (readonly)

Get the custom field settings on a portfolio.

Parameters:

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

    the request I/O options.



169
170
171
 
# File 'lib/asana/resources/portfolio.rb', line 169

def custom_field_settings
  @custom_field_settings
end

#gid ⇒ Object (readonly) 



18
19
20
 
# File 'lib/asana/resources/portfolio.rb', line 18

def gid
  @gid
end

#id ⇒ Object (readonly) 



16
17
18
 
# File 'lib/asana/resources/portfolio.rb', line 16

def id
  @id
end

#members ⇒ Object (readonly) 



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

def members
  @members
end

#name ⇒ Object (readonly) 



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

def name
  @name
end

#owner ⇒ Object (readonly) 



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

def owner
  @owner
end

#resource_type ⇒ Object (readonly) 



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

def resource_type
  @resource_type
end

#workspace ⇒ Object (readonly) 



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

def workspace
  @workspace
end

Class Method Details

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

Creates a new portfolio in the given workspace with the supplied name.

Note that portfolios created in the Asana UI may have some state (like the “Priority” custom field) which is automatically added to the portfolio when it is created. Portfolios created via our API will not be created with the same initial state to allow integrations to create their own starting state on a portfolio.

Parameters:

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

    The workspace or organization in which to create the portfolio.

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

    The name of the newly-created portfolio

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

    An optional color for the portfolio

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

    the request I/O options.

  • data (Hash) —

    the attributes to post.



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

def create(client, workspace: required("workspace"), name: required("name"), color: nil, options: {}, **data)
  with_params = data.merge(workspace: workspace, name: name, color: color).reject { |_,v| v.nil? || Array(v).empty? }
  self.new(parse(client.post("/portfolios", body: with_params, options: options)).first, client: client)
end

.find_all(client, workspace: required("workspace"), owner: required("owner"), per_page: 20, options: {}) ⇒ Object

Returns a list of the portfolios in compact representation that are owned by the current API user.

Parameters:

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

    The workspace or organization to filter portfolios on.

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

    The user who owns the portfolio. Currently, API users can only get a

  • list —

    of portfolios that they themselves own.

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

    the number of records to fetch per page.

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

    the request I/O options.



80
81
82
83
 
# File 'lib/asana/resources/portfolio.rb', line 80

def find_all(client, workspace: required("workspace"), owner: required("owner"), per_page: 20, options: {})
  params = { workspace: workspace, owner: owner, limit: per_page }.reject { |_,v| v.nil? || Array(v).empty? }
  Collection.new(parse(client.get("/portfolios", params: params, options: options)), type: self, client: client)
end

.find_by_id(client, id, options: {}) ⇒ Object

Returns the complete record for a single portfolio.

Parameters:

  • id (Gid) —

    The portfolio to get.

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

    the request I/O options.



66
67
68
69
 
# File 'lib/asana/resources/portfolio.rb', line 66

def find_by_id(client, id, options: {})

  self.new(parse(client.get("/portfolios/#{id}", options: options)).first, client: client)
end

.plural_name ⇒ Object

Returns the plural name of the resource.



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

def plural_name
  'portfolios'
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 portfolio. Returns the full record for the new custom field setting.

Parameters:

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

    The id of the custom field to add to the portfolio.

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

    Whether this field should be considered important to this portfolio (for instance, to display in the list view of items in the portfolio).

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

    An id of a custom field setting on this portfolio. The new custom field setting will be added before this one.

  • `insert_before` —

    and ‘insert_after` parameters cannot both be specified.

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

    An id of a custom field setting on this portfolio. The new custom field setting will be added after this one.

  • `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.



188
189
190
191
 
# File 'lib/asana/resources/portfolio.rb', line 188

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("/portfolios/#{gid}/addCustomFieldSetting", body: with_params, options: options)).first, client: client)
end

#add_item(item: required("item"), insert_before: nil, insert_after: nil, options: {}, **data) ⇒ Object

Add an item to a portfolio.

Parameters:

  • Returns —

    an empty data block.

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

    The item to add to the portfolio.

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

    An id of an item in this portfolio. The new item will be added before the one specified here.

  • `insert_before` —

    and ‘insert_after` parameters cannot both be specified.

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

    An id of an item in this portfolio. The new item will be added after the one specified here.

  • `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.



129
130
131
132
 
# File 'lib/asana/resources/portfolio.rb', line 129

def add_item(item: required("item"), insert_before: nil, insert_after: nil, options: {}, **data)
  with_params = data.merge(item: item, insert_before: insert_before, insert_after: insert_after).reject { |_,v| v.nil? || Array(v).empty? }
  client.post("/portfolios/#{gid}/addItem", body: with_params, options: options) && true
end

#add_members(members: required("members"), options: {}, **data) ⇒ Object

Adds the specified list of users as members of the portfolio. Returns the updated portfolio 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.



151
152
153
154
 
# File 'lib/asana/resources/portfolio.rb', line 151

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("/portfolios/#{gid}/addMembers", body: with_params, options: options)).first)
end

#delete ⇒ Object

An existing portfolio can be deleted by making a DELETE request on the URL for that portfolio.

Returns:

  • an empty data record.



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

def delete()

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

#get_items(options: {}) ⇒ Object

Get a list of the items in compact form in a portfolio.

Parameters:

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

    the request I/O options.



111
112
113
114
 
# File 'lib/asana/resources/portfolio.rb', line 111

def get_items(options: {})

  Collection.new(parse(client.get("/portfolios/#{gid}/items", options: options)), type: self, client: client)
end

#remove_custom_field_setting(custom_field: required("custom_field"), options: {}, **data) ⇒ Object

Remove a custom field setting on the portfolio. Returns an empty data block.

Parameters:

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

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

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

    the request I/O options.

  • data (Hash) —

    the attributes to post.



199
200
201
202
 
# File 'lib/asana/resources/portfolio.rb', line 199

def remove_custom_field_setting(custom_field: required("custom_field"), options: {}, **data)
  with_params = data.merge(custom_field: custom_field).reject { |_,v| v.nil? || Array(v).empty? }
  client.post("/portfolios/#{gid}/removeCustomFieldSetting", body: with_params, options: options) && true
end

#remove_item(item: required("item"), options: {}, **data) ⇒ Object

Remove an item to a portfolio.

Parameters:

  • Returns —

    an empty data block.

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

    The item to remove from the portfolio.

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

    the request I/O options.

  • data (Hash) —

    the attributes to post.



141
142
143
144
 
# File 'lib/asana/resources/portfolio.rb', line 141

def remove_item(item: required("item"), options: {}, **data)
  with_params = data.merge(item: item).reject { |_,v| v.nil? || Array(v).empty? }
  client.post("/portfolios/#{gid}/removeItem", body: with_params, options: options) && true
end

#remove_members(members: required("members"), options: {}, **data) ⇒ Object

Removes the specified list of members from the portfolio. Returns the updated portfolio 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.



161
162
163
164
 
# File 'lib/asana/resources/portfolio.rb', line 161

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("/portfolios/#{gid}/removeMembers", body: with_params, options: options)).first)
end

#update(options: {}, **data) ⇒ Object

An existing portfolio can be updated by making a PUT request on the URL for that portfolio. Only the fields provided in the ‘data` block will be updated; any unspecified fields will remain unchanged.

Parameters:

  • Returns —

    the complete updated portfolio record.

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

    the request I/O options.

  • data (Hash) —

    the attributes to post.



94
95
96
97
 
# File 'lib/asana/resources/portfolio.rb', line 94

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

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