Using Custom Attributes

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.

Creating custom attributes

There are several ways to create a custom attribute:

Via the Settings menu

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

Screenshot_2022-12-14_at_12.03.11.png
 
Enter the requested details, select the type of object you want to add the custom attribute to in the Add to box, and click Create when you’re done.
 
ft_st_createatribute9.png
Image: 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.

Please note: If you create your custom attribute via the Settings menu on a specific project, it will only be available in that project. 

Tip: To change which project a custom attribute is linked to or whether the custom attribute is global or project-specific in the first place, you need to use API.

 

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.

Screenshot_2022-12-14_at_12.03.38.png
 

Enter the details, 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), and click Create when you’re done.

Screenshot_2022-12-14_at_12.02.45.png
 
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.
 

Please note: If you create your custom attribute via the Create dialogue on a specific project, it will only be available in that project. 

Tip: To change which project a custom attribute is linked to or whether the custom attribute is global or project-specific in the first place, you need to use API.

 

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.

Please note:If you create your custom attribute via the System settings > Workflow > Custom Attributes page, the newly created attribute will be available in all projects.

 

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.

Screenshot_2022-12-14_at_11.51.11.png

 

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.

Screenshot_2022-12-14_at_12.00.22.png

 

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.

 

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.

Screenshot_2022-12-14_at_12.18.04.png
 

They are also displayed as sections in the sidebar.

Screenshot_2022-12-14_at_12.22.43.png
 

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

Screenshot_2022-12-14_at_12.25.33.png
 

Custom attribute types

Screenshot_2022-12-14_at_12.26.19.png

 

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)

  • Link - Link one or many objects to the object type the attribute is created on Custom Attribute Links.
  • 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.

 

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.

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

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 for creating 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()
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.

Please note: Due to their complexity and performance reasons, hierarchical attributes are not available in the spreadsheets.
Was this article helpful?
0 out of 0 found this helpful

Articles in this section

See more