To upgrade ftrack self hosted to 4.11 you must first upgrade to a 4.10 version. The database migrations are not compatible when upgrading directly from 4.9 (or earlier) to 4.11.

A new Collaborator entity has been introduced which is used to represent collaborators in a client review. ReviewSessionInvitee and ReviewSessionObjectStatus are affected by this change as they now have a resource_id attribute pointing to the new Collaborator (or an internal User entity). These changes attempt to be backwards compatible in a best effort, but there can be situations where they are not. It is recommended to update any tools that are using the ftrack API to manage client reviews to instead use the new Collaborator entity and set resource_id on ReviewSessionInvitee and ReviewSessionObjectStatus. review_session_invitee_id is still available on ReviewSessionObjectStatus but will be removed in un upcoming release of ftrack.

The legacy client review interface that could be enabled via system settings has been removed in this version.

Deprecated entities

Deprecated entity types `Conversation`, `Message` and `Participant` have been removed from the API.

Custom attribute links are no longer considered an experimental feature. During its experimental phase it was determined that allowing the destination to be of the generic type "Object" became confusing. Therefore, future custom attribute link configurations must specify `object_type_id_to` when linking towards object types such as Task, Sequence and Shot.

Existing custom attribute link configurations linking towards `object` will be converted

automatically and the `object_type_id_to` will be set to the most commonly used object type.

If no links are present the `object_type_id_to` will default to task.

In addition Component have been removed from the list of valid destination types. If there are existing custom attribute configurations they will however be left as is. Please let us know if this is a feature you would like to see return.

The ability to link a list to tasks will be removed in ftrack 4.7. We recommend

using the new custom attribute link feature instead if you want to create links

between task and list.

The pika library is updated to version 1.1.0. If you have specified a custom

heartbeat interval in your amqp host connection string ( ftrack.amqp_host )

please make sure to update it to "heartbeat" from "heartbeat_interval".

heartbeat_interval will still work but will through a deprecation warning.

The `Can manage custom widgets` permission is now required to add or update custom widgets and web views in ftrack. After the 4.6 migration all security roles with access to System Settings will have this permission.

In addition to the permission the `Custom widgets`, the feature must be enabled from System Settings > Advanced > Custom widgets. This feature will be automatically enabled if you already have a Web view widget.

With the Capacity forecast dashboard on the Overview page leaving beta, old dashboards will be automatically replaced with the new version. Since the new dashboard works differently the filter settings will be cleared.

To get started with the new dashboard it is recommended to go through the quick get started guide available from the Capacity Forecast dashboard page.

While the new dashboard comes with a wide range of new features, some has been retired now that the dashboard leaves the beta stage:

Nginx version updated to version 1.18. This should not require any action.

Uploading media directly to a client review has changed so that the asset versions version number is now copied to the review session object and the name is now the asset name and not the uploaded file name. This typically means that the name will be the same but does not include the file type extension.

Adding media to a client review has changed so that name and description has changed place. After the update name and descriptions are set as:

name is the task name if the version is related to a task, otherwise the asset name will be used.

description is the name of the asset parent object. If the asset is uploaded or published directly under the project this field will be empty.

Note categories are now referred to as note labels and a note can have multiple
labels.

2-factor authentication is enabled by default but a security key must be generated and added to the server configuration before it can be used. Read more here.

API changes

The category_id attribute and category relationships is still kept for backwards
compatibility but will be removed in an upcoming release. If a note has only
one label, the category and category_id will behave as in 4.2, but if there are
multiple labels only one of them will be represented by those attributes.

New relationships and schemas have been introduced to allow for transition to
the new note labels and maintain as much backwards compatibility as possible.

The NoteCategory entity still exists but should be replaced by the new NoteLabel
entity. NoteCategory inherit from NoteLabel which makes entities interchangeable.

The new NoteLabelLink entity should be used to add labels to notes. It has the
attributes label_id and note_id. Where label_id refers to the
NoteLabel/NoteCategory. The NoteLabelLink entity also has the relationships note
and label.

The Note entity has a new relationship called note_label_links which is an array
of NoteLabelLink entities.

Creating a note would previously return category_id in the response to
the create operation, it will no longer be included in the response and will
have to be queried.

Update events sent via the event hub will no longer contain a value for
categoryid, instead NoteLabelLink will be a separate entity in the update event.

Note events stored in the database that can be queried via the API as Event will
no longer contain categoryid. Instead separate events will be created for
the note with action set to db.all.notelabellink.

Users do not receive notifications if they do not have access to a project

Users without access to a project does not receive notifications for assignments / statuses on the project.

Client review collaborator interface update

The client review interface used by collaborators have been replaced by a new interface. If you encounter problems with the new interface, you can switch back to the previous interface from System settings > Review. The old version of the review interface will be removed in a future release.

Update events for private projects

Update events will only be sent out for the projects which the user has access to. Global API keys have access to all projects with open access. If you have a script that reacts to changes in ftrack using update events, ensure it has sufficient rights to access all required projects.

Modifying UserSecurityRole deprecated

Adding and modifying UserSecurityRole directly is no longer supported. Instead the new actions add_user_security_role, remove_user_security_role, grant_user_security_role_project and revoke_user_security_role_project should be used. add_user_security_role and remove_user_security_role accept user_id and role_id as parameters, while grant_user_security_role_project and revoke_user_security_role_project accept the additional parameters project_id or all_open_projects.

Projects relation removed from UserSecurityRole

The projects relation on UserSecurityRole has been removed and replaced by the user_security_role_projects relation which references the new object UserSecurityRoleProject.

Adding and removing security roles using legacy API

Support for adding and removing security roles to users and granting access to projects for users using legacy API has been removed. Please use new API for these operations instead.

Version 4.0.3 enforces stricter request validation and will not allow POST requests to application or API endpoints from other sources than the configured server URL. If you are accessing the ftrack instance using another domain or IP address, please contact support before upgrading.

When using custom dashboard widgets and triggering the event
ftrack.application.open-actions, some entity types in the event payload have
changed. Entity types with multiple words now have underscored stripped
for consistency with the sidebar.

For example, AssetVersion will now be translated to assetversion instead of
asset_version.

When upgrading to 3.6.0 the character set of the ftrack / database connection will change from latin1 to utf-8. During the 3.6.0 upgrade string characters will be converted to the utf-8 character set. This change should not be noticeable from the ftrack Connect, ftrack or the APIs.

Please make sure to read this before running the upgrade:

The upgrade may take a long time to complete, so make sure to run it in staging environment before upgrading production and plan a sufficient maintenance window. If you are using custom connections to the database you must ensure that those connections are using the utf-8 character set after the migration. If not, data read/written may be corrupted as it is interpreted using the wrong encoding.

Warning:

        Using ftrack's database directly is not supported or advised.