Skip to main content

Migrating Framework from v1 to v2

The legacy Framework v1 has been deprecated and replaced by the new Framework v2. This document will guide you through the process of migrating your customisations from the legacy Framework to the new Framework v2.

To be able to customise the new Framework, you will need to write extensions. Extensions are a way to augment the functionality of the Framework. They are designed to be highly extensible and customisable, and are meant for the user to align the Framework to cover its specific needs. Extensions are also thought to be shareable.

For more information: Framework Extensions

Setting up custom extensions​

To be able to port your customisations to the new Framework, you will need to setup folder either locally or on your network storage, where extensions will be stored.

To have Connect 3 and the new Framework to pick up your custom extensions, you will need to set the environment variable FTRACK_CONNECT_EXTENSIONS_PATH to point to the folder where your extensions are stored:

  export FTRACK_CONNECT_EXTENSIONS_PATH=/path/to/your/extensions

In this guide we will assume you are porting a customised Nuke integration, but the same principles apply to other DCC integrations.

Name resolving​

Extensions are resolved by their type and name. By keeping the name of the extension the same, you can ensure that the new Framework will pick up your customisations.

For example, if you want to customise the Nuke script exporter, but do not want to provide a custom tool config, preserve the name nuke_script_exporter to have it picked up in favour of the shipped default script exporter plugin.

ftrack-application-launcher​

Has been deprecated and built into Connect, moving from JSON configuration to YAML launch configuration provided with each Connect plugin(integration)

For more information: Application Launcher

Migrating config​

If you have a custom launcher config JSON file, you will need to migrate it to the new YAML format and then store it on the user extension path:

  FTRACK_CONNECT_EXTENSIONS_PATH/
    nuke/
      launch/
        nuke-launch.yaml

Migrating code​

If you have customised the application launcher plugin code base, you will need to fork the ftrack integrations repository and migrate the changes to the new code base:

  integrations/
    apps/
      connect/
        source/
          ftrack_connect/
            application_launcher/
              ..

ftrack-connect-pipeline​

The Framework core plugin has been replaced by the framework-core library (ftrack_framework_core module) in the new Framework, with constants put to the constants library (ftrack_constants module) and utils to utils library (ftrack_utils module).

With the new Framework comes the concept of tools, and it has been designed to make it very easy to add a new tool to the DCC menu - with a minimal effort implementation and deploy using the new tool-config extension.

The engine has at same time been simplified supporting something called the store. Together with making plugins much simpler, just operating on the store, enables tools and engines to be much more flexible and easier to customise. For more information, please have a look at the plugin and engines within the source code of the new Framework:

  integrations/
    libs/
      ftrack_framework_core/
        source/
          ftrack_framework_core/
            engine/
              ..
            plugin/
              ..

We will not cover any customisations to the Framework core plugin in this guide, but in general you would need to fork off integrations repository and migrate the changes to the new code base.

ftrack-connect-pipeline-qt​

The legacy framework had no layered separation between QT specific components and the core framework. To achieve this, the plugin has been split up in separate libraries and extensions with the new Framework:

  • qt library (ftrack_qt module); QT general components, not related to the framework. To be used as building blocks for any custom UI components.
  • qt-style library (ftrack_qt_style module); The ftrack style, from the resource/style package, built for QT.
  • framework-qt library (ftrack_framework_qt module); Framework specific QT components - bases for dialog and widgets.
  • Dialogs common extension (projects/framework-common-extensions/dialogs); Dialogs for the framework, such as the Publisher and Opener dialogs.
  • Widgets common extension (projects/framework-common-extensions/widgets); Widgets for the framework, such as the publisher asset version selector.
  • Nuke widgets extension (projects/framework-nuke/extensions/widgets); Contains the Nuke DCC specific widgets.

The legacy qt plugin also had a widget factory that was intended to provide some means of customisation, this has been deprecated and replaced by the new extensions.

If you have made deeper customisations to ftrack-connect-pipeline-qt you will need to fork of the integrations repository and migrate the changes to the new code base.

To create custom dialogs and/or widgets, that previously were driven by the QT factory, create extensions as needed:

  FTRACK_CONNECT_EXTENSIONS_PATH/
    dialogs/
       custom_publisher_dialog.py
    widgets/
       custom_asset_version_selector.py

ftrack-connect-pipeline-definitions​

The legacy framework had a definitions plugin that was used to configure for example a publisher, telling the UI and the engine how to collect context, which components to operate upon and so on.

In the 2022 build of the Framework, the definitions were moved to the DCC plugin (see below), and the plugin was deprecated.

This has been replaced by the concept of tools and their corresponding tool config files and plugins:

  • plugins extension (projects/framework-common-extensions/plugins); The core/shared plugins.
  • Nuke plugins extension (projects/framework-nuke/extensions/plugins); Contains the Nuke DCC specific plugins.
  • tool-configs extension (projects/framework-common-extensions/tool-configs); The core tool-configs extension, contains the standalone file publisher and opener tool configs.
  • Nuke tool configs extension (projects/framework-nuke/extensions/tool-configs); Contains the Nuke DCC specific tool configs.

To create a tool config from your JSON definition, you will need to analyse and compare the existing YAML tool configs, converting your custom definitions accordingly:

  FTRACK_CONNECT_EXTENSIONS_PATH/
    nuke/
      tool-configs/
        custom-nuke-publisher.yaml

If you have any custom plugins, you will need to analyse and compare the existing plugins, converting them to the new code base:

  integrations/
    apps/
      connect/
        source/
          ftrack_connect/
            plugins/
              custom_nuke_script_exporter.py

ftrack-connect-pipeline-nuke (|maya | houdini | unreal | ...)​

This was the DCC specific plugin that was used to bootstrap the Framework within the DCC, provide tool menu items and setup the DCC timeline and similar.

This has been renamed to framework-nuke (projects/framework-nuke folder).

Bootstrap​

The bootstrap has been minimised in Framework v2 and moved to the source code of the DCC plugin:

  integrations/
    projects/
      framework-nuke/
        source/
          ftrack_nuke/
            __init__.py

Here you will find all the logic that was previously located in the resource/bootstrap folder.

Definitions​

In the 2022 build of Framework, definitions were moved to the resource/definitions folder and has now been replaced by tool config and plugin extensions:

  integrations/
    projects/
      framework-nuke/
        extensions/
          nuke/
            ..

See ftack-connect-pipeline-definitions chapter above for more detailed information.

Hook​

The hook is still deployed to the same location, but has been moved to the connect-plugin folder:

  integrations/
    projects/
      framework-nuke/
        connect-plugin/
          discover_ftrack_framework_nuke.py

It is pretty much the same, but without support providing timeline (start and end frame) to DCC as this has been deprecated and are to be moved to an extension.

Building​

Plugins are from now built with Poetry and not setuptools anymore, for more information on how to build an integration - please refer to the README:

  integrations/
    projects/
      framework-nuke/
        README.md

Summary​

The changes introduced with the new Framework are significant, but the new Framework has been designed to make it very easy to extend it without changing too much the Framework core libraries and default shipped base integrations - just by adding extensions on top of them.

Porting the old framework customisations to the new Framework will require some effort, but in general it is all about converting rewriting the old JSON definitions to fit the new YAML tool configs and converting the old plugins to the new simpler ones operating on the engine store.

Depending on how deep the customisations are, you might need to fork off the integrations repository and perform changes on Connect and the Framework libraries or DCC source code. But in general it should be enough to just create extensions and tell Connect and the new Framework to pick them up.