Skip to main content

Migrating from v2 to v3

With the upcoming introduction of Connect 3 we're taking a first big step to allow deeper configuration and extensibility of Connect, integrations and their launch environment.

To reach this goal we have exposed the new Framework extensions capabilities to Connect and moved the Plugin manager, Application launcher and Action launcher widget plugins to be native in Connect.

Detailed list of changes​

  1. Integrated the Application Launcher plugin to be native in Connect, moving from .json to .yaml configuration enabling the ability to override configurations from the FTRACK_CONNECT_EXTENSIONS_PATH.
  2. Moved application launch configuration to each integration, adding support for environment variables in launcher configs.
  3. Integrated the Action Launcher widget to be native in Connect.
  4. Integrated the Plugin manager to be native in Connect, moving from reading plugins from AWS storage to Github releases - integrations repository.
  5. Consolidated the way Connect bootstrap plugins: If FTRACK_CONNECT_PLUGIN_PATH env set, that fully overrides the local plugin directory, together with an overhauled plugin load mechanism. See more details.
  6. Connect now supports new framework based integrations, that depends on ftrack libraries from PyPi and highly customisable with the introduction of the extensions concept.
  7. Each Connect plugin now has a __version__.py file that is used to set the version of the plugin, to support rebuilds on updates to dependencies/libraries.
  8. Changed build system to use Poetry for building Connect and its plugins.
  9. Connect installer/package, widgets and integrations are aligned ftrack products and are now using the new ftrack calendar versioning schemes: YY.mm.patch.

Application launcher​

Besides integrating the application launcher into the native Connect code base, we have changed from a .json format to a .yaml format for application launcher configurations to be consistent with the latest changes to our Integration Framework.

Launcher configurations are now an extension that is part of the integration and are now located within a Connect plugin:

<ftrack-connect-plugin-directory>/
  <integration>/
    launch/
      <integration>-launch.yaml

Another addition is that launch configs now support configuration of custom environment variables, together with defining the extension paths used for new DCC integrations. For more detailed information about launcher configuration, see: application_launch section. Here you will also find information on how to utilize the FTRACK_CONNECT_EXTENSIONS_PATH for customising your launchers.

Convert your launcher configuration​

To convert a .json launcher configuration to the new format, follow these steps:

  1. Use a tool to convert the raw json to yaml, for example: https://www.json2yaml.com/
  2. Add the following to the top of the file:
type: launcher
name: <your name>
priority: 100
note

These lines are needed to make the config part of the new Connect extensions registry, making it possible to override the configuration from the user extensions path.

  1. Save the file within your Connect plugin at the following location:

<ftrack-connect-plugin-directory>/
  my_custom_plugin/
    launch/
      myapplication-launch.yaml

Plugins and the Plugin manager​

The plugin manager now reads plugins from Github releases instead of AWS plugin space. The releases are read from the "integrations" repository:

https://github.com/ftrackhq/integrations.git

note

The plugin manager still supports picking up and reading plugins from a plugin.json pointed out by the environment variable FTRACK_CONNECT_JSON_PLUGINS_URL if set.

Starting with the new ftrack versioning scheme (YY.mm.patch), the plugin manager will now also support the new versioning scheme for Connect plugins.

On installation, Connect will now ask to cleanup/archive old incompatible and legacy plugins.

Plugin bootstrap and FTRACK_CONNECT_PLUGIN_PATH environment variable​

A change in Connect 3 is that FTRACK_CONNECT_PLUGIN_PATH now full overrides the local plugin directory, and resolves conflicts by respecting the order of which plugins are detected. Plugin path can as before be a list, and plugins are loaded in the order they appear in the list, ignoring incompatible plugins and denoting deprecated ones.

To have local plugins be respected the way it was in Connect 2, please prepend the local plugin folder FTRACK_CONNECT_PLUGIN_PATH. Example on Mac:

  $ export FTRACK_CONNECT_PLUGIN_PATH=/Users/myaccount/Library/Application\ Support/ftrack-connect-plugins:/Volumes/nas/connect-plugins

The About dialog in Connect now shows detailed information about the plugins and the plugin path(s) from were they are loaded.

Changes to plugin source code​

Except moving over to Poetry and living in our integrations monorepo, the following changes are to Connect plugin source code:

  1. Connect plugin related data are now situated in the "connect-plugin" directory. This includes the "hook" folder.
  2. Version are now defined in the pyproject.toml file, and not in source _version.py anymore. This version is exported to __version__.py situated in the root of the plugin directory on build.
  3. Connect plugins are now utilizing the same versioning scheme as ftrack products. SCM versioning is only used for integration libraries, that are published to PyPi, and Connect.

