This page covers how to configure OpenAssetIO for a specific end-user working environment.

Overview

An OpenAssetIO enabled tool or application is known as a Host (as it "hosts" the API). Through the use of manager plugins, OpenAssetIO allows the host to communicate with one or more Asset Management Systems, called Managers.

This page covers hows to configure OpenAssetIO so that the hosts you use (e.g. DCC tools, applications and other scripts) use a specific manager of your choice to resolve and potentially publish data.

OpenAssetIO itself is usually built into any host that supports it, this means you don't normally need do to anything to ensure the API itself is present. The most common tasks in configuration are:

Installing manager plugins and making them available to a host.
Configuring which manager a host should use.

Installing Manager plugins

Note: To aid problem solving, the plugin systems log debug messages when they search for and load plugins.

OpenAssetIO supports Python, C++, and hybrid plugins.

Typically there will only be a single asset management system in use, with a corresponding plugin(s). However, if there are multiple systems available with their own OpenAssetIO manager plugins, it is safe, and encouraged, to install all of them such that they're discoverable (as described below). For example, some host applications may support multiple managers simultaneously.

Using pip

Most Python-based plugins should support what is known as "entry point" based loading. This means they can be installed using the package installer for Python, and will then be automatically detected.

These plugins are usually published to PyPI, and so are easy to install. Simply use the pip module of the Python installation you wish to make the plugin available to:

1 python -m pip install <manager-plugin-package>

If the plugin is not published, you may be able to install it from a local checkout of its source code:

1 python -m pip install <path/to/src>

Warning: Many hosts use their own embedded Python interpreter. You may need to consult the relevant documentation to determine its location, version, sys.path etc. and adjust the invocation of python accordingly, so that the plugin is installed to the correct Python instance.

Manual installation

The OpenAssetIO plugin system can also be explicitly configured to look in specific locations. The $OPENASSETIO_PLUGIN_PATH environment variable can be set to point to one or more directories containing manager plugins.

This is required for C++ plugins, but can be used for Python plugins as well, where entry point discovery (described above) is not available.

It is a standard 'left-most wins' search-path, that uses platform specific delimiters (see here for more information).

This variable is completely independent from $PYTHONPATH, $LD_LIBRARY_PATH, or any other language/host specific configuration.

This can simplify deployment by allowing a common location to be specified to, for example, service multiple hosts and Python versions (assuming the manager plugins have been suitably coded).

To install a plugin using this approach:

Download or otherwise obtain the required manager plugin.
Place this in your chosen location. This can be anywhere on a filesystem that is visible to the hosts that you wish to use.
Set, or extend $OPENASSETIO_PLUGIN_PATH to include this location.

Hybrid plugins

The hybrid plugin system allows multiple plugin systems to be composed. Typically, this means a C++ and a Python plugin system.

This reduces boilerplate for supporting multiple plugin systems simultaneously. It also has the unique ability to compose multiple plugins together, dispatching to the appropriate plugin for a given API request.

The hybrid plugin system should be the default choice for any host that can support both Python and C++ plugins - i.e. any pure Python host or any C++ host with an embedded Python interpreter.

The appropriate plugin for an API request is determined as follows:

On construction, the hybrid plugin system is provided with a list of plugin systems to compose (e.g. C++ and Python). The order of this list establishes a priority order.
When the host requests a plugin with a particular identifier (via a config file or otherwise), any plugin that matches the identifier, from any listed plugin system, is a candidate for API requests.
When a specific API request is made, the highest priority plugin is used that supports the capability associated with the API method.

Note that the OpenAssetIO API is designed to be stateless. By this we mean that all data required to service an API request is provided with every API method invocation. In particular, the Context can be used by managers to coordinate higher-level state across API method invocations. This can enable data sharing between multiple constituent plugins of a hybrid plugin, without them requiring an explicit communication channel.

Host configuration

In order to make use of OpenAssetIO to manage data, the host needs to know which manager plugin it should use, and any associated settings that plugin many need (e.g. server configuration).

Most hosts should support the OpenAssetIO default configuration mechanism. This simplifies sharing settings between hosts in a centralized fashion.

Advanced hosts with specific workflows may require configuring by other means - please consult the relevant host provided documentation in these cases.

The Default Config Mechanism

You can specify your preferred manager and settings in a simple TOML file, and set the $OPENASSETIO_DEFAULT_CONFIG to point to this file. Hosts should then use this configuration to setup the API at startup.

The format for manager-specific sections of this file is documented here.

To configure OpenAssetIO using this approach:

Create a TOML file with the identifier and any settings in a location of your choosing. This can be anywhere on a filesystem that is visible to the hosts that you wish to use.
Set $OPENASSETIO_DEFAULT_CONFIG to point to that file.

Note: Some hosts may provide functionality to override or ignore this configuration.

Troubleshooting

To help diagnose issues, first make sure that debug logging is enabled in your host. You usually do this by adjusting the host's native logging controls, or in some cases you may need to set $OPENASSETIO_LOGGING_SEVERITY to 1.

Pip installed Python plugins not being found

Check any messages logged by the plugin system during startup.
Check with the plugin's documentation that it does support entry point based loading.
Check that the Python interpreter used by your host is the same version as the one used to install via pip.
Check that the appropriate directory is on sys.path in the host's interpreter.

Manually installed plugins not being found

Check $OPENASSETIO_PLUGIN_PATH includes the directory in which the desired plugins reside.
Check any messages logged by the plugin system during startup.

Default config mechanism not working

Check $OPENASSETIO_DEFAULT_CONFIG points to the file using a valid path for the operating system in question.
Check the user has read permissions for the file.
Check any messages logged by the manager factory during startup.