Application launcher

Connect comes built in with an application launcher that allows you to launch DCCs and other applications from within Connect. The application launcher is driven by events, and is configured through launcher configuration files written in YAML.

warning

Deprecation notice: The previous application launcher Connect plugin is deprecated, and so are the previous JSON configuration files.

note

Migration notice: If you have a custom launcher you will need to migrate this to the new YAML format.

Launching applications

As well as common actions, Application launchers can be bound to none, one or more Context.

Is therefore important to remember to select one in order to discover new applications and integrations.

note

If no applications are available, it is likely that the context is not set or that the integration is not loaded properly. Please check the logs for clues in those scenarios.the

The same goes for launching application from ftrack Studio, with the important additional check to be made ensuring the user logged in to Connect is the same as the one logged on to ftrack Studio.

Selecting integrations

Each application can request one or more integrations to run, the name of the group will appear next to the version.

Integrating

Launching an application is usually not enough to have ftrack integrated. In order to do so , integrations are provided separately.

The purpose of this hook is to provide vital information to the application startup, so the ftrack api and integration code can be fully loaded and put to the use.

Each integration will provide something similar to the hook below:

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

import os
import sys
import ftrack_api
import logging
from functools import partial


logger = logging.getLogger('example_integration.discover')


def on_application_launch(session, event):
    '''Handle application launch and add environment to *event*.'''

    # gather local paths
    plugin_base_dir = os.path.normpath(
        os.path.join(os.path.abspath(os.path.dirname(__file__)), '..')
    )

    hook_path = os.path.join(plugin_base_dir, 'resource', 'hook')

    # Add dependencies to PATH.
    python_dependencies = os.path.join(plugin_base_dir, 'dependencies')
    sys.path.append(python_dependencies)

    # Get the context is running from.
    entity = event['data']['context']['selection'][0]
    task = session.get('Context', entity['entityId'])

    data = {
        'integration': {
            "name": 'ftrack-example-integration',
            'version': '0.0.0',
            'env': {
                'FTRACK_EVENT_PLUGIN_PATH.prepend': hook_path,
                'PYTHONPATH.prepend': os.path.pathsep.join(
                    [python_dependencies]
                ),
                'FTRACK_CONTEXTID.set': task['id'],
                'FS.set': task['parent']['custom_attributes'].get(
                    'fstart', '1.0'
                ),
                'FE.set': task['parent']['custom_attributes'].get(
                    'fend', '100.0'
                ),
            },
        }
    }

    # Return the composed data for this integration.
    return data


def register(session):
    '''Subscribe to application launch events on *registry*.'''
    if not isinstance(session, ftrack_api.session.Session):
        return

    handle_event = partial(on_application_launch, session)

    # Filter the application launch and discovery, based on the application
    # identifier and the version extracted.
    session.event_hub.subscribe(
        'topic=ftrack.connect.application.launch and '
        'data.application.identifier=an_application*'
        ' and data.application.version >= 2021',
        handle_event,
        priority=40,
    )
    session.event_hub.subscribe(
        'topic=ftrack.connect.application.discover and '
        'data.application.identifier=an_application*'
        ' and data.application.version >= 2021',
        handle_event,
        priority=40,
    )

This discover is composed by 3 important pieces.

2 listeners to discover and launch
1 function hooked to them.

Listeners

Each integration will have to provide two event listeners hooked to the same function.

Each of this will have to provide a filter for the application to be launched, optional, but suggested is to provide a lower/higher limit based on the application version for this integration.

In case more than one integration has to be loaded in a given order is suggested to provide them with an increasing priority version.

The discovery one:

session.event_hub.subscribe(
    'topic=ftrack.connect.application.discover and '
    'data.application.identifier=an_application*'
    ' and data.application.version >= 2021',
    handle_event, priority=40
)

The above event will be emitted during the discovery cycle of the applications , which happens when the correct context gets selected. This is used to check the version and if the integration is available.

And the launch one:

