class Asana::Resources::Portfolio
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.
Attributes
Public Class Methods
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.
workspace - [Gid] The workspace or organization in which to create the portfolio. name - [String] The name of the newly-created portfolio color - [String] An optional color for the portfolio options - [Hash] the request I/O options. data - [Hash] the attributes to post.
# 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
Returns a list of the portfolios in compact representation that are owned by the current API user.
workspace - [Gid] The workspace or organization to filter portfolios on. owner - [String] The user who owns the portfolio. Currently, API users can only get a list of portfolios that they themselves own.
per_page - [Integer] the number of records to fetch per page. options - [Hash] the request I/O options.
# 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
Returns the complete record for a single portfolio.
id - [Gid] The portfolio to get. options - [Hash] the request I/O options.
# 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
Returns the plural name of the resource.
# File lib/asana/resources/portfolio.rb, line 37 def plural_name 'portfolios' end
Public Instance Methods
Create a new custom field setting on the portfolio. Returns the full record for the new custom field setting.
custom_field - [Gid] The id of the custom field to add to the portfolio. is_important - [Boolean] 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] 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] 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] the request I/O options. data - [Hash] the attributes to post.
# 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 an item to a portfolio.
Returns an empty data block.
item - [Gid] The item to add to the portfolio. insert_before - [Gid] 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] 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] the request I/O options. data - [Hash] the attributes to post.
# 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
Adds the specified list of users as members of the portfolio. Returns the updated portfolio 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/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
An existing portfolio can be deleted by making a DELETE request on the URL for that portfolio.
Returns an empty data record.
# File lib/asana/resources/portfolio.rb, line 100 def delete() client.delete("/portfolios/#{gid}") && true end
Get a list of the items in compact form in a portfolio.
options - [Hash] the request I/O options.
# File lib/asana/resources/portfolio.rb, line 108 def get_items(options: {}) Collection.new(parse(client.get("/portfolios/#{gid}/items", options: options)), type: self, client: client) end
Remove a custom field setting on the portfolio. Returns an empty data block.
custom_field - [Gid] The id of the custom field to remove from this portfolio. options - [Hash] the request I/O options. data - [Hash] the attributes to post.
# 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 an item to a portfolio.
Returns an empty data block.
item - [Gid] The item to remove from the portfolio. options - [Hash] the request I/O options. data - [Hash] the attributes to post.
# 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
Removes the specified list of members from the portfolio. Returns the updated portfolio 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/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
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.
Returns the complete updated portfolio record.
options - [Hash] the request I/O options. data - [Hash] the attributes to post.
# 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