Class: Asana::Resources::Portfolio

Inherits:
PortfoliosBase 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 PortfoliosBase

add_custom_field_setting_for_portfolio, add_item_for_portfolio, add_members_for_portfolio, create_portfolio, delete_portfolio, get_items_for_portfolio, get_portfolio, get_portfolios, inherited, remove_custom_field_setting_for_portfolio, remove_item_for_portfolio, remove_members_for_portfolio, update_portfolio

Methods inherited from Resource

#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) 



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

def color
  @color
end

#created_at ⇒ Object (readonly) 



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

def created_at
  @created_at
end

#created_by ⇒ Object (readonly) 



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

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.



166
167
168
 
# File 'lib/asana/resources/portfolio.rb', line 166

def custom_field_settings
  @custom_field_settings
end

#gid ⇒ Object (readonly) 



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

def gid
  @gid
end

#members ⇒ Object (readonly) 



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

def members
  @members
end

#name ⇒ Object (readonly) 



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

def name
  @name
end

#owner ⇒ Object (readonly) 



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

def owner
  @owner
end

#resource_type ⇒ Object (readonly) 



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

def resource_type
  @resource_type
end

#workspace ⇒ Object (readonly) 



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

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.



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

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.



77
78
79
80
 
# File 'lib/asana/resources/portfolio.rb', line 77

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.



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

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.



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

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.



185
186
187
188
 
# File 'lib/asana/resources/portfolio.rb', line 185

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.



126
127
128
129
 
# File 'lib/asana/resources/portfolio.rb', line 126

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.



148
149
150
151
 
# File 'lib/asana/resources/portfolio.rb', line 148

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.



100
101
102
103
 
# File 'lib/asana/resources/portfolio.rb', line 100

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.



108
109
110
111
 
# File 'lib/asana/resources/portfolio.rb', line 108

def get_items(options: {})

  Collection.new(parse(client.get("/portfolios/#{gid}/items", options: options)), type: Resource, 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.



196
197
198
199
 
# File 'lib/asana/resources/portfolio.rb', line 196

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.



138
139
140
141
 
# File 'lib/asana/resources/portfolio.rb', line 138

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.



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

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.



91
92
93
94
 
# File 'lib/asana/resources/portfolio.rb', line 91

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

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