ftrack connect¶

Welcome to the ftrack connect documentation.

Quick start¶

Follow these steps to get started with Connect. With Connect you can publish/submit files to ftrack and start supported applications with the ftrack integration:

Install ftrack connect package by downloading it from the Integrations webpage.
Launch the ftrack-connect executable. See these instructions if you cannot find it.
Start your favorite application with the ftrack integration. You can find instructions in this article or, publish/submit to ftrack following these instructions.

Articles¶

About¶

ftrack-connect¶

ftrack connect is all about connecting ftrack to other systems and providing tighter integration into your everyday workflows.

It revolves around a service, installed locally onto each individuals machine, that provides enhanced functionality for the web interface including launching applications, notifications, local action processing and multi-site as well as generic interfaces for logging time and publishing any kind of data into ftrack.

ftrack-connect-package¶

ftrack connect package contains that core service and standalone applications. Specific integrations with other applications are named following the convention ftrack-connect-[application] and are available separately. In the not too distant future you will be able to install and configure those separate integrations directly from within both the ftrack web interface and also this core system.

Installing¶

Pre-built packages are available for download for Windows, Linux and Mac from the Integrations webpage.

Note

Alternative installation methods require technical knowledge.

Building from source¶

You can also build manually from the source for more control. First obtain a copy of the source by either downloading the zipball or cloning the public repository:

$ git clone git@bitbucket.org:ftrack/ftrack-connect.git

install the requirements to prepare you environment with:

$ python -m pip install -r requirements.txt

Then you can build and install the package into your current Python site-packages folder:

$ python setup.py install

Alternatively, just build locally and manage yourself:

$ python setup.py build

Is also possible to build live development version using:

$ python setup.py build_ext --inplace

Building from git repository¶

Note

This is an advance method and is not suggested for average users Please refer to the previous way to install as default.

Alternatively, install using pip:

$ pip install git+https://bitbucket.org/ftrack/ftrack-connect.git

Warning

When installing through pip, the default hooks will not be properly installed as part of the package, but they’ll instead be installed on the root of the interpreter eg:

C:\Python37\ftrack_connect_resource\hook

Before starting connect please ensure the path is added to your

FTRACK_EVENT_PLUGIN_PATH

environment variable.

Building documentation from source¶

To build the documentation from source:

$ python setup.py build_sphinx

Then view in your browser:

file:///path/to/ftrack-connect/build/doc/html/index.html

Running tests against the source¶

With a copy of the source it is also possible to run the unit tests:

$ python setup.py test

Dependencies¶

Python >= 3, < 4
PySide >= 2, < 3
Riffle >= 0.1.0, < 2W
Qt.py >= 1.3 < 2

Additional For building¶

pyScss >= 1.2.0, < 2
Sphinx >= 1.8.5, < 4
sphinx_rtd_theme >= 0.1.6, < 1
Lowdown >= 0.1.0, < 1

Additional For testing¶

Pytest >= 2.3.5

Using¶

Find out all the information you need to use ftrack connect day to day.

Launching the service¶

ftrack connect revolves around a core service that runs locally on your machine. Once you have the main package installed, you need to run an instance of the service.

If you are using one of the pre-built packages you can just run the executable provided.

Mac users will have ftrack-connect.app executable in the Applications directory.

Windows users will have the ftrack connect executable as a shortcut on the Desktop and start menu.

Linux users will have the executable in the directory where the .tar file was extracted.

Once the service is launched, the main window will appear and you will also notice an ftrack icon in your task bar.

Windows:

Mac:

The service will then continue to run in the background even if you close all the windows.

To reopen a window or exit the service, use the service context menu.

Alternative launching methods¶

If you are using alternative installation methods, such as building from source or installing through pip, you should open a terminal and execute the following:

python -m ftrack_connect

Note

To see all available launch options (including changing the theme and logging verbosity) use:

python -m ftrack_connect --help

Signing In & Out¶

To use the service, you need a valid ftrack account.

Signing In¶

The first time you launch the service (or after you have logged out previously) you will be prompted to sign in to your ftrack server.

Fill out the fields:

Server url:	The URL to your server that you normally type into a web browser. For example, https://mycompany.ftrackapp.com
Username:	The username you were given to sign into the ftrack web application.
API key:	Your personal API key which you can find on your account page in the main ftrack web application.

Then press Sign In.

Note

Once signed in successfully, you will not have to sign in again, even if you close and reopen the application, unless you sign out explicitly.

Signing Out¶

If you need to sign out explicitly then you can do this from the service context menu by selecting Log Out & Quit.

Publishing¶

Connect provides a simple publisher application to support publishing files directly from your computer without the need to open another application (though publishing from within many applications, including from the ftrack web interface, is also supported).

To publish, ensure you have the interface open by selecting Open from the service context menu and then selecting the Publish tab.

Add components¶

Drag and drop files from your computer onto the publisher (or use the Browse button to browse and select files).

Note

Sequences of files will be automatically detected and added as one entry.

Each file will be added as a component with a name based on the filename of the file. You can manually edit the name if desired by clicking in the name of the component and typing a new name.

_images/publisher_edit_component_name.png

Components can be removed by clicking the Remove icon next to each entry.

