Using Custom Attributes

A Custom attribute has a type and can be configured to have permission settings. Custom attributes can be used to filter, sort, and group data in the UI, and are accessible from the Python API.

Custom attributes can be created on lists, users, asset versions, and any other object in your workspace.

Creating custom attributes

There are several ways to create a custom attribute:

Via the Settings menu

Project-specific custom attributes can be created by clicking the toolbar Settings menu > Attributes > Create attribute to open the Create attribute dialogue.

After its creation, a project-specific custom attribute can be viewed on the System settings > Workflow > Custom Attributes page, and you will be able to see which project the attribute is linked to.

Via the Create dialogue

Open the Create dialogue by clicking the Create button in the toolbar above the tasks spreadsheet, and selecting any object to create. Scroll down to the bottom of the dialogue and click the Create attribute link to open the Create attribute dialogue.

Enter the details, select the type of object you want to add the custom attribute to in the Add to box (the Add to drop-down will always be populated by default with the first object alphabetically in your workspace, regardless of what object you have selected): if you select a specific object, the custom attribute will only be editable on that object. If you would like this custom attribute to be editable on any object, select "Projects and Objects" from the drop-down menu. Click Create when you’re done.

Via System settings

From System Settings in the profile menu, click Custom attributes in the Workflow category. This page displays all available custom attributes.

From here you can create, edit and remove custom attributes. Click the Create button to bring up the Create attribute dialogue. This is the same dialogue as the one described in the section above, except that it may contain some settings that are only available for administrators.

Enter the details and select the type of object you want to add the custom attribute to in the "Add to" box; if you select a specific object, the custom attribute will only be editable on that object. If you would like this custom attribute to be editable on any object, select "Projects and Objects" from the drop-down menu. Click Create when you’re done.

To change the order of appearance in the Info tab and Create dialogue, you can click Manual sort and drag and drop the attributes. Click Save when you’re satisfied with the result.

Viewing custom attributes

In the Tasks Spreadsheet

The spreadsheet can be configured to show, sort, and filter by custom attributes. Go to the Settings menu (gear icon) Attributes > Custom Attributes [Object] to see its custom attributes and select the attribute to add it to the spreadsheet. In the example below, we have a custom 'fps' attribute on the Shot object that we've added to our sheet.

In the Sidebar

The Info tab in the sidebar will list all custom attributes on that object type and the values can also be edited from here.

Editing values of custom attributes

Removing a custom attribute

Custom attributes can be removed by administrators from System settings. When in System settings, click Custom attributes in the Workflow category. This page displays a list of custom attributes available, and from here, you can remove attributes.

Attribute permissions

An attribute can be limited to specific user roles like project managers or restricted users. In the Create attribute dialogue, select the role(s) you want to limit the attribute to in the Permissions box.

Attribute groups

Custom attributes you create can be organized into groups to be easier to find and manage. The groups are displayed in the Custom attributes menu when clicking Settings > Attributes to the right in the toolbar.

They are also displayed as sections in the sidebar.

Attribute groups are managed at the System settings > Advanced > Attribute groups page.

Custom attribute types

Expression attribute

A custom attribute expression can pull data from other attributes and apply a variety of functions on the result. You can also grab project/global scope attributes. Expression attributes can be created on asset versions and on all object types, such as Task and Milestone.

Creating attributes

When creating an expression attribute, there are two required fields.

Result type

The type of result you expect from the expression. This affects the filters and cell renderers that can be used in spreadsheets. It also influences the resulting data type when retrieving data with the API.

Expression

This is the expression, and it needs to be inside curly brackets:

{self.bid * 10}

Everything before and after will be added as plain text to the result. E.g. Bid times five:

{self.bid * 5}

Could result in something like:

20

Data sources

Expression attributes may collect data from different sources and the sources are slightly different depending on the type of object.

Custom attributes

Custom attributes can be accessed on self. If tasks have a custom attribute called myNumber it can be used in an expression.

{self.myNumber / 10}

General sources

Cost in USD can be calculated like this:

${Project.USDExchangeRate * self.bid}

Bid days in hours can be calculated like this:

{self.bid * FTrackGlobals.workdayLength}

Functions

Functions are technical but very useful for creating powerful expressions. They map directly to database-native functions, and documentation can be found at mariadb.com.

Here are some examples:

{func.DATEDIFF(func.NOW(), Project.enddate)}
{func.sum(self.bid) * 100}
{func.substring(self.cutFrames, 1 + func.locate('-', self.cutFrames)) - func.substring(self.cutFrames, 1, func.locate('-', self.cutFrames)-1)+1}
{func.IF(TaskStatus.name == 'In progress', 'PAF', func.IF(TaskStatus.name=='Approved', 'Final', 'Rough'))}

Arithmetic operations

Common arithmetic operations can be used in expression (* / + -)

{(self.bid - self.worked) * FTrackGlobals.workdayLength}

Dynamic enumerator attribute

A dynamic enumerator is a custom attribute type that will fetch its values from a remote service. Before the values are presented in a drop-down menu, they are queried from the service via the event hub. The event includes information about the current context being edited which can be used to filter the values.

Here is a simple example of a dynamic enumerator event listener:

import ftrack_api


def callback(event):
    '''Dynamic enumerator callback.'''
    attribute_name = event['data']['attributeName']

    if attribute_name == 'product_category':
        output = [
            {
                'name': 'Furniture',
                'value': 'furniture'
            }, {
                'name': 'Car',
                'value': 'car'
            }
        ]

        return output


session = ftrack_api.Session()
session.event_hub.subscribe(
    'topic=ftrack.dynamic-enumerator', callback
)
session.event_hub.wait()