Mavenlink

Custom Field Sets

Custom Field Sets (CFS) contain Custom Fields and define the fields' subject type. The current supported subjects are Workspace, Story, User, and WorkspaceGroup.

CFS objects have the following readable attributes:

  • name - the given set name
  • subject_type - the type of objects contained by the CFS. The current supported subjects are Workspace, Story, User, and WorkspaceGroup.
  • created_at - the date the CFS was created
  • updated_at - the date the CFS was last updated

Fetching Custom Field Sets

For accessing all of the visible Custom Field Sets for your account:

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

The returned CFSs will be sorted by the created_at field in descending order by default.

Associated Objects

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

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

In this example, our API will ensure that the returned JSON for each set will include a key called custom_field_ids. Additionally the JSON will include a top level key custom_fields with all of the associated custom fields. See Object Associations to learn more. The following asociations can be requested through the API:

  • custom_fields - the custom fields that belong to this CFS

Ordering

Valid orders are:

  • created_at:desc The default order is created_at:desc.

Getting a Custom Field Set

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

Creating a new Custom Field Set

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

  • name - (required) the given field name
  • subject_type - (required) the type of objects contained by the CFS. The current supported subjects are Workspace, Story, User, and WorkspaceGroup.

You can create CFS as follows:

curl -d "custom_field_set[name]=MySetName" "https://api.mavenlink.com/api/v1/custom_field_sets.json"

Updating an existing Custom Field Set

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

  • name - (required) the given set name

Note: subject_type cannot be changed.

You can edit CFS as follows:

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

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

Destroying an existing Custom Field Set

Destroying requires the current user to be the account administrator. Destroying a set will delete all contained custom fields and all custom field values for those fields. You can delete a CFS as follows:

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

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