ftrack ships with a set of default attributes on each object type. To customize the system to your needs and workflow you can use custom attributes, and an attribute can easily be added to a spreadsheet via the settings button to the right in the toolbar.

Custom attributes can be used to track data on objects. An attribute has a type and can be configured to have a permission setting. Custom attributes can be used to filter, sort and group data and are also accessible from the Python API.

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

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.

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

The values saved in custom attributes can be edited in the same way as other attributes, either by:

Clicking a cell in the spreadsheet.
Using the sidebar.
Using the Python API.

Creating custom attributes

There are several ways to create a custom attribute.

Via the settings button

Click the Settings Menu > Attributes > Create attribute to open the Create attribute dialogue.

Enter the details and select the type of object you want to add the custom attribute to in the "Add to" box. Click Create when you’re done.

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.

Enter the details and select the type of object you want to add the custom attribute to in the "Add to" box (the default will always be "Asset Build" regardless of the object you've chosen). 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. 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.

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 certain 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

You can create custom attributes of the following types:

Boolean - Checkbox field
Date - Selectable or typeable date field reflecting the date style of your System Settings > Advanced > Advance settings date formatting.
Dynamic enumerator - API scriptable List field, can be single or multi-selection. (Click link for more info)
Enumerator - regular List field whose items can be formatted in the "Create attribute" dialogue window. You can set it as single or multi-selection.
Expression - Pull and combine data from other attributes using functions to calculate the expression attribute result. (Click link for more info)
Number - Number field with the option to turn decimals on or off.
Text - Standard text field with the option to be formatted as Markdown when supported.
Link - Link one or many objects to the object type the attribute is created on Custom Attribute Links.

Hierarchical attribute

Hierarchical attributes are inherited all the way down to the bottom of the project structure. They are useful when attribute values need to be overridden only for certain objects.

Examples are frame rate and render priority. For instance, the frame rate would be the same for the entire project except for certain shots that for some reason should run in slow motion.

Hierarchical attributes can only be created from System settings.

They are accessible via the API, in the Create dialogue and in the sidebar.

Note: Due to their complexity and performance reasons, hierarchical attributes are not available in the spreadsheets.

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:

Data sources

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

Sources for object types such as Task

self
id
name
startdate
enddate
bid
worked
description

TaskType
name
billable

TaskStatus
name

StatusType
name
short

Priority
name

Sources for Asset versions

self
version
date
comment

StatusType
name

AssetStatus
name

Asset
name

AssetType
name
short

WorkTask
<same as self on Task>

WorkTaskStatus
name

WorkTaskType
name

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

All expression attributes can collect data from these sources:

Project - Can be used to access attributes from a project.
name
fullname
isglobal
startdate
enddate
status

FTrackGlobals - Can be used to access some of the system settings.
workdayLength

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 to create powerful expressions. They map directly to database-native functions and documentation can be found at mariadb.com. Here is a list of the supported functions:

MAX - Maximum value in group (only useful in spreadsheet functions)
MIN - Minimum value in group (only useful in spreadsheet functions)
AVG - Average value in group (only useful in spreadsheet functions)
SUM - Sum of the values in the group (only useful in spreadsheet functions)
COUNT - Number of values in group (only useful in spreadsheet functions)
SUBSTRING - Return a substring of the string
LOCATE - Locate the positon of a substring in a string
IF - if condtion
NOW - Current time and date
DATEDIFF - Difference between two dates
WEEKDAY - Return day of week from date (0 = Monday, 6 = Sunday)
CONCAT - Concatinate strings
ROUND - Round a number to specified number of decimals
CEIL - Returns the smallest integer value not less than provided value
FLOOR - Returns the largest integer value not greater than provided value

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()