session.event_hub.subscribe(
    'topic=ftrack.connect.application.launch and '
    'data.application.identifier=an_application*'
    ' and data.application.version >= 2021',
    handle_event, priority=40
)

The above event will be emitted during the launch cycle of the applications and will be used to parse and inject the environment variables defined during the application’s startup.

Discover Function

The discover function will be the one to provide to the applications the right environment where to pick the required files.

The bare minimum amount of data it should return in order to be discovered as working integrations is

{
    'integration': {
        "name": '<name-of-the-integration>',
        'version': '<the.integration.version>'
    }
}

where a fully formed integrations would provide also entry point for the environment variables:

data = {
    'integration': {
        "name": 'ftrack-example-integration',
        'version': '0.0.0',
        'env': {
            'FTRACK_EVENT_PLUGIN_PATH.prepend': hook_path,
            'PYTHONPATH.prepend': os.path.pathsep.join([python_dependencies]),
            'FTRACK_CONTEXTID.set': task['id'],
        }
    }
}

Managing environment variables

Each integration can express a set of environment variables and operations to be performed when handled by the application launcher.

the formatting of envs is composed by:

<$ENVIRONMENT> . <OPERATION>

for example:

'PYTHONPATH.append': '<some file system path>'

Environment operations

note

If not provided, the default operation for environment will be append

prepend : The value of the environment will be prepended.
append : The value of the environment will be appended.
set: The given environment will be set with the given value.
pop: The value of the environment variable will be removed.
unset: The environment value will be unset.

note

In case of multiple integrations loaded, the priority provided in the integration will drive the order the environment variables will be manipulated.

Launch configuration

The launch configuration is a YAML file that aids Connect in locating the application executable and provide other information about the application such as launch arguments, environment variables and paths to framework extensions.application

note

If you are migrating from v2 to v3, please see Migrating from v2 to v3.

As an example, we will have a look at the configuration for the Nuke Studio DCC application:

type: launcher
name: nuke-studio
context:
- Project
identifier: ftrack-connect-launch-nuke-studio
applicationIdentifier: nuke-studio_{variant}
label: Nuke Studio
icon: nuke_studio
variant: "{version}"
integrations:
  legacy:
  - ftrack-nuke-studio
search_path:
  linux:
    prefix:
    - "/"
    - usr
    - local
    - Nuke.*
    expression:
    - Nuke\d.+
    version_expression: Nuke(?P<version>.*)\/.+$
    launch_arguments:
    - "--studio"
  windows:
    prefix:
    - C:\
    - Program Files.*
    expression:
    - Nuke.*
    - Nuke\d.+.exe
    version_expression: "(?P<version>[\\d.]+[vabc]+[\\dvabc.]*)"
    launch_arguments:
    - "--studio"
  darwin:
    prefix:
    - "/"
    - Applications
    expression:
    - Nuke.*
    - NukeStudio\d[\w.]+.app

type: The type extension, must be set to 'launcher'.
name: The name of the launcher, this is used to identify the launcher in the application launcher.
context: The context that the launcher is available in.
identifier: The identifier of the launcher, this is used to identify the launcher in the application launcher.
applicationIdentifier: The identifier of the application, this is used to identify the application in the application launcher.
label: The label of the launcher, used by the UI.
icon: The icon of the launcher, used by the UI.
variant: The variant of the launchers.
integrations: The dependenciey intgrations that are required for the launcher to work.
search_path: The search path for the application executable, on each available platform.
environment_variables: The environment variables that should be set when launching the application, each variable can either have single or multiple values (list).
extensions_path: (Framework based integrations) The paths where extensions can be found, can be either on relative or absolute paths.

Application launcher

Launching applications​

Selecting integrations​

Integrating​

Listeners​

Discover Function​

Managing environment variables​

Environment operations​

Launch configuration​

Launching applications

Selecting integrations

Integrating

Listeners

Discover Function

Managing environment variables

Environment operations

Launch configuration