Mavenlink

Custom Fields

Custom Fields (CF) are used to store Custom Field Values on a given subject. The current supported subjects are Workspace, Story, User, and WorkspaceGroup.

CF objects have the following readable attributes:

  • name - the given field name
  • value_type - the type of all Custom Field Values on this field, defaulting to 'string'. The current types include: 'string', 'date', 'number', 'currency', 'single', or 'multi'
  • creator_id - the internal id of the User who created the custom field
  • default_text - the placeholder text. This only applies for the types: 'string', 'date', 'number' and 'currency'.
  • unique_constraint - an optional boolean constraint which forces the Custom Field Values' value to be unique across a subject_type. The default is false. This only applies for the types: 'string', 'date', 'number' and 'currency'.
  • custom_field_set_id - the custom field set the field belongs in. All custom fields are contained in a custom field set which may contain many fields.
  • write_access - the permission level required to create, update, and destroy values for this custom field (explained below)
  • read_access - the permission level required to read values for this custom field (explained below)
  • created_at - the date the CF was created
  • updated_at - the date the CF was last updated

Fetching Custom Fields

For accessing all of your visible Custom Fields for your account that the current user has access to:

curl -X GET "https://api.mavenlink.com/api/v1/custom_fields.json"

The returned CFs will be sorted by the name field in ascending order by default.

Associated Objects

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

curl "https://api.mavenlink.com/api/v1/custom_fields.json?include=creator"

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

  • creator - the user who created the custom field
  • choices - the choices added to a single or multi choice custom field

Ordering

Valid orders are:

  • updated_at
  • name

The default order is name:asc.

Getting a Custom Field

As with all resources, you can request either GET /api/v1/custom_fields.json?only=5 or GET /api/v1/custom_fields/5.json.

Creating a new Custom Field

Creating requires the current user to be the account administrator, and accepts the following params:

  • name - (required) the given field name
  • value_type - (optional) the types the Custom Field Values use. The current types include: 'string', 'date', 'number', and 'currency'
  • default_text - (optional) the placeholder text
  • unique_constraint - (optional) a boolean constraint which forces the Custom Field Values' value to be unique across a subject_type. The default is false
  • choices - (optional) the choices that a Custom Field may have. Only valid for a 'single' and 'multi' type custom fields. eg. [{'label' => 'first choice'}, {'label' => 'another choice'}]. The order will specify the choice order in the Mavenlink application.
  • custom_field_set_id - (optional) the custom field set the custom field will belong to. If the custom_field_set_id is omitted this field will belong to a Workspace set named 'Default Project Set'. Note omitting the set id will restrict this field to only be applied to workspaces.
  • write_access - (optional) the permission level required for a user to create, update, or delete a custom field value for an object.
  • read_access - (optional) the permission level required to read a custom field value for an object.
    • Regarding read_access and write_access: To set permissions access for custom fields use one of the following keys. CF in Story or Workspace custom field sets use the Workspace permission keys and CF in User and WorkspaceGroup custom field sets use Account level permissions.

      • Workspace permission keys:
        • 'project_collaboration', 'time_logging', 'financial', 'project_admin'
        • defaults:
          • read_access: 'project_collaboration'
          • write_access: 'project_admin'
      • Account level permission keys:
        • 'account_collaboration', 'project_creator', 'project_lead', 'reports_viewer', 'account_admin'
          • defaults:
            • read_access: 'account_admin'
            • write_access: 'account_admin'

      ie. to require that only those with financial access in a workspace can read a custom field value create the field with: read_access = 'financial'

You can create CF as follows:

curl -d "custom_field[name]=MyField" "https://api.mavenlink.com/api/v1/custom_fields.json"

Updating an existing Custom Field

Updating requires the current user to be the account administrator. An update operation takes the following parameters:

  • name - (required) the given field name
  • default_text - (optional) the placeholder text
  • choices - choices may be updated through their CF's choices attribute. To change a choice's name or oder, specify the id. To add new choices, do not specify an id and the choices will be created in the provided order. eg. [{'label' => 'a brand new choice'}, {'id' => '1', 'label' => 'the first choice is now the second choice and has this long name'},]. If a previous choice of the custom field is omitted, that choice will be soft deleted so that the values will not point to invalid choices.
  • custom_field_set_id - (optional) the custom field set this custom field belongs to. Must be of the same subject_type.
  • write_access - (optional) the permission level required for a user to create, update, or delete a custom field value for an object.
  • read_access - (optional) the permission level required to read a custom field value for an object.

Note: unique_constraint and value_type cannot be changed.

You can edit CF as follows:

curl -X PUT -d "custom_field[name]='My New Field Name'" "https://api.mavenlink.com/api/v1/custom_fields/1.json"

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

Destroying an existing Custom Field

Destroying requires the current user to be the account administrator. Destroying a CF destroys all associated Custom Field Values. You can delete a CF as follows:

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

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