Select a linked entity¶

To change the entity that the publish will be linked to, click the Browse button next to the Linked Entity field.

_images/publisher_linked_entity_field.png

A browser, similar to the file browser, will appear, but it allows browsing ftrack rather than the filesystem.

You can navigate through a project structure by double clicking on items in the list. A navigation bar at the top will show you where you are and you can also click an item in the navigation bar to jump back up the hierarchy. Alternatively, use the neighbouring Navigate Up tool button to move up a level at a time.

Note

If an item you expect to see in the list is not appearing, try clicking the Reload tool button to refresh the list from the server.

To select the entity to link against, select an item in the list and then click the Choose button. Alternatively, to cancel making any changes click the Cancel button.

Choose or create asset¶

You can now choose if you like to publish a new version of an previously published asset or if you like to publish the first version of a new asset.

To create a new asset, select Create new and fill in the following options.

Type:	The type of asset to publish. Choose from a list retrieved from the connected ftrack server.
Name:	The name of asset to publish. The name and type must be unique when creating new assets.

To publish a new version of an existing asset, select Version up existing instead. In the list which is shown below the radio buttons, select the asset you wish to use.

Fill out remaining fields¶

Fill out the remaining fields in the publisher.

Web playable:	If you want one of the components to be encoded for playing on the web select it in this field from the list of components added.
Thumbnail:	Drag and drop a small thumbnail of the asset onto this field to give others a better indication of what the asset is before opening.
Description:	A brief description of the published asset or the changes made since the last published version.

Publish¶

When ready, press Publish to start the publish. During this time you will see a progress indicator.

Important

Do not quit the service whilst the publish is in progress.

Once completed, the indicator will change to a notification.

Using integrations and actions¶

The pre-built packages installed from the Integrations webpage contains a set of integrations with different creative applications. These integrations can be launched directly from Connect or the ftrack web interface through the use of Actions.

Connect provides an interface in the standalone application to run your actions. Actions in ftrack provide a standardised way to integrate other tools, either off-the-shelf or custom built, directly into your ftrack workflow.

Using actions you can, for example, launch applications for a task you are working on, generate a custom report or generate your entire filesystem structure for a project with one click.

See also

ftrack:using/actions

Launching actions in Connect¶

To launch an action, select an entity for which to launch the action and press the action in the list below.

Actions are grouped based on their label and a context menu will be shown if multiple variants are available.

_images/using_actions_multiple_variants.png

See also

You can also launch actions from the web interface.

ftrack:using/actions

Limitations¶

Connect will currently only list actions available in the running process and will therefore not include actions running on any remote servers.

Actions in connect does currently not support custom UI. You will see an error message if you try to run an action which returns an UI configuration.

Custom tab widgets¶

It is currently possible to provide connect with custom tabs though connect widget plugins.

This plugins allow to provide custom tabs which can host any custom functionalities, which might be required by productions.

More information on how to write a connect widget plugin are available in development docs

Default plugins¶

By default ftrack connect is shipped with two default plugins.

Launch
Publish

Default Connect widget example

Managing plugins¶

From the top bar menu, widgets can be enabled and disabled. These settings will persists across connect restart.

Connect widget management menu

Installing plugins¶

New plugins can be provided as part of the FTRACK_CONNECT_PLUGIN_PATH path, under a hook folder.

for example

<$FTRACK_CONNECT_PLUGIN_PATH>/my_widget/hook

Note

If you find yourself in need of using third party modules, please see how ftrack plugins are usually packaged. A example is available as part of our recipes repository

Plugin directory¶

ftrack Connect supports extensions through the use of a plugin directory. The directory will be automatically searched for hooks where users can add their own custom event processing, actions and locations.

The path for the default plugin directory differs between platforms:

OS X:	~/Library/Application Support/ftrack-connect-plugins
Windows:	C:\Documents and Settings\<User>\Application Data\Local Settings\ftrack\ftrack-connect-plugins
Linux:	~/.local/share/ftrack-connect-plugins

An easy way of finding your default plugin directory is to open the ftrack connect menu and click Open plugin directory:

_images/open_default_plugin_directory.png

This will create the directory if not already existing and open it in the file browser. Downloaded Connect plugins can be unzipped and placed in this directory.

See also

For development of plugins please refer to this article.

Environment variable¶

Advanced users may want to control where Connect looks for plugins. It may be because you want to centralise hooks on a network share for everyone in the Company or just want to have them somewhere else than default.

By setting the FTRACK_CONNECT_PLUGIN_PATH you can add additional places where plugin hooks are discovered. E.g:

export FTRACK_CONNECT_PLUGIN_PATH=/Users/mattiaslagergren/Desktop/my-plugins

Developing¶

Discover how to extend and modify ftrack connect for a tighter integration and more customisation options.

Hooks¶

Hooks in ftrack connect can be used to extend or modify the default behaviour of the application. They build upon the event system used in ftrack. As such, each hook receives a single argument which is an instance of ftrack_api.event.base.Event.

The built-in hooks can be overridden by creating new hooks and placing them in a directory. Then configure the environment by setting the FTRACK_EVENT_PLUGIN_PATH environment variable.

