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

color[R]
created_at[R]
created_by[R]
custom_field_settings[R]
gid[R]
members[R]
name[R]
owner[R]
resource_type[R]
workspace[R]

Public Class Methods

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

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
find_all(client, workspace: required("workspace"), owner: required("owner"), per_page: 20, options: {}) click to toggle source

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
find_by_id(client, id, options: {}) click to toggle source

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
plural_name() click to toggle source

Returns the plural name of the resource.

# File lib/asana/resources/portfolio.rb, line 37
def plural_name
  'portfolios'
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 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_item(item: required("item"), insert_before: nil, insert_after: nil, options: {}, **data) click to toggle source

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
add_members(members: required("members"), options: {}, **data) click to toggle source

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
delete() click to toggle source

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_items(options: {}) click to toggle source

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_custom_field_setting(custom_field: required("custom_field"), options: {}, **data) click to toggle source

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_item(item: required("item"), options: {}, **data) click to toggle source

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
remove_members(members: required("members"), options: {}, **data) click to toggle source

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
update(options: {}, **data) click to toggle source

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