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.

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

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 Create dialog

Open the Create dialog by clicking the Create button in the toolbar above the tasks spreadsheet, and selecting an object to create. Scroll down to the bottom of the dialog 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. Click Create when you’re done.

Via the settings button

Click the settings button to the right in the tasks spreadsheet toolbar. Select Attributes ‣ Create attribute to open the Create attribute dialog.

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 System settings

From System settings in the profile menu, click Custom attributes in the Advanced 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 dialog. This is the same dialog 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 dialog 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 Advanced 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 dialog, 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
  • date
  • dynamic enumerator
  • enumerator
  • expression
  • number
  • text

Enumerators can be configured to be either of single or multi select type.

Text attributes can be configured to be formatted as Markdown when supported.

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

What 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
     <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()
Did this answer your question?