It is also possible to prevent a default hook from being triggered by calling event.stop in a callback with higher priority or by removing the default hook using ftrack.Session.event_hub.unsubscribe

Note

Unlike regular events, hooks will typically be run synchronously on the system running the ftrack connect application.

ftrack.connect.publish.make-web-reviewable¶

The make-web-reviewable hook is triggered when publishing a new version. The default hook will upload the selected component to cloud storage and encode it to appropriate formats(mp4 and webm).

Example event passed to hook:

Event(
    topic='ftrack.connect.publish.make-web-playable',
    data=dict(
        versionId='eb16970c-5fc6-11e2-bb9a-f23c91df25eb',
        path='/path/to/file/to/use/for/component.mp4'
    )
)

Default hook¶

# :coding: utf-8
# :copyright: Copyright (c) 2014 ftrack


import functools
import os.path
import logging

import ftrack_api.session

logger = logging.getLogger('ftrack.connect.publish.make-web-playable')


def callback(event, session):
    '''Default make-web-playable hook.

    The hook callback accepts an *event*.

    event['data'] should contain:

        * versionId - The id of the version to make reviewable.
        * path - The path to the file to use as the component.

    Will raise :py:exc:`ValueError` if the provided path is not an accessible
    file and :py:exc:`ftrack.FTrackError` if cloud storage is full or not
    enabled.

    '''
    versionId = event['data']['versionId']
    path = event['data']['path']

    version = session.get('AssetVersion', versionId)

    # Validate that the path is an accessible file.
    if not os.path.isfile(path):
        raise ValueError(
            '"{0}" is not a valid filepath.'.format(path)
        )

    # version.encode_media uploads file to cloud storage and triggers
    # encoding of the file to appropirate formats(mp4 and webm).
    version.encode_media(path)
    session.commit()
    logger.info('make-reviewable hook completed.')


def subscribe(session):
    '''Subscribe to events.'''
    topic = 'ftrack.connect.publish.make-web-playable'
    logger.info('Subscribing to event topic: {0!r}'.format(topic))
    session.event_hub.subscribe(
        u'topic="{0}" and source.user.username="{1}"'.format(
            topic, session.api_user
        ),
        functools.partial(callback, session=session)
    )


def register(session, **kw):
    '''Register plugin. Called when used as an plugin.'''
    # 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.Session):
        logger.debug(
            'Not subscribing plugin as passed argument {0!r} is not an '
            'ftrack_api.Session instance.'.format(session)
        )
        return

    subscribe(session)
    logger.debug('Plugin registered')

ftrack.action.launch¶

The action.launch hook is triggered from the ftrack interface when a user selects an action in the Actions menu. For more information about launching actions from the web UI, see ftrack:using/actions.

The list of actions is provided by the ftrack.action.discover hook. The action.discover hook provides a list of actions. All parameters from these actions are passed to this hook and can be used when launching the action.

The default hook is a placeholder and should be extended to include correct action commands.

Example event passed to hook:

Event(
    topic='ftrack.action.launch',
    data=dict(
        actionIdentifier='ftrack-connect-launch-applications-action',
        applicationIdentifier='maya-2014',
        foo='bar',
        selection=[
            dict(
                entityId='eb16970c-5fc6-11e2-bb9a-f23c91df25eb',
                entityType='task'
            )
        ]
    )
)

Expects reply data in the form:

dict(
    success=True,
    message='maya-2014 launched successfully.'
)

ftrack.action.discover¶

The action.discover hook is triggered from the ftrack interface to request a list of available actions for launching. For more information, see ftrack:using/actions.

The default hook is a placeholder and should be extended to include a complete list of actions that can be launched.

Example event passed to hook:

Event(
    topic='ftrack.action.discover',
    data=dict(
        selection=[
            dict(
                entityId='eb16970c-5fc6-11e2-bb9a-f23c91df25eb',
                entityType='task',
            )
        ]
    )
)

Expects reply data in the form:

dict(
    items=[
        dict(
            label='Mega Modeling',
            variant='2014',
            actionIdentifier='ftrack-connect-launch-applications-action',
            icon='URL to custom icon or predefined name',
            applicationIdentifier='mega_modeling_2014'
        ),
        dict(
            label='Professional Painter',
            icon='URL to custom icon or predefined name',
            actionIdentifier='ftrack-connect-launch-applications-action',
            applicationIdentifier='professional_painter'
        ),
        dict(
            label='Cool Compositor',
            variant='v2',
            actionIdentifier='ftrack-connect-launch-applications-action'
            icon='URL to custom icon or predefined name',
            applicationIdentifier='cc_v2',
            cc_plugins=['foo', 'bar']
        )
    ]
)

The response should be a dictionary with an items list. The list should contain a dictionary for each menu item to be returned.

Action¶

To add an action, add an item in the following format.

dict(
    label='Crazy Compositor',
    actionIdentifier='ftrack-connect-launch-applications-action',
    variant='v2',
    description='Launch Crazy Compositor',
    icon='URL to custom icon or predefined name',
    cc_plugins=['foo', 'bar'],
    applicationIdentifier='cc_v2'
)

The different options are:

label

Used to display the action in the ftrack interface.

actionIdentifier

Used to target a specific callback for an action.

variant

