Migration notes

Migrate to 3.3.32

Migrate to 3.3.16

Thumbnails are now validated when set via the web interface or the API. Thumbnails must one of the following file types: bmp, gif, jpeg, jpg, png, tif, tiff.

When set from the API, the thumbnail component should be a file component present in the server location.

Migrate to 3.3.2

Legacy API changes

Custom attributes of types date and number must be of valid type or castable to valid type:

  • Date: datetime.datetime or formatted as %Y-%m-%dT%H:%M:%S.
  • Number: float or int or the corresponding string representation: E.g. str(42), str(42.0).
  • Boolean: bool or as strings ‘1’ or ‘0’.

When setting custom attribute values on enumerators the value must be a valid option. The multi and single selection setting will be enforced to stop users from adding multiple values to a single select enumerator.

Migrate to 3.3.0

Files tab

The files tab in the ftrack sidebar has been removed and any uploaded files have been converted into versions with components. To upload files to objects in the web UI, use the versions tab in the sidebar instead.

Attachments converted to components

Attachments in ftrack are now represented by components. This enables a simpler and a more unified way of how files are handled but also to allow for greater flexibility when managing data.

ftrack.server location

A new built-in location has been created called ftrack.server which represents all components currently stored on the ftrack server. Any files uploaded to the server including thumbnails, review media and more will be placed in this location.

Local installation

When upgrading to 3.3, unused files in the /opt/ftrack_config/data/attachments folder will be removed. The remaining files will be moved into an id folder structure to avoid having to many files in the same folder. A file with name a7394f1e-a474-417b-8962-0c9b5d719ff7 will become a/7/3/9/4f1e-a474-417b-8962-0c9b5d719ff7 after the migration.

Developer notes

Attachment endpoints

The /attachment/get?attachmentid=SOME_ID endpoint has been deprecated and have been replaced with /component/get?id=SOME_ID. Existing components using that as their resource identifier have either been converted and moved to the ftrack.server location or their resource identifier has been converted to use the new URL and should continue to function as before.

The /attachment/getAttachment?attachmentid=SOME_ID endpoint has been deprecated and have been replaced with /component/get?id=SOME_ID. The old endpoint will redirect to the new during a period of transition.

Legacy API changes

The Attachment class is no longer available in the API together with the method getAttachments on Tasks.

The createAttachment method on Tasks have been updated to publish versions instead of creating an Attachment to be somewhat backwards compatible.

Upload and attach a file to a task in ftrack using the legacy API like this and then get the URL that can be used to retrieve it:

task = ftrack.Task(TASK_ID)
component = task.createAttachment('/path/to/file')
url = component.getUrl()

ftrack.Note.createAttachment(), ftrack.Note.getAttachments(), ftrack.Job.createAttachment() and ftrack.Job.getAttachments() have been added to allow for backwards compatibility when adding files to jobs and notes.

ftrack.Component.getUrl() has also been added to simplify retrieval of the component URL.


All methods will return ftrack.Component since that is the new representation for attachments.

Uploading media for review

Uploading media for review can be done using both the legacy API and the new python api.

See also


Migrate to 3.2.5

New RV plugin

ftrack 3.2.5 requires a new version of the RV plugin which can be downloaded from https://ftrack.com

Migrate to 3.2.0

Shots / Asset builds spreadsheet renamed to Tasks

The Shots / Asset builds spreadsheet has been renamed to Tasks.

Multiple sidebar tabs replaced by Tasks

The different tabs Shots, Asset builds, Tasks and Related tasks which appeared in the sidebar on different kind of objects have been been combined in to a single tab called Tasks.

Tasks lists all immediate children of the object you are currently viewing if the object can have children. If not, it will show a list of objects on the same level in the hierarchy.

Removed keyboard shortcuts

Keyboard shortcuts for creating objects in the tasks spreadsheet has been removed. To create objects see Populating the project.

Milestones represented as separate object

Tasks which had a start and end date set to the same time would be displayed as milestones in the web interface. These have been converted to milestone objects.

If any tasks was erroneously converted to milestones, they can be converted back by right-clicking on the milestone in the main spreadsheet and choosing Convert to task from the context menu.

Removed Asset Builds section in project outliner

There is no longer a dedicated asset builds section in the project outliner. Instead a new object called folder has been added to ftrack and for existing projects the Asset builds section in the project outliner has been converted into a folder object with the same name. For new projects the user can create any structure he or she would like.

All section removed from the project outliner

The All section in the project outliner has been removed. To view the whole project, press the project name at the top of the project outliner.

Ability to replace with sequence in ftrackreview removed

The replace feature in the ftrack review browser has been removed from sequences and is now only available on lists.

Developer notes

There are no API changes in this release that affect the signatures of the public methods in the python API. However internals have changed and a new version of the API must therefore be downloaded. It can be downloaded from the System settings->About page.


Milestones no longer have a start date attribute and can be identified by their object type.

Identify milestone:

print milestone.get('objectType')  # Milestone

Change of layout name

The custom sidebar layout for the info tab has been renamed from siderbar_info to sidebar_info. Read more

Migrate to 3.1.4

Removed replace option in review browser

Replace option in the entity browser in internal review has been removed for all entities except Lists.

Developer notes

Time zone support and datetime.datetime.


This change only affects users with time zone support enabled, Read more.

Previously the API returned datetime.datetime in the time zone of the API user. To reduce confusion the API now handles all datetime.datetime objects as UTC, if timezone support is enabled.

