Custom Attributes

Custom attributes let you define your own metadata fields on files in a workspace—things like production status, external IDs, links to tools like Jira or Miro, or technical data such as poly counts. This page covers how workspace admins configure attributes, how users edit values on files, how filtering works, and how attributes appear in the API.

​

Who Can Use Custom Attributes

• Workspace admins
  • Create, edit, reorder, duplicate, and delete custom attributes.
  • Decide which attributes are filterable.
• Users with upload access
  • Edit values for custom attributes on files.
• All users who can view files
  • See filterable custom attributes in the Files view filters.

​

Attribute Primitives and Types

In general, custom attributes have:

• Name — the label shown in the UI (must be unique).
• Primitive — the underlying data type.
• Type — how values are entered or constrained for that primitive.

Supported primitives:

• Text — Free-form text.
• Number — Numeric values.
• Boolean — True/false values.
• Date — Date.

Supported types:

• For Text and Number:
  • Any value — Users can enter any value of the appropriate primitive.
  • Select — Users pick a single option from a predefined list.
  • Multi-Select — Users pick one or more options from a predefined list.
• For Boolean and Date:
  • These do not have a separate Type setting; the value is always a single Boolean or Date.

All attributes:

• Must have a unique name within the workspace.
• Are visible on all supported objects (currently files only).

​

Managing Attributes

To configure which attributes exist in a workspace:

1. Open the Mudstack desktop app.
2. Go to Workspace Settings.
3. Open the Custom attributes page.

Only workspace admins can see and use the Custom attributes page.

​

Discriminators

Discriminators let you target specific sets of objects with different attribute configurations based on a query.

• A discriminator defines which files a given attribute set applies to (for example, files in a certain path, with a certain extension, or matching other file metadata).
• If there is no discriminator, the attribute set applies to all files in the workspace.
• There is one shared draft per discriminator (or per object when there is no discriminator). All workspace admins editing that discriminator work on the same draft.

Future releases will extend discriminators so you can configure attributes for other object types (folders, file versions, libraries, workspaces) using similar query-based rules. Behavior:

• The draft is saved to the cloud automatically as you make changes.
• There is only one draft per discriminator (or per object when there is no discriminator).
• Other workspace admins see the same draft and can collaborate on it.
• Changes in the draft do not affect files until you promote it.

​

Create a New Attribute

To add a new attribute to the current discriminator’s draft:

1. Click Create a new attribute.
2. A new row appears at the bottom of the attribute list.
3. Set the Name (must be unique).
4. Set the Primitive:
   • Text
   • Number
   • Boolean
   • Date
5. Set the Type (for Text and Number primitives only):
   • Any value
   • Select
   • Multi-Select
   • For Boolean and Date, Type is fixed and not editable.
6. (Optional) Click Options:
   • For Select and Multi-Select, define the list of allowed options and any relevant validation (e.g. required, max selections).
   • Set a default value (can be empty).
7. Toggle Show in filters if you want this attribute to appear in the Files view filter list (see Filtering and Searching).

​

Required Dropdown Values

For Select and Multi-Select attributes:

• Attributes that are configured as active/required must have a valid value before you can save changes.
• If a dropdown-type attribute is missing a required value:
  • The attribute row shows a warning indicating it’s incomplete.
  • You must resolve the warning (set a valid value) before the change can be pushed.

​

Edit an Existing Attribute

Within the draft, you can update:

• Name
• Type (within the same primitive, where applicable for Text/Number)
• Options (for Select / Multi-Select)
• Default value
• Filterable / Show in filters toggle
• Order in the list

Editing rules:

• You cannot change the Primitive of an attribute after it has been created and promoted.
• If you need a different primitive (for example, changing Text to Number), create a new attribute and migrate values as needed.

To edit:

1. Locate the attribute in the list.
2. Use the edit button to update:
   • Name of the attribute.
   • If the attribute is filterable.
3. Drag the attribute to change its order. This order controls how attributes appear on files and in filter lists.

All edits you make here are part of the draft and are saved automatically.

​