A variant of the action, such as application version.

description

A helpful description for the user.

icon

Icon to display in the ftrack interface. Can be either an URL to a custom icon or the name of a predefined icon. Predefined icons are hiero, hieroplayer, nuke, nukex, maya, premiere and default

In addition, you can add any extra data you want to include in the event. The data returned will be passed on to the ftrack.action.launch hook.

In the default hook each item contains an applicationIdentifier which is used to uniquely identify which application to start.

ftrack.connect.plugin.debug-information¶

The ftrack.connect.plugin.debug-information hook is triggered when the About window in ftrack connect is opened.

It can be used to return information about loaded plugins in ftrack connect. Such as actions.

Example event passed to hook:

Event(
    topic='ftrack.connect.plugin.debug-information'
)

Expects return data in the form:

[
    dict(
        name='ftrack connect nuke',
        version='0.1.2'
    ),
    dict(
        name='PDF Export',
        version='0.1.2',
        debug_information=dict(
            api_key='de305d54-75b4-431b-adb2-eb6b9e546014'
        )
    ),
    dict(
        name='ftrack connect package',
        version='0.2.4',
        core=True
    )
]

The response should be a single dictionary or a list of dictionaries and the example response above would be displayed in the About window like this:

Each dictionary should contain the keys:

name: Name of the plugin which will be displayed in the About window.
version: Version of the plugin which will be displayed in the About window.
core: Optional key will place the plugin under the core features instead of in plugins list.
debug_information: Optional dictionary containing key/value attributes which will be displayed in the debug information section.

ftrack.connect.application.launch¶

The ftrack.connect.application.launch synchronous event is triggered when an application is launched using the ftrack_connect.application.ApplicationLauncher.

It can be used to modify the environment and arguments used when launching applications using subprocess.Popen().

Example event passed to hook:

Event(
    topic='ftrack.connect.application.launch',
    data=launch_data
)

The passed data variable, launch_data is a dictionary containing:

command: The first arugment passed to subprocess.Popen, containing a list of the command should run.
options: A dictionary with keyword arguments passed to subprocess.Popen.
application: A dictionary containing information about the application that is being launched.
context: The ftrack entity context that the application is being launched for.

Modifications to the launch_data dictionary, either by replacing the content or modifying it directly, will be picked up and used by the application launcher.

ftrack.connect.verify-startup¶

The ftrack.connect.verify-startup hook is triggered when ftrack connect is started and any plugins have been loaded.

The hook can be used to inform the users about problems that could arise with the way ftrack connect is currently configured.

Example event passed to hook:

Event(
    topic='ftrack.connect.verify-startup'
)

Expects return data in the form:

'Message about something that may not work as expected'

The response should either be None or a string where a string will be assumed to be a message that should be shown to the user as a warning.

Note

This event is only published through the event hub of the new ftrack python API.

ftrack.connect.plugin.connect-widget¶

The ftrack.connect.plugin.connect-widget hook is triggered when ftrack connect starts up and is used to register custom widgets for connect.

The hook can be used to inform the users about problems that could arise with the way ftrack connect is currently configured.

Example event passed to hook:

Event(
    topic='ftrack.connect.plugin.connect-widget'
)

Expects return data in the form of a QtWidget.

Note

Connect widget will be able to use the widgets provided as part of ftrack-connect.

An example is provided as part of the resources:

# :coding: utf-8
# :copyright: Copyright (c) 2014 ftrack
import ftrack_api
import logging
from Qt import QtWidgets, QtCore

import ftrack_connect.ui.application

logger = logging.getLogger('ftrack_connect.plugin.actions')


class ExamplePlugin(ftrack_connect.ui.application.ConnectWidget):
    '''Base widget for ftrack connect actions plugin.'''
    icon = ':ftrack/image/default/ftrackLogoColor'

    def __init__(self, session, parent=None):
        '''Instantiate the actions widget.'''
        super(ExamplePlugin, self).__init__(session, parent=parent)
        layout = QtWidgets.QVBoxLayout()
        self.setLayout(layout)

        text = QtWidgets.QLabel('This is a test plugin!')
        layout.addWidget(text)


def register(session, **kw):
    '''Register plugin. Called when used as an plugin.'''
    # 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.Session):
        logger.debug(
            'Not subscribing plugin as passed argument {0!r} is not an '
            'ftrack_api.Session instance.'.format(session)
        )
        return

    # #  Uncomment to register plugin
    # plugin = ftrack_connect.ui.application.ConnectWidgetPlugin(ExamplePlugin)
    # plugin.register(session, priority=10)

Tutorial¶

Learn how to extend and modify ftrack connect for a tighter integration and more customisation options.

Adding a location plugin¶

This tutorial assumes basic knowledge of the Location plugins system in ftrack and will focus on how to make Location plugins available for Connect and integrated applications.

Making Connect aware of your location plugin¶

Using the plugin directory we can register a location plugin to be available in Connect. Let us now implement a basic Location plugin

import ftrack_api

def configure_locations(event):
    session = event['data']['session']

    location = session.ensure(
        'Location', {
            'name': 'studio.location'
        }
    )

    location.priority = 0
    location.structure = ftrack_api.structure.standard.StandardStructure()

    location.accessor = ftrack_api.accessor.disk.DiskAccessor(
        prefix=prefix='<path-to-directory-where-files-should-go>'
    )