Please contact support if you have questions or need help adjusting your scripts to this change.

Migrate to 3.1.0

Update server configuration

Local installations need to update their ftrack configuration file with the Server URL to allow ftrack to function properly together with a Service secret.

Update server startup script

Local installations need to replace the scripts they use to run the ftrack server. New script are located in /opt/ftrack/init.d. Local installations should use supervisord_local instead of supervisord_apache and ftrack. Servers are now running Nginx with uwsgi instead of Apache with mod_wsgi.

cp /opt/ftrack/init.d/supervisord_local /etc/init.d/
chmod +x /etc/init.d/supervisord_local
chkconfig ftrack off
chkconfig supervisord_apache off
chkconfig supervisord_local on
service supervisord_local start

Developer notes

Event server port change

The event server is now using the same port as the ftrack server to get around issues where firewalls are blocking it. A new version of the python API needs to be downloaded to use this server version. It can be downloaded from the System settings->About page.

Migrate to 3.0.29

Validate arguments in plugin register function

To make event and location plugin register functions work with both old and new API the function should be updated to validate the input arguments. For old plugins the register method should validate that the first input is of type ftrack.Registry.

import ftrack

class Action(ftrack.Action):
    '''My Action class.'''

def register(registry, **kw):
  '''Register action.'''

  logger = logging.getLogger(

  # Validate that registry is an instance of ftrack.Registry. If not,
  # assume that register is being called from a new or incompatible API and
  # return without doing anything.
  if not isinstance(registry, ftrack.Registry):
          'Not subscribing plugin as passed argument {0!r} is not an '
          'ftrack.Registry instance.'.format(registry)


Plugins using the new API should validate that the first input is of type ftrack_api.Session.

# Validate that session is an instance of ftrack_api.Session. If not, assume
# that register is being called from an old or incompatible API and return
# without doing anything.
if not isinstance(session, ftrack_api.Session):
        'Not subscribing plugin as passed argument {0} is not an '
        'ftrack_api.Session instance.'.format(session)

Migrate to 3.0.9

Display bid as days bug

We recently found a bug in ftrack version 3 which causes the setting display bid as days to not be respected. The issue is present in ftrack versions 3.0.1 to 3.0.8. If you have enabled the setting Display bid as days and set any bid values after upgrading to ftrack 3, please ensure that your bid values are correct.

To do so first take a moment and ensure that the setting “Workday length” in System settings->Scheduling->Settings is correct. Then look at one of your recent projects and check if the “Bid as days” column in the spreadsheet is correct.

If you need help with updating bid values which have been wrongly saved, please contact support by emailing support@ftrack.com.

Migrate to 3.0.3

Action event data format

The event data passed for action discover and launch events has been changed. The keys actionData and context has been removed and their contents has been moved to the root level. If you have modified the default application hooks in ftrack Connect or have developed custom actions they will need to be updated to use the new format. Read more

Removed attribute

The parent_type attribute is no longer available on task objects. This means that task.get(‘parent_type’) will not work.

Migrate from 2.x.x to 3.0.x

Timesheet value format

When entering time in the timesheet a single digit now means minutes instead of hours. The format has been updated for greater flexibility. Read more

Time tracking options removed

The two options open for everyone and require comment which could be used to limit who and how time can be logged have been removed from the web interface.

Removed delete keyboard shortcut

The keyboard shortcut for deleting objects in the spreadsheet has been removed.

New permission: Manage users

A new permission has been added to control the ability to manage users. The permission has given to any role that had access to settings.

Project full name instead of short name / code

Whenever a project name is displayed in the interface, the project’s full name will be used instead of the short name / code.

Developer notes

Change details are not always included for deleted objects

When listening to update events and accessing the change details for a deleted object, a property may have a value of None.

Managed locations will no longer overwrite data

Creating a component in a managed location will throw an error if a file already exists in the target path.


The event system used by the API has been heavily improved with a few changes. For more information about working with events, please refer to the documentation.

  • “Topic” has been renamed to “Event” throughout the API.
    • TopicHub -> EventHub
    • TopicEvent -> Event
    • TopicHubConnectionError -> EventHubConnectionError
  • ftrack.EventHub.unsubscribe() now accepts only the subscriber id as parameter.

  • ftrack.EventHub.connect() now raises ftrack.EventHubConnectionError if already connected.

  • ftrack.EventHub.disconnect() now raises ftrack.EventHubConnectionError if not connected.

  • Location events renamed
    • ‘component-added-to-location’ -> ‘ftrack.location.component-added’
    • ‘component-removed-from-location’ -> ‘ftrack.location.component-removed’
  • Location event handlers should now accept a single ftrack.Event instance.

  • Action handlers should now accept a single event argument with the previous data information available in event[‘data’]. The user id is now available in event[‘source’][‘user’][‘id’].

  • ftrack.EventHub.subscribe() ‘topic’ argument is now ‘subscription’ and can take a more expressive form for greater control over events delivered to the callback. As such, previous ‘topic’ strings should be converted to a subscription like ‘topic=the/topic/string’ to avoid errors.

  • ftrack.EventHub.subscribe() no longer accepts callbackID. Due to use of more complex subscriptions it is no viable to support basic callback ids per topic.

  • Event.topic property has been removed. Instead use, event[‘topic’].

  • ftrack.EventHub.publish() now accepts an Event instance as first argument. This instance should contain the event data rather than passing