Delete an Attribute

1. Find the attribute in the draft list.
2. Click the Delete button on that row.
3. Confirm deletion when prompted.

When an attribute is deleted and the draft is later promoted:

• Existing values on files are preserved on the record until the next write to that file, but the attribute will no longer be editable.
• The attribute is removed from the workspace configuration and will no longer appear in the UI or filters.

​

Reordering Attributes

You can drag attributes in the draft list to change their order.

• The order on the Custom attributes page controls:
  • The order attributes appear on files.
  • The order filterable custom attributes appear in filter lists.

Creating attributes always adds them to the end of the list. Creating attributes directly in-between other attributes by specifying a position is not supported in this release.

​

Promoting Attribute Changes

When you are happy with the draft:

1. Click Promote (or the equivalent promote action) on the Custom attributes page.
2. Mudstack validates the entire draft:
   • Attribute names are unique.
   • Attribute definitions are compatible with existing data as required.
   • Filter and option configurations are consistent.
3. If validation fails, you’ll see errors to correct in the draft before you can promote again.
4. If validation succeeds, the draft becomes the new promoted configuration for that discriminator.

​

Attribute Values on Files

​

Editing Values

With upload access, you can edit values for any custom attribute defined in the workspace:

1. Open a file.
2. Go to the Info tab.
3. Scroll to Custom attributes.
4. Update the value for the attribute you want to change.

Behavior:

• All supported primitives and types are editable:
  • Text (Any value, Select, Multi-Select).
  • Number (Any value, Select, Multi-Select).
  • Boolean.
  • Date.
• Attributes appear in the order defined on the Custom attributes page.
• Changes to attribute values are treated like other local changes:
  • They appear in the Changes View.
  • Pushing the change creates a web-based commit, just like edits to built-in attributes.

​

When Values Are Updated

• Local edits to attribute values become part of your workspace’s history once pushed.
• Users see updated attribute values as soon as:
  • The commit containing the changes is synced, and
  • They fetch or refresh data for those files.

​

Filtering and Searching by Custom Attributes

Filterable custom attributes can help your artists find files based on your own custom criteria.

​

Making Attributes Filterable

• Each attribute has a Filterable option that can be toggled on the Custom attributes page.
• Only attributes marked as filterable appear in the filters panel in the files view

​

Using Custom Attributes as Filters

To filter by a custom attribute:

1. Open Files.
2. Open the Filter panel.
3. In the filter list, you’ll see:
   • Built-in (base) attributes.
   • Any custom attributes marked as filterable.
4. Click a filterable custom attribute to see its available facets (values).
5. Click a facet to filter files by that attribute value.

​

API Behavior for Custom Attributes

Custom attributes are available through the API both at the definition level and on individual objects. See the API documentation for more information

​

Attribute Definitions in API Responses

When you request an object that uses custom attributes, the response includes information about the attributes that exist in the workspace. For each attribute definition, the API includes at minimum:

• title - Attribute Name
• type - Primitive
• enum - (if the type supports options, such as Select or Multi-Select)
• displayorder - Order of an attibute on an object

Filterable attributes will show under searchable

​

Attribute Values on Objects

For each file with custom attributes, the object’s representation includes at minimum:

• Attribute name
• Primitive and Type
• Value

Future releases will extend this behavior so that folders, file versions, libraries, and workspace-level entities expose their own custom attributes and values through the API.

Note: Attribute and value CRUD endpoints are exposed via the API. External tools and plugins can create/update attributes and attribute values, and those changes will be reflected in the app once fetched.

​

How plugins work with custom attributes

Plugins can:

• Read workspace custom attribute definitions and values.
• Create or update custom attribute values.
• Create or update attribute definitions via the API (where permitted).

This enables workflows such as:

• Automatically populating a custom attribute from an external system (e.g. Jira ticket IDs, contract IDs).
• Keeping a large dropdown list in sync with external data (e.g. IP or contract lookup tables maintained outside Mudstack).
• Interrogating a file on new version and updating custom attributes (e.g. Poly count, material count, image dimensions)