def register(session, **kw):

    # Validate that session is an instance of ftrack_api.Session. If not,
    # assume that register is being called from an incompatible API
    # and return without doing anything.
    if not isinstance(session, ftrack_api.Session):
        # Exit to avoid registering this plugin again.
        return

    session.event_hub.subscribe(
        'topic=ftrack.api.session.configure-location',
        configure_locations
    )

If we add our new location plugin, custom_location_plugin.py, to the plugin directory it will be automatically registered and available in Connect:

<ftrack-connect-plugin-directory>/
    my_location_plugin/
        hook/
            location/
                custom_location_plugin.py

API Reference¶

ftrack_connect¶

ftrack_connect.asynchronous¶

ftrack_connect.error¶

ftrack_connect.event_hub_thread¶

ftrack_connect.worker¶

ftrack_connect.ui¶

ftrack_connect.ui.application¶

ftrack_connect.ui.resource¶

Resource module that loads into PySide various resources including images and stylesheets.

ftrack_connect.ui.theme¶

ftrack_connect.ui.model¶

ftrack_connect.ui.model.entity_tree¶

ftrack_connect.ui.widget¶

ftrack_connect.ui.widget.asset_type_selector¶

ftrack_connect.ui.widget.component¶

ftrack_connect.ui.widget.components_list¶

ftrack_connect.ui.widget.data_drop_zone¶

ftrack_connect.ui.widget.entity_browser¶

ftrack_connect.ui.widget.entity_path¶

ftrack_connect.ui.widget.indicator¶

ftrack_connect.ui.widget.item_list¶

ftrack_connect.ui.widget.item_selector¶

ftrack_connect.ui.widget.label¶

ftrack_connect.ui.widget.line_edit¶

ftrack_connect.ui.widget.list¶

ftrack_connect.ui.widget.overlay¶

ftrack_connect.ui.widget.thumbnail_drop_zone¶

ftrack_connect.ui.widget.uncaught_error¶

Plugins¶

By placing plugin hooks in a discoverable plugin directory Connect will automatically register them. A plugin hook can be used for custom event processing, actions and location plugins.

In this article we will learn about the structure of a plugin and some best practices that will help you on your way to become an ftrack Connect ninja.

Structure¶

A plugin’s structure is easy to grasp and relies on a simple directory structure. The plugin itself is made up of a directory, my_custom_plugin, and inside that a hook directory:

<ftrack-connect-plugin-directory>/
    my_custom_plugin/
        hook/
            my_action.py

When Connect starts it will go over the hook directories in the plugin directory and call register on each of the python scripts in the hook directory. The my_action.py may look something like this:

import ftrack_api

...

def register(session, **kw):
    '''Register plugin.'''

    # Validate that session is an instance of ftrack_api.Session. If not,
    # assume that register is being called from an incompatible API
    # and return without doing anything.
    if not isinstance(session, ftrack_api.Session):
        # Exit to avoid registering this plugin again.
        return

    # Register plugin event listener.
    ...

This example is using the ftrack-python-api but the concept is valid for the legacy api as well.

Separating resources¶

Although possible we recommend keeping the hook directory as clean as possible and have any shared modules or other data in a separate directory. This is not something you have to do but it will make things easier down the line.

Now let’s say that you have a few different actions that share the same modules. You want to keep things DRY and therefore place them in a resource directory, resource:

<ftrack-connect-plugin-directory>/
    my_custom_plugin/
        hook/
            my_action.py
            another_action.py
        resource/
            my_module/
                __init__.py