Backward compatibility​

Connect can still bootstrap and run all legacy ftrack-* plugins and widgets except these:

  • ftrack-connect-action-launcher-widget
  • ftrack-connect-plugin-manager

If they are still around in the plugin path, they will simply be ignored.

The following plugins need to be upgraded to a version >= 24 to be recognized by Connect:

  • ftrack-connect-publisher-widget
  • ftrack-connect-timetracker-widget

Migrating your plugins​

You do not need to migrate your plugins to the new versioning scheme, Connect will still support the old versioning scheme, only enforcing it for plugins provided by ftrack.

The only step required to fully comply with Connect 3 is to add a __version__.py file to your plugin.

(Optional) Add a requirements.txt to the root of your plugin, providing detailed information (e.g. output from pip freeze) about dependencies and their versions.

Other changes to Connect​

  • Connect resources are now moved into the source folder, fully enabling Connect to be installed as a Python wheel.
  • The About window has been improved, displaying information about incompatible and deprecated plugins, plus detailed information about the built in widgets.
  • If a system tray is not available, Connect still proceeds launch and is fully operational.

Frequently asked questions​

Will my old Connect plugin still work?​

Yes, as long as it adhere the plugin "hook" folder and registers in the standard way as before, but it will show as deprecated if the __version__.py is missing.

Will my old Connect plugin widgets still work?​

Yes, no refactoring has been made to the Connect source code base in that regard.

How do I migrate my plugin to the new versioning scheme?​

You are not required to change your plugin version, the new versioning scheme is only enforced for plugins provided by ftrack. However, to fully comply with Connect 3, you need to add a __version__.py file to your plugin.

Where have all the DCC integrations gone?​

We are re-releasing basic DCC integrations, designed to be extended with custom tools and addons using the new framework subsystem, on Github integrations repository releases.

Will the old integrations work with Connect 3?​

Yes, you can decide to keep the ftrack-application-launcher and ftrack-connect-pipeline-* plugins in your plugin path, and they will still work.

Even the old legacy Connector integrations plugins will still work with Connect 3.

note

If you have multiple integrations for the same DCC, they will appear as duplicate launcher entries in Connect 3.

If I need to roll back and use Connect 2, how do I do that?​

If you did chose to archive the old plugins, you can simply clear out the plugin folder and restore them. They should be located in a folder called ftrack-connect-plugins-ARCHIVED alongside the plugin folder.

We will keep the Connect 2 plugin space online, making it possible to download all plugins again from the AWS plugin space using the legacy ftrack-connect-plugin-manager plugin.

Can Connect 3 and Connect 2 coexist?​

Yes you can install Connect 3 alongside Connect 2, but on Mac and Windows you would need to rename the Connect 2 application folder to prevent a collision. You would also need to have two separate plugin folders, and use the FTRACK_CONNECT_PLUGIN_PATH environment variable to set them apart.

Can Connect 2 load Connect 3 plugins?​

No, Connect 2 is not forward compatible with Connect 3 plugins.

With FTRACK_CONNECT_PLUGIN_PATH, Connect 3 does not respect my locally installed plugins anymore?​

With the new refurbished plugin management in Connect 3, the local plugin directory is not considered if the FTRACK_CONNECT_PLUGIN_PATH environment variable is set. See example above on how to have Connect load plugins from both a custom location and local plugin space.

We are using FTRACK_CONNECT_JSON_PLUGINS_URL to point to our own plugin space, will that still work?​

Yes, if the environment variable is set it will override the Github releases plugin space.

Why does Connect have two versions? Connect release is named both 24 and 3?​

Connect application is a module and is versioned using SCM (v3.x.x), while the Connect installer package is versioned using ftrack calendar versioning (24.x.x).

I read about this new FTRACK_CONNECT_EXTENSIONS_PATH environment variable, what does it do?​

The variable is picked up by Connect (not the DCC integrations) enabling you to add search path(s) for DCC launch configs, enabling a entry point for customising the ftrack DCC integrations.

I want to extend Connect using the new extensions capabilities, how do I do that?​

In short, you need to override the DCC:s launch config adding your own extension path. In there you can deploy your own customisation to framework tools - dialogs, plugins, widgets and configs.

For detailed information on how to customise Connect launch config extensions, follow this Tutorial

For information on how to extend the Framework, head over to Framework.