Class: Asana::Resources::CustomField

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

Overview

Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the [Custom Fields](/developers/documentation/getting-started/custom-fields) developer documentation for more information about how custom fields relate to various resources in Asana.

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

#description ⇒ Object (readonly) 



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

def description
  @description
end

#enum_options ⇒ Object (readonly) 



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

def enum_options
  @enum_options
end

#id ⇒ Object (readonly) 



14
15
16
 
# File 'lib/asana/resources/custom_fields.rb', line 14

def id
  @id
end

#name ⇒ Object (readonly) 



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

def name
  @name
end

#precision ⇒ Object (readonly) 



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

def precision
  @precision
end

#type ⇒ Object (readonly) 



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

def type
  @type
end

Class Method Details

.add_enum_option(client, custom_field: required("custom_field"), name: required("name"), color: nil, insert_before: nil, insert_after: nil, options: {}, **data) ⇒ Object

Creates an enum option and adds it to this custom field’s list of enum options. A custom field can have at most 50 enum options (including disabled options). By default new enum options are inserted at the end of a custom field’s list.

Parameters:

  • Returns —

    the full record of the newly created enum option.

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

    Globally unique identifier for the custom field.

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

    The name of the enum option.

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

    The color of the enum option. Defaults to ‘none’.

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

    An existing enum option within this custom field before which the new enum option should be inserted. Cannot be provided together with after_enum_option.

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

    An existing enum option within this custom field after which the new enum option should be inserted. Cannot be provided together with before_enum_option.

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

    the request I/O options.

  • data (Hash) —

    the attributes to post.



83
84
85
86
 
# File 'lib/asana/resources/custom_fields.rb', line 83

def add_enum_option(client, custom_field: required("custom_field"), name: required("name"), color: nil, insert_before: nil, insert_after: nil, options: {}, **data)
  with_params = data.merge(name: name, color: color, insert_before: insert_before, insert_after: insert_after).reject { |_,v| v.nil? || Array(v).empty? }
  Resource.new(parse(client.post("/custom_fields/#{custom_field}/enum_options", body: with_params, options: options)).first, client: client)
end

.create(client, workspace: required("workspace"), type: required("type"), name: required("name"), description: nil, precision: nil, enum_options: nil, options: {}, **data) ⇒ Object

Creates a new custom field in a workspace. Every custom field is required to be created in a specific workspace, and this workspace cannot be changed once set.

A custom field’s ‘name` must be unique within a workspace and not conflict with names of existing task properties such as ’Due Date’ or ‘Assignee’. A custom field’s ‘type` must be one of ’text’, ‘enum’, or ‘number’.

Parameters:

  • Returns —

    the full record of the newly created custom field.

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

    The workspace to create a custom field in.

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

    The type of the custom field.

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

    The name of the custom field.

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

    The description of the custom field.

  • precision (Integer) (defaults to: nil) —

    The number of decimal places for the numerical values. Required if the custom field is of type ‘number’.

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

    The discrete values the custom field can assume. Required if the custom field is of type ‘enum’.

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

    the request I/O options.

  • data (Hash) —

    the attributes to post.



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

def create(client, workspace: required("workspace"), type: required("type"), name: required("name"), description: nil, precision: nil, enum_options: nil, options: {}, **data)
  with_params = data.merge(workspace: workspace, type: type, name: name, description: description, precision: precision, enum_options: enum_options).reject { |_,v| v.nil? || Array(v).empty? }
  Resource.new(parse(client.post("/custom_fields", body: with_params, options: options)).first, client: client)
end

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

Returns the complete definition of a custom field’s metadata.

Parameters:

  • id (Id) —

    Globally unique identifier for the custom field.

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

    the request I/O options.



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

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

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

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

Returns a list of the compact representation of all of the custom fields in a workspace.

Parameters:

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

    The workspace or organization to find custom field definitions in.

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

    the number of records to fetch per page.

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

    the request I/O options.



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

def find_by_workspace(client, workspace: required("workspace"), per_page: 20, options: {})
  params = { limit: per_page }.reject { |_,v| v.nil? || Array(v).empty? }
  Collection.new(parse(client.get("/workspaces/#{workspace}/custom_fields", params: params, options: options)), type: Resource, client: client)
end

.plural_name ⇒ Object

Returns the plural name of the resource.



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

def plural_name
  'custom_fields'
end

.reorder_enum_option(client, custom_field: required("custom_field"), enum_option: required("enum_option"), name: required("name"), color: nil, before_enum_option: nil, after_enum_option: nil, options: {}, **data) ⇒ Object

Moves a particular enum option to be either before or after another specified enum option in the custom field.

Parameters:

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

    Globally unique identifier for the custom field.

  • enum_option (Id) (defaults to: required("enum_option")) —

    The ID of the enum option to relocate.

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

    The name of the enum option.

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

    The color of the enum option. Defaults to ‘none’.

  • before_enum_option (Id) (defaults to: nil) —

    An existing enum option within this custom field before which the new enum option should be inserted. Cannot be provided together with after_enum_option.

  • after_enum_option (Id) (defaults to: nil) —

    An existing enum option within this custom field after which the new enum option should be inserted. Cannot be provided together with before_enum_option.

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

    the request I/O options.

  • data (Hash) —

    the attributes to post.



99
100
101
102
 
# File 'lib/asana/resources/custom_fields.rb', line 99

def reorder_enum_option(client, custom_field: required("custom_field"), enum_option: required("enum_option"), name: required("name"), color: nil, before_enum_option: nil, after_enum_option: nil, options: {}, **data)
  with_params = data.merge(enum_option: enum_option, name: name, color: color, before_enum_option: before_enum_option, after_enum_option: after_enum_option).reject { |_,v| v.nil? || Array(v).empty? }
  Resource.new(parse(client.post("/custom_fields/#{custom_field}/enum_options/insert", body: with_params, options: options)).first, client: client)
end

Instance Method Details

#delete ⇒ Object

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

Returns:

  • an empty data record.



125
126
127
128
 
# File 'lib/asana/resources/custom_fields.rb', line 125

def delete()

  client.delete("/custom_fields/#{id}") && true
end

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

A specific, existing custom field can be updated by making a PUT request on the URL for that custom field. 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 custom field.

A custom field’s ‘type` cannot be updated.

An enum custom field’s ‘enum_options` cannot be updated with this endpoint. Instead see “Work With Enum Options” for information on how to update `enum_options`.

Parameters:

  • Returns —

    the complete updated custom field record.

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

    the request I/O options.

  • data (Hash) —

    the attributes to post.



117
118
119
120
 
# File 'lib/asana/resources/custom_fields.rb', line 117

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

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

#update_enum_option(enum_option: required("enum_option"), name: required("name"), color: nil, enabled: nil, options: {}, **data) ⇒ Object

Updates an existing enum option. Enum custom fields require at least one enabled enum option.

Parameters:

  • Returns —

    the full record of the updated enum option.

  • enum_option (Id) (defaults to: required("enum_option")) —

    Globally unique identifier for the enum option.

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

    The name of the enum option.

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

    The color of the enum option. Defaults to ‘none’.

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

    Whether or not the enum option is a selectable value for the custom field.

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

    the request I/O options.

  • data (Hash) —

    the attributes to post.



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

def update_enum_option(enum_option: required("enum_option"), name: required("name"), color: nil, enabled: nil, options: {}, **data)
  with_params = data.merge(name: name, color: color, enabled: enabled).reject { |_,v| v.nil? || Array(v).empty? }
  refresh_with(parse(client.put("/enum_options/#{enum_option}", body: with_params, options: options)).first)
end