To access the module in the resource/ folder we need to do some manual work to allow us to import it. In my_action.py we will add it to the `sys.path:

import os
import sys

RESOURCE_DIRECTORY = os.path.abspath(
    os.path.join(os.path.dirname(__file__), '..', 'resource', 'my_module')
)

if RESOURCE_DIRECTORY not in sys.path:
    sys.path.append(RESOURCE_DIRECTORY)

import my_module

# Define register and rest of action.
...

Separating locations and actions¶

We’ve now learned how to add our own actions in Connect and how to share code between them. Another type of plugin that we may want to use is a location plugin. Registering it is easy since we only have to put it into our hook directory.

A location plugin you will typically want to have accessible inside an integration as well. This can be done by adding the path to the environment when an application is launched, see ftrack.connect.application.launch.

But if we just add it to the hook directory and add the hook directory to the environment, other Actions may be registered from inside the integration. This could lead to situations where the My action action is registered twice, one from Connect and one from the integration you’ve started.

To solve this we recommend separating actions and locations into separate sub-directories:

<ftrack-connect-plugin-directory>/
    my_custom_plugin/
        hook/
            action/
                my_action.py
                another_action.py
            location/
                custom_location_plugin.py
        resource/
            my_module/
                __init__.py

When Connect starts it will traverse the directory structure in the hook directory and register each plugin. This separation will allow us to only add the <ftrack-connect-plugin-directory>/my_custom_plugin/hook/location/ directory when launching our integrations.

See also

Location plugin example to learn how to use it with application launch hook.

Frequently asked questions¶

Where can I see information about my ftrack connect¶

To see information like logged in user, version of ftrack connect or connected ftrack server click the service context menu and choose About. This will bring up a dialog containing information about the currently running instance of ftrack connect.

Glossary¶

API: Application programming interface.
default plugin directory: The default plugin directory where plugin hooks can be placed. See Plugin directory for usage.
ftrack: Cloud based Creative Project management tool for Production Tracking, Asset Management and Team Collaboration.

See also

www.ftrack.com
hook: Used to extend or modify the default behaviour in ftrack connect. See Hooks for more information.
Houdini: Houdini is a 3D animation application software developed by Side Effects Software. Visit the website at http://www.sidefx.com/
JSON: (JavaScript Object Notation), a lightweight data-interchange format. Visit the website at http://www.json.org/
location plugin: A custom developed location to represent a storage. Used by the API to manage files and data.
mp4: MPEG-4 Part 14 or MP4 is a digital multimedia format most commonly used to store video and audio, but can also be used to store other data such as subtitles and still images. It’s being developed by International Organization for Standardization (ISO). Visit the website at http://www.iso.org/
plugin directory: A directory that Connect searches for plugin hooks. See Plugin directory for usage.
python: A programming language that lets you work more quickly and integrate your systems more effectively. Often used in creative industries. Visit the language website at http://www.python.org
service context menu: The service provides a context menu for performing basic actions. It is accessible by clicking on the service icon.
webm: WebM is a video file format intended primarily for royalty-free use in the HTML5 video tag. Visit the website at http://www.webmproject.org/

Release and migration notes¶

Find out information about what has changed between versions and any important migration notes to be aware of when switching to a new version.

Release Notes¶

Upcoming¶

5 July 2021

new:

UiProvide ability to extend connect through ConnectWidgets plugins.
changed

UiMove to Pyside2.
changed

APIRemove ftrack-python-legacy-api dependency and dependent code.

Warning

Hooks using ftrack.EVENT_HANDLERS won’t be discovered anymore.
new

UiReplace QtExt with Qt.py module.
changed

changedMove connector integration codebase to separate repository.
new

SetupUse setuptool_scm to infer version.
fixed

Application launcherStandalone installation does not correctly inject dependencies at application startup.

1.1.9¶

11 March 2021

fixed

open_directoryOpening component breaks on cloud paths.

1.1.8¶

21 January 2020

new

InternalAdded a lockfile mechanism so Connect will exit if another instance is already running. Users can pass a command-line flag, -a or –allow-multiple, to skip this check.

1.1.7¶

8 March 2019

new

UiAdded button in About dialog to create a Linux desktop entry file to make Connect appear in the applications menu.

1.1.6¶

8 October 2018

changed

UiUpdate icons and style.
fixed

Internalutil.open_directory fails on Windows when path includes spaces.

1.1.5¶

13 September 2018

fixed

Logginglogger breaks with non ascii path.
changed

LoggingImprove logging configuration.
fixed

UiApplication versions are not correctly sorted.

1.1.4¶

27 April 2018

fixed

Import assetImport Asset breaks checking for asset in remote locations.
changed

CrewRemove Crew widget chat and notifications.
changed

UiAdded feature to hide the ftrack-connect UI on startup. This is done with the flag “–silent” or “-s”.

1.1.3¶

2 February 2018

fixed

Plugins

ftrack.connect.plugin.debug-information only published for the legacy api.

1.1.2¶

1 December 2017

fixed

DocumentationRelease notes page is not formatted correct.

1.1.1¶

16 November 2017

fixed

APIError when publishing in connect with non-task context.

1.1.0¶

12 September 2017

changed

Import assetComponent location picker now defaults to location where the component exists. If a component exists in more than one location, the priority order determines the default location.
fixed

Info dialogTasks dialogInfo and Tasks dialogs are not compatible with recent versions of Qt.
fixed

APIAll widgets are not compatible with recent versions of Qt.

1.0.1¶

11 July 2017

fixed

Asset managerCannot change version of versions with a sequence component.

1.0.0¶

7 July 2017

fixed

APIErrors in hooks are shown as event hub errors.
fixed

Asset managerUiAsset manager fails to open in some rare cases.
fixed

APIApplication search on disk does not follow symlinks.
changed

APIEventsThe ftrack.connect.application.launch event is now also emitted through the new api. The event allows you to modify the command and/or environment of applications before they are launched.
changed

APIChanged Connector based plugins to use the new API to publish assets.
fixed

Import assetUiImport asset dialog errors when a version has no user.
changed

APIChanged from using legacy API locations to using locations from the ftrack-python-api. Make sure to read the migration notes before upgrading:
fixed

InternalFixed occasional X11 related crashes when launching actions on Linux.
changed

PublishThe new api and locations are used for publishing.
changed

InternalX11 windows system is not thread safe.
changed

Asset managerInternalUiUpdate color on version indicator in asset manager.
fixed

SettingsNumberic settings cannot be set to higher than 99.

0.1.33¶

17 January 2017

fixed

DocumentationInstallation and usage instructions are confusing for users who have downloaded the pre-built package.

0.1.32¶

1 December 2016

fixed

APISwitched to require ftrack-python-api > 1.0.0.

0.1.31¶

1 December 2016

fixed

WidgetEntity picker may cause instability on some combinations of platforms and applications.
new

Asset version scannerAdded new method to scan for new asset versions.

0.1.30¶

23 September 2016

fixed

Asset managerAsset manager fails to switch versions if an asset is removed without refreshing the list.

0.1.29¶

21 September 2016

fixed

InternalWrapper for PySide2 and Qt5 does not work properly on Windows.

0.1.28¶

16 September 2016

changed

InternalAdd wrapper for PySide2 / Qt5 to support Maya 2017 and other future applications that rely on later versions of Qt.
fixed

APIInternalConnect break in case of slow connection or missing url icon.
changed

InternalSpeedup asset manager.
fixed

InternalConnect logs are saved to the wrong directory.

0.1.27¶

8 August 2016

new

ActionsAdded default action to reveal a Component in the OS default file browser.

0.1.26¶

19 July 2016

new

InternalLogs are now written to file and the logs directory can be accessed via the about menu.

0.1.25¶

7 June 2016

changed

InternalImprove support for debugging tools.
fixed

Asset managerAsset versioning change breaks if versions has been deleted.

0.1.24¶

7 June 2016

fixed

LoginError when starting connect with invalid ftrack server URL.

0.1.23¶

6 May 2016

fixed

APIEventsThe ftrack.connect.publish-components event listener does not work correctly when using Windows.

0.1.22¶

2 May 2016

new

APIEventsAdded new ftrack.connect.publish-components event listener which can be used to publish components from applications not supporting the locations framework.
changed

LoginLogin details and credentials are now stored in a json file in the platform specific user data folder instead of using QSettings.
fixed

LoginUnable to logout on some platforms.

0.1.21¶

30 March 2016

fixed

APIEventsEvent listeners using new API may be registered twice.

0.1.20¶

14 March 2016

new

PluginsAdded a menu option to open the default plugin directory.
changed

LoginImproved error handling for invalid server URLs.
new

LoginAdded ability to login using regular users credentials via web interface instead of API key. Username and API key fields are therefore hidden by default in the ftrack connect login screen.
new

Eventsftrack connect will now respond to the ftrack.connect.discover event which can be used to identify if ftrack connect is running for the current user.
new

LocationPaths for custom locations that are implemented in the new Python API, ftrack-python-api, are now resolved in Connect.
new

Location ScenarioAdded a new hook that can be used to detect problems and present information to the user.

See also

Verify startup hook
new

Location ScenarioAdded a configure storage scenario widget that will be shown on startup if a storage scenario has not been configured on the server.
changed

Event pluginsEvent plugins are now loaded for the new Python API, ftrack-python-api. Read more
fixed

UiRestore ftrack_connect.panelcom.PanelComInstance communication with contextSelector, so changes to the environments get reflected into the widgets.

0.1.19¶

8 January 2016

new

Context SelectorAdded new ftrack_connect.ui.widget.context_selector.ContextSelector widget that can be used to present and browse for a context.
changed

Removed BrowseTasksSmallWidget in favor of ftrack_connect.ui.widget.context_selector.ContextSelector.

0.1.18¶

10 November 2015

new

Added new ftrack_connect.ui.widget.html_combobox.HtmlComboBox widget and ftrack_connect.ui.widget.html_delegate.HtmlDelegate.

0.1.17¶

16 October 2015

fixed

ActionsThe option launch with latest is not respected when launching Adobe applications.
fixed

ActionsDeveloperWhen launching actions via connect, not all action data are passed when firing the launch event.

0.1.16¶

2 October 2015

new

Display more detailed information about ftrack connect in About window.

See also

Add custom information to About window

0.1.15¶

22 September 2015

changed

Entity BrowserAdded support for new workflow object icons in entity browser.
fixed

CrewHumanized notification dates are not always correct.
fixed

PublisherClean up after a failed publish fails if not permitted to delete version.

0.1.14¶

8 September 2015

new

ActionsAdded support for launching actions from Connect.

See also

Using integrations and actions
new

CrewAdded crew widgets for chat and notifications.
changed

ActionsApplications may now include description and variant.
changed

Developerthumbnail.Base will no longer default to ellipsis shape. Use thumbnail.EllipsisBase for round thumbnails.

0.1.13¶

31 August 2015

changed

PublisherUpdate entity browser to support updated naming convention.

0.1.12¶

24 August 2015

new

PublisherSupport custom object types and icons in entity browser.

0.1.11¶

5 June 2015

changed

PublisherFile browser now defaults to home directory.
fixed

PublisherFile browser crashes if file is removed or renamed.
fixed

PublisherFile browser not being refreshed if closed and reopened.

0.1.10¶

6 May 2015

fixed

PublisherCan not add files via drag and drop with non-ascii characters in the path.

0.1.9¶

18 March 2015

new

DeveloperAdded base widgets and connectors to be used by application plugins.

0.1.8¶

2 March 2015

fixed

PublisherPublisher browser breaks when objects and files have non-ascii characters.
new

DeveloperTutorialAdded tutorial on how to add you own custom applications and how to modify the environment.
changed

PublisherAdded the possibility to specify if you like to version up an existing version or create a new version when publishing. Read more

0.1.7¶

3 February 2015

fixed

PublisherPublisher is stuck in processing state if publish fails.

0.1.6¶

30 January 2015

change

DeveloperMoved logic for finding and starting applications supported by legacy plugins from the ftrack connect core to the legacy plugins repository.
fixed

Unable to launch NukeX on Windows.
fixed

Wrong Nuke version is launched on Windows if several are installed.
fixed

Hiero and HieroPlayer are not discovered on Windows.

0.1.5¶

26 January 2015

change

Include all environment variables when launching applications.

0.1.4¶

23 January 2015

new

Added About option to menu to display eg. version, logged in user and ftrack server url.
change

Use a managed location when publishing from adobe extensions to prevent publishing temporary files.

0.1.3¶

14 January 2015

change

Update default action_discover and action_launch hooks to support new format in ftrack 3.0.3. Read more
new

Support launching applications with legacy ftrack plugins enabled.
fixed

Fix import error causing Nuke to not launch correctly via Connect.

0.1.2¶

17 December 2014

Release to match version for package. No changes introduced.

0.1.1¶

2 December 2014

new

Support publishing independently of applications.
new

Provide default actions for discovering and launching locally installed applications.

Migration notes¶

Migrate from 1.X to 2.0¶

Users of a downloaded Connect package are recommended to test the new version before upgrading all workstations. Especially if you have custom code implemented with the legacy api.

Developer notes¶

With version 2.0, ftrack-connect drops support for ftrack-python-legacy-api, and will stop including backward compatibility modules such as:

ftrack-location-compatibility

Legacy locations will have to update to ftrack-python-api syntax in order to keep them working.

Modules and interpreter changes¶

With the move to connect2 some of the basic modules and systems have been updated or changed to match the current VFX platform.:

Python: 2.7 –> 3.7
PySide: 1.1.3 –> 1.3.x
Qt: 4.8 –> 5.14.X
QtExt: 0.2.2 -> Qt.py 1.3.3
ftrack-python-api: 1.8.X -> 2.X

Launching applications¶

The application launch logic has now been moved to the ftrack-application-launcher

Warning

Is likely your application launcher or hooks could have import references to: ftrack_connect.application This should be replaced with: ftrack_application_launcher.application

For other changes regarding the launch of applications please refer to the ftrack-application-launcher documentation.

hooks¶

Updating hooks mostly means updating the registration function from:

def register(registry, **kw):
    if registry is not ftrack.EVENT_HANDLERS:
        return

to:

def register(api_object, **kw):
    if registry is not isinstance(api_object, ftrack.Session):
        return

or will not be discovered anymore.

connector¶

Due to the changes of python interpreter and pyside version, we also dropping the support for connector integration from within connect itself.

To allow backward compatiblity , the codebase has been moved into a separate repository And will have to be included as dependency in the integration that requires connector to be present.

Note

Any reference to ftrack_connect.connector should be replaced with ftrack_connector_legacy.connector

Eg, from

from ftrack_connect.connector import (
    FTAssetHandlerInstance,
    HelpFunctions,
    FTAssetType,
    FTComponent
)

To

from ftrack_connector_legacy.connector import (
    FTAssetHandlerInstance,
    HelpFunctions,
    FTAssetType,
    FTComponent
)

Migrate from 0.1.19 to 0.1.20¶

Developer notes¶

The ftrack-python-api will from now discover plugins that are added to the FTRACK_EVENT_PLUGIN_PATH.

This means that register functions will be called several times, both for the ftrack-python-api and the legacy api. To avoid registering a hook multiple times, developers should validate the register functions arguments.

For event listeners like actions or event processing scripts we do:

import ftrack

...

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

    # Validate that registry is the correct ftrack.Registry. If not,
    # assume that register is being called with another purpose or from a
    # new or incompatible API and return without doing anything.
    if registry is not ftrack.EVENT_HANDLERS:
        # Exit to avoid registering this plugin again.
        return

    # Register plugin event listener.
    ...

And for location plugins we verify that the registry is a ftrack.LOCATION_PLUGINS:

import ftrack

...

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

    # Validate that registry is the correct ftrack.Registry. If not,
    # assume that register is being called with another purpose or from a
    # new or incompatible API and return without doing anything.
    if registry is not ftrack.LOCATION_PLUGINS:
        # Exit to avoid registering this plugin again.
        return

    # Register location plugin.
    ...

Plugins for the new Python API must validate that they are called with an ftrack_api.session.Session as a first argument:

import ftrack_api

...

def register(session, **kw):
    '''Register plugin.'''

    # Validate that session is an instance of ftrack_api.Session. If not,
    # assume that register is being called from an incompatible API
    # and return without doing anything.
    if not isinstance(session, ftrack_api.Session):
        # Exit to avoid registering this plugin again.
        return

    # Register plugin event listener.
    ...

Migrate from 0.1.2 to 0.1.3¶

Developer notes¶

Updated action hooks¶

The default discover and launch action hooks has been updated to support the updated action format in ftrack 3.0.3. If you have created custom hooks, please make sure they are updated accordingly. In the updated format of the event data selection and the contents of actionData has been moved to the root, event['data'], level.