Migration 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 https://www.ftrack.com/portfolio/connect. 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.

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

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.

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.

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.

Asset version dependencies are now called links¶

Asset version dependencies are now called links in the ftrack sidebar. This is only a change in the web interface and no further actions are required.

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.

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.

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.

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.

Uploading media for review¶

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

New RV plugin¶

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

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.

Dependencies are now called links and can be used for all objects¶

Dependencies are now called links and links are no longer restricted to linking Asset builds to Shots. Any objects can be linked together using the new links tab in the sidebar.

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.

Milestones¶

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

Removed replace option in review browser¶

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

Time zone support and datetime.datetime.¶

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.

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

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.

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(
      'ftrack_plugin:action.register'
  )

  # 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):
      logger.debug(
          'Not subscribing plugin as passed argument {0!r} is not an '
          'ftrack.Registry instance.'.format(registry)
      )
      return

  ...

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):
    logger.debug(
        'Not subscribing plugin as passed argument {0} is not an '
        'ftrack_api.Session instance.'.format(session)
    )
    return

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.

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.

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.

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.

Events¶

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
  • TOPICS -> EVENT_HUB
  • TOPIC_HANDLERS -> EVENT_HANDLERS
  • FTRACK_TOPIC_PLUGIN_PATH -> FTRACK_EVENT_PLUGIN_PATH

• 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