Visit help center for the latest documentation.

Migration notes

Migrate to 3.5.10

General notes

ftrack embedded in iframe

It is no longer possible to embed ftrack in an iframe. If you are running ftrack in an iframe and are required to do so, please contact our support for assistance.

Sync users with LDAP

Users that require triggering a LDAP sync through the api must have the “Manage User” permission configured.

Migrate to 3.5.8

Developer notes

Asset version attribute validation

The version attribute on AssetVersion is now correctly validated when committing. Any non-numerical value will raise an integrity error.

To migrate your code change from:

asset_version['version'] = 'my-internal-version-number-5'

To an int value:

asset_version['version'] = 5


Alphabetical values have never been stored but was previously converted to an incremental version value or 0.

Migrate to 3.5.4

General notes

Resources pane replaced

The resources pane in the Tasks spreadsheet has been replaced by a new, improved version which shows the users schedule.

The new pane shows the the project team by default but allows you to control which users to see using filters. The timelines are no longer synchronized and the ability to double-click an item in the Gantt view to filter the resources has been removed.

Migrate to 3.5.3

General notes

Project permissions changed

If a user has the global can access projects permissions for one project, they will now be able to access other projects for which they also have a permission role.

If a user is assigned to a task, but does not have a permission role for the project they will no longer see the task in My tasks.

Developer notes

Changes to query parser

The ftrack API was not handling conversion of None values correctly, wrongly treating them as a strings. This was addressed in version 3.5.3 but if you relied on the previous parsing of “none” you would have to update your code making sure to enclose the value in quotes.

Migrate to 3.5.2

Developer notes

Asset parent valdiation

Creating an asset under leaf context nodes such as milestones or a tasks now fail as expected.

If you rely on the ability to create assets under milestones or tasks you must update your code to create the asset on an object instead (e.g. Project, Folder, Asset build, Shot, etc.). If a relation to a task is required the AssetVersion can have such relationship (task_id).

Migrate to 3.5.0

General notes

Python API and ftrack Connect must be updated

Update ftrack Connect and Python API to latest versions.

Update ftrack Connect to version 0.5.6 or later. Download the latest version from If you are running any integrations from source or have custom integrations, they must also be updated to ensure ftrack-python-api version 1.0.4 or later is used.

Planning section has been removed

The Planning section has been deprecated in favor of the new Studio overview and planning tools. Project phases, People bookings and Calendar events (holidays) have all be converted to the new calendar event entity.

Existing planned schedule has been converted and can be seen from Studio overview, under the timeline views.

See also

Studio overview

Some notable features from the old Planning section which are not present in Studio overview are:

  • It is not possible to group the schedule by task type. The new forecast report in Studio overview can show a summary of events scheduled per type.
  • An event may only have a single task type, previously a phase could have multiple types associated with it. You can add multiple events with different types.
  • There is currently no ability to print the schedule.
  • The color attribute on Phases is not present on Events. Instead, the blocks in the schedule are colored according to the new Project color.

New create project dialog

The create project dialog has been replaced with a new and more user friendly version. The new dialog does not allow configuring legacy settings or custom attributes when creating a project. These attributes can still be set in the project sidebar after creating the project.

For advanced use-cases it is possible to reproduce the old behaviour by Overriding the default create project behavior.

Project sidebar start and end date issues

A project’s start and end dates are not displayed correct if the user is in a timezone with a negative UTC offset (e.g. users in South and North America).

The issue appears as a 1 day difference between start and end dates set from the create project dialog, and what is displayed in the Sidebar.

After the fix the issue will be corrected, and all project start and end dates in the sidebar will appear 1 day later, if the user is in a timezone with negative UTC offset (e.g. Americas).

Developer notes

Python API must be updated

To update the Python API, run the following in any environment which uses the new Python API:

pip install --upgrade ftrack-python-api

Python API of versions prior to 1.0.2 will fail to initialize a session with the following error:

ftrack_api.exception.ServerCompatibilityError: Server version 3.5.x
incompatible with this version of the API which requires a server
version >= 3.3.11, < 3.4

Python API of versions prior to 1.0.4 will not be able to use custom attributes when used with ftrack version 3.5.0 or later.


The Legacy API is not affected by these changes and can be continue to be used as before.

Custom attributes are no longer returned sparse via API

Custom attributes are no longer returned sparse when accessed using the custom_attributes relation on Context, AssetVersion, User or List.

This means that if an entity has no value set for a custom attribute, the default value configured will be returned instead of None / null.

Start and end date validation

When changing start and end date-time attributes on TypedContext-derived entities (e.g. Task or Milestone) via the API, the dates are now validated to be within the project’s start and end dates.

When changing a Project’s start and end date so that the project is shorter than previously, the dates are validated to ensure that no tasks, milestones or events are scheduled outside of the project.

Phase and Bookings deprecated

Phase and bookings entities are now deprecated, and any new objects will not show up in the interface. Update any custom code using the entity types to use the new CalendarEvent type instead.

Migrate to 3.3.35

Developer notes

Enforced project and object permissions

Read permissions are now fully enforced for projects and objects. If you are not able to query certain projects or tasks via the API after this change you need to update the permissions for those users via the ftrack web interface.

Migrate to 3.3.32

General notes

Migrate to 3.3.16

General notes

Thumbnail validation

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

Developer notes

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

General notes

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

General notes

New RV plugin

ftrack 3.2.5 requires a new version of the RV plugin which can be downloaded from

Migrate to 3.2.0

General notes

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

General notes

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

General notes

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

Developer notes

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

General notes

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

Migrate to 3.0.3

Developer notes

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

General notes

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