Mavenlink

Custom Field Values

Custom Field Values (CFV) are used to save values for a specific Custom Field, previously set up via the Custom Field endpoint, and for a specific subject (i.e: a Workspace, Story or User).

CFV objects have the following readable attributes:

  • id - the internal custom field value id
  • subject_type - the type of entity the custom field value is associated with. Valid types include 'Workspace', 'Story', and 'User'
  • subject_id - the internal id of the entity type defined by the subject_type field
  • value - the value applied to the subject
  • type - they type of value. The Current valid values are: 'string', 'date', 'number', 'currency' 'single', and 'multi'
  • setter_id - the internal id of the User who has set value
  • account_id - the id of the account the custom field value is on
  • custom_field_id - the internal id of the associated custom field
  • custom_field_name - the name of the associated custom field
  • created_at - the date the custom field value was created in Mavenlink
  • updated_at - the date the custom field value was last updated

Fetching Custom Field Values

Accessing a list of CFVs requires the following parameter:

* `subject_type` - (required) the type of entity the custom field value is associated with. This currently accepts `Workspace`, `Story` and `User` as valid value

For example to list the custom field values for all the workspaces the current user has access too:

curl -X GET -d "subject_type=Workspace" "https://api.mavenlink.com/api/v1/custom_field_values.json"

The returned CFVs will be sorted by the updated_at field in ascending order by default.

Notes regarding permissions for subject types:
  • When subject_type is 'Workspace' or 'Story', Report Viewers will access all CFVs. Otherwise, the list of CFVs will be restricted by your participating workspaces on your account.
  • When subject_type is 'WorkspaceGroup' or 'User', you must be the account administrator to access these CFVs.

Associated Objects

You can include CFV's associations with the include param. For example, to include returned CFV's associated custom field, you would do the following:

curl "https://api.mavenlink.com/api/v1/custom_field_values.json?include=custom_field"

In this example, our API will ensure that the returned JSON contains top-level keys called custom_fields where you can find associated data by inspecting CFVs' custom_fields_ids fields. See Object Associations to learn more. The following associations can be requested through the API:

  • custom_field - the associated custom field, returned in the custom_fields top-level key
  • setter - the associated user, returned in the users top-level key

Filtering CFV

The Mavenlink API allows you to pass in filter conditions to allow the retrieval of only certain CFVs that meet those conditions.

  • with_subject_id - only CFVs associated to an entity of the type of subject_type with the given ID
  • with_setter_id - only CFVs set by a user with the given ID
  • with_custom_field_id - only CFVs associated to a custom field with the given ID

For example to get all CFV associated to a workspace with the id 5:

curl "https://api.mavenlink.com/api/v1/custom_field_values.json?with_subject_id=5&subject_type=Workspace"

Ordering CFV

Valid orders are:

  • updated_at
  • created_at

The default order is updated_at:asc.

Getting a CFV

As with all resources, you can request either GET /api/v1/custom_field_values.json?only=5 or GET /api/v1/custom_field_values/5.json. In both cases, default filters will be applied.

Notes regarding permissions for subject types:
  • subject_type = Workspace or Story - Report Viewers will access all CFVs. Otherwise, the list of CFVs will be restricted by your participating workspaces on your account
  • subject_type = User - You must be the account administrator to access these CFVs

Creating a new CFV

CFV belong to a custom field and are associated to a subject. It takes the following parameters:

  • subject_type - (required) the type of entity the custom field value is associated with. This currently only accepts Workspace as valid value
  • subject_id - (required) the internal id of the entity type defined by the subject_type field
  • custom_field_id - (required) the internal id of the associated custom field
  • value - (required) the value of the associated custom field

The value formats for different types are as follows:

  • string - <text_string>, eg. 'foo'
  • date - <ISO_8601 Date Format> eg. '2014-02-25' (accepted range: '1900-01-01' to '2015-12-31')
  • number - <integer_value> eg. '13'
  • currency - [<int_value_in_cents>, <currency_code>] eg. '[998, USD]'
  • single and multi - [<choice_ids>] eg. '[1, 2, 4]'

You can create CFV as follows:

curl -d "custom_field_value[subject_type]=Workspace" -d "custom_field_value[subject_id]=10" -d "custom_field_value[custom_field_id]=1" -d "custom_field_value[value]=50" "https://api.mavenlink.com/api/v1/custom_field_values.json"
Notes regarding permissions for subject types:
  • subject_type = Workspace or Story - Account administrators can create CFVs for all workspaces across the account regardless of participation. Otherwise, only project leads can create CFVs for their participating workspaces
  • subject_type = User - You must be the account administrator to create a CFV for a User

Updating an existing CFV

An update operation takes the following parameter:

  • value - (required) the value of the associated custom field

You can edit CFV as follows:

curl -X PUT -d "custom_field_value[value]=40" "https://api.mavenlink.com/api/v1/custom_field_values/1.json"

The response will contain the JSON representation of the updated CFV or an error message indicating which arguments are missing or erroneous.

Notes regarding permissions for subject types:

The same notes apply for creating CFVs.

Destroying an existing CFV

You can delete CFV as follows:

curl -X DELETE "https://api.mavenlink.com/api/v1/custom_field_values/1.json"

The response will have no content and HTTP 204 status code if the CFV has been successfully deleted, or a JSON error message indicating why the CFV could not be deleted.