This Interface binds a Asset Management System into OpenAssetIO. More...

#include <ManagerInterface.hpp>

Public Types
using	Ptr = ManagerInterfacePtr

using	ConstPtr = ManagerInterfaceConstPtr

Batch element error handling
using	BatchElementErrorCallback = std::function< void(std::size_t, errors::BatchElementError)>
	Callback signature used for an unsuccessful operation on an element in a batch. More...

Public Member Functions
	ManagerInterface ()
	Constructor. More...

virtual	~ManagerInterface ()=default
	Polymorphic destructor. More...

Asset Management System Identification
These functions provide hosts with general identity information about the Asset Management System itself.These may all be called before initialize has been called.
virtual Identifier	identifier () const =0
	Returns an identifier to uniquely identify a specific asset manager. More...

virtual Str	displayName () const =0
	Returns a human readable name to be used to reference this specific asset manager in UIs or other user-facing messaging. More...

Initialization
virtual InfoDictionary	settings (const HostSessionPtr &hostSession)

virtual void	initialize (InfoDictionary managerSettings, const HostSessionPtr &hostSession)
	Prepares for interaction with a host. More...

virtual void	flushCaches (const HostSessionPtr &hostSession)
	Clears any internal caches. More...

Policy
virtual trait::TraitsDatas	managementPolicy (const trait::TraitSets &traitSets, access::PolicyAccess policyAccess, const ContextConstPtr &context, const HostSessionPtr &hostSession)
	Management Policy queries allow a host to ask a Manager how they would like to interact with different kinds of entity. More...

Manager State
A single 'task' in a host, may require more than one interaction with the asset management system. Because the ManagerInterface is effectively state-less. To simplify error handling, and allow an implementation to know which interactions are related, this API supports the concept of a Manager State object. This is contained in every Context and passed to relevant calls. This mechanism may be used for a variety of purposes. For example, it could ensure that queries are made from a coherent time stamp during a render, or to undo the publishing of multiple assets.
virtual ManagerStateBasePtr	createState (const HostSessionPtr &hostSession)
	Create a new object to represent the state of the interface and return it (or some handle that can be persisted within the context). More...

virtual ManagerStateBasePtr	createChildState (const ManagerStateBasePtr &parentState, const HostSessionPtr &hostSession)
	Create a state that is a child of the supplied state. More...

virtual Str	persistenceTokenForState (const ManagerStateBasePtr &state, const HostSessionPtr &hostSession)
	Returns a string that encapsulates the current state of the ManagerInterface represented by the supplied state object, (created by createState or createChildState) so that can be restored later, or in another process. More...

virtual ManagerStateBasePtr	stateFromPersistenceToken (const Str &token, const HostSessionPtr &hostSession)
	Restores the supplied state object to a previously persisted state. More...

Protected Member Functions
EntityReference	createEntityReference (Str entityReferenceString) const
	Create an EntityReference object wrapping a given Entity Reference string. More...

Asset Management System Information
These functions provide general information about the Asset Management System itself.
enum	Capability : std::underlying_type_t< internal::capability::manager::Capability > { kEntityReferenceIdentification, kManagementPolicyQueries = internal::capability::manager::Capability::kManagementPolicyQueries, kEntityTraitIntrospection, kStatefulContexts = internal::capability::manager::Capability::kStatefulContexts, kCustomTerminology = internal::capability::manager::Capability::kCustomTerminology, kResolution = internal::capability::manager::Capability::kResolution, kPublishing = internal::capability::manager::Capability::kPublishing, kRelationshipQueries = internal::capability::manager::Capability::kRelationshipQueries, kExistenceQueries = internal::capability::manager::Capability::kExistenceQueries, kDefaultEntityReferences = internal::capability::manager::Capability::kDefaultEntityReferences }
	Capabilities that the manager implements. More...

static constexpr std::array	kCapabilityNames
	Mapping of ManagerCapability enum value to human-readable name. More...

virtual bool	hasCapability (Capability capability)=0
	Query the manager as to which capabilities it implements. More...

virtual InfoDictionary	info ()
	Returns other information that may be useful about this Asset Management System. More...

virtual StrMap	updateTerminology (StrMap terms, const HostSessionPtr &hostSession)
	This call gives the manager a chance to customize certain strings used in a host's UI/messages. More...

Entity Reference Inspection
Functionality for validating entity references, and the existence or kind of entity that they point to.
using	ExistsSuccessCallback = std::function< void(std::size_t, bool)>
	Callback signature used for a successful entity existence query. More...

using	EntityTraitsSuccessCallback = std::function< void(std::size_t, trait::TraitSet)>
	Callback signature used for a successful entity trait set query. More...

virtual bool	isEntityReferenceString (const Str &someString, const HostSessionPtr &hostSession)
	Determines if the supplied string (in its entirety) matches the pattern of a valid Entity Reference in your system. More...

virtual void	entityExists (const EntityReferences &entityReferences, const ContextConstPtr &context, const HostSessionPtr &hostSession, const ExistsSuccessCallback &successCallback, const BatchElementErrorCallback &errorCallback)
	Called to determine if each Entity Reference supplied points to an entity that exists in the Asset Management System, and that they can be resolved into a meaningful string or otherwise queried. More...

virtual void	entityTraits (const EntityReferences &entityReferences, access::EntityTraitsAccess entityTraitsAccess, const ContextConstPtr &context, const HostSessionPtr &hostSession, const EntityTraitsSuccessCallback &successCallback, const BatchElementErrorCallback &errorCallback)
	Provides the host with the Trait Set of one or more entities. More...

Entity Reference Resolution
The concept of resolution is turning an Entity Reference into the data for one or more traits that are meaningful to the situation. It could be a color space, a directory, a script or a frame range for an image sequence.
using	ResolveSuccessCallback = std::function< void(std::size_t, trait::TraitsDataPtr)>
	Callback signature used for a successful entity resolution. More...

using	DefaultEntityReferenceSuccessCallback = std::function< void(std::size_t, std::optional< EntityReference >)>
	Callback signature used for a successful default entity reference query. More...

virtual void	resolve (const EntityReferences &entityReferences, const trait::TraitSet &traitSet, access::ResolveAccess resolveAccess, const ContextConstPtr &context, const HostSessionPtr &hostSession, const ResolveSuccessCallback &successCallback, const BatchElementErrorCallback &errorCallback)
	Provides the host with a TraitsData populated with the available data for the properties of the requested set of traits for each given Entity Reference. More...

virtual void	defaultEntityReference (const trait::TraitSets &traitSets, access::DefaultEntityAccess defaultEntityAccess, const ContextConstPtr &context, const HostSessionPtr &hostSession, const DefaultEntityReferenceSuccessCallback &successCallback, const BatchElementErrorCallback &errorCallback)
	Called to determine an EntityReference considered to be a sensible default for each of the given trait sets and context. More...

Related Entities
A 'related' entity could take many forms. For example: In 3D CGI, Multiple AOVs or layers may be related to a 'beauty' render. In Compositing, an image sequence may be related to the script that created it. An asset may be related to a task that specifies work to be done. Parent/child relationships are also (semantically) covered by these relationships. In this API, these relationships are represented by trait data. This may just compose property-less traits as a 'type', or additionally, set trait property values to further define the relationship. For example in the case of AOVs, the type might be 'alternate output' and the attributes may be that the 'channel' is 'diffuse'. Related references form a vital part in the abstraction of the internal structure of the asset management system from the Host application in its attempts to provide the user with meaningful functionality. A good example of this is in an editorial example, where it may need to query whether a 'shot' exists in a certain part of the asset system. One approach would be to use a 'getChildren' call, on this part of the system. This has the drawback that is assumes that shots are always something that can be described as 'immediate children' of the location in question. This may not always be the case (say, for example there is some kind of 'task' structure in place too). Instead we use a request that asks for any 'shots' that relate to the chosen location. It is then up to the implementation of the ManagerInterface to determine how that maps to its own data model. Hopefully this allows Hosts of this API to work with a broader range of asset managements, without providing any requirements of their structure or data model.
using	RelationshipQuerySuccessCallback = std::function< void(std::size_t, managerApi::EntityReferencePagerInterfacePtr)>
	Callback signature used for a successful paged entity relationship query. More...

virtual void	getWithRelationship (const EntityReferences &entityReferences, const trait::TraitsDataPtr &relationshipTraitsData, const trait::TraitSet &resultTraitSet, size_t pageSize, access::RelationsAccess relationsAccess, const ContextConstPtr &context, const HostSessionPtr &hostSession, const RelationshipQuerySuccessCallback &successCallback, const BatchElementErrorCallback &errorCallback)
	Queries entity references that are related to the input references by the relationship defined by a set of traits and their properties in `relationshipTraitsData`. More...

virtual void	getWithRelationships (const EntityReference &entityReference, const trait::TraitsDatas &relationshipTraitsDatas, const trait::TraitSet &resultTraitSet, size_t pageSize, access::RelationsAccess relationsAccess, const ContextConstPtr &context, const HostSessionPtr &hostSession, const RelationshipQuerySuccessCallback &successCallback, const BatchElementErrorCallback &errorCallback)
	Queries entity references that are related to the input reference by the relationships defined by a set of traits and their properties. More...

Publishing
The publishing functions allow a host create or update entities within the Asset Management System represented by this implementation. The API is designed to accommodate the broad variety of roles that different asset managers embody. Some are 'librarians' that simply catalog the locations of existing media. Others take an active role in both the temporary and long-term paths to items they manage. There are two key components to publishing within this API. 1 - The Entity Reference As with the other entry points in this API, it is assumed that an Entity Reference is known ahead of time. How this reference is determined is beyond the scope of this layer of the API, and functions exists in higher levels that combine browsing and publishing etc... Here, we simply assert that there must be a meaningful reference given the Trait Set of the entity that is being created or published. Note 'Meaningful' is best defined by the asset manager itself. For example, in a system that versions each 'asset' by creating children of the asset for each version, when talking about where to publish an image sequence of a render to, it may make sense to reference to the Asset itself, so that the system can determine the 'next' version number at the time of publish. It may also make sense to reference a specific version of this asset to implicitly state which version it will be written to. Other entity types may not have this flexibility. 2 - TraitsData The data for an entity is defined by one or more Traits and their properties. The resulting Trait Set defines the "type" of the entity, and the trait property values hold the data for each specific entity. This means that OpenAssetIO it not just limited to working with file-based data. Traits allow ancillary information to be managed (such as the colorspace for an image), as well as container-like entities such as shots/sequences/etc. For more on the relationship between Entities, Specifications and traits, please see this page. The action of 'publishing' itself, is split into two parts, depending on the nature of the item to be published. Preflight When a Host is about to create some new media/asset. Registration When a Host is ready to publish media that exists. For examples of how to correctly call these parts of the API within a host, see the Examples page. Note The term 'publish' is somewhat loaded. It generally means something different depending on who you are talking to. See the Glossary entry for more on this, but to help avoid confusion, this API provides the updateTerminology call, in order to allow the implementation to standardize some of the language and terminology used in a Hosts presentation of the asset management system with other integrations of the system.
using	PreflightSuccessCallback = std::function< void(std::size_t, EntityReference)>
	Callback signature used for a successful preflight operation on a particular entity. More...

using	RegisterSuccessCallback = std::function< void(std::size_t, EntityReference)>
	Callback signature used for a successful register operation on a particular entity. More...

virtual void	preflight (const EntityReferences &entityReferences, const trait::TraitsDatas &traitsHints, access::PublishingAccess publishingAccess, const ContextConstPtr &context, const HostSessionPtr &hostSession, const PreflightSuccessCallback &successCallback, const BatchElementErrorCallback &errorCallback)
	Prepares for some work to be done to create data for the referenced entity. More...

virtual void	register_ (const EntityReferences &entityReferences, const trait::TraitsDatas &entityTraitsDatas, access::PublishingAccess publishingAccess, const ContextConstPtr &context, const HostSessionPtr &hostSession, const RegisterSuccessCallback &successCallback, const BatchElementErrorCallback &errorCallback)
	Publish entities to the Asset Management System. More...

Detailed Description

This Interface binds a Asset Management System into OpenAssetIO.

It is not called directly by a host, but by the middleware that presents a more object-oriented model of this to the host - namely, the Manager.

It is structured around the following principles:

The currency of the API is either data, or an Entity Reference. objects should not be used to represent an entity or its properties.

The manager plugin is expected to be batch-first. That is, where relevant, methods expect lists as their primary input parameters, and return a list as the result. This means a host can batch together multiple items and execute the same command on every item in the list in a single call, saving on potentially expensive round-trips and allowing the manager to use other back-end optimisations.

The interface is reentrant and must be thead-safe. The result of any method should solely depend on its inputs, the underlying asset data, and any local (immutable) state established during initialize. This class could be static. In practice though, in a real-world session with a host, there are benefits to having an 'instance' with a managed lifetime. This can be used to facilitate caching, persist connections, etc.

The implementation of this class should have no UI dependencies, so that it can be used in command-line only hosts/batch process etc...

You generally don't need to call the superclass implementation of any methods in this interface, unless you are deriving from your own subclass which requires it.

Logging and Error Handling

The supplied HostSession object provides access to a logger that allow messages and progress to be reported back to the user. All logging should go through these methods otherwise it may not be correctly presented to the user. The loose term "user" also covers developers, who may need to see log output for debugging and other purposes.

Warning: Your plugin may be hosted out of process, or even on another machine, the HostSession bridge takes care of relaying messages accordingly. Using custom logging mechanisms may well result in output being lost.

See also: HostSession.logger; LoggerInterface

Exceptions should be thrown to handle any in-flight errors that occur. The error should be mapped to a derived class of exceptions.OpenAssetIOException, and thrown. All exceptions of this kind will be correctly passed across the plug-in C boundary, and re-thrown. Other exceptions should not be used.

See also: errors

Threading

Any implementation of the ManagerInterface should be thread safe. The one exception being initialize, this will never be called concurrently.

When a Context object is constructed by createContext, the createState (or createChildState for createChildContext) method will be called, and the resulting state object stored in the context. This context will then be re-used across related API calls to your implementation of the ManagerInterface. You can use this to determine which calls may be part of a specific 'action' in the same host, or logically grouped processes such as a batch render. This should allow you to implement stable resolution of meta-versions or other resolve-time concepts.

There should be no persistent state in the implementation, concepts such as getError(), etc.. for example should not be used.

Hosts

Sometimes you may need to know more information about the API host. A Host object is available through the HostSession object passed to each method of this class. This provides a standardised interface that all API hosts guarantee to implement. This can be used to identify exactly which host you are being called for, and query various entity related specifics of the hosts data model.

See also: Host

Initialization

The constructor makes a new instance, but at this point it is not ready for use. Instances of this class should be light weight to create, but don't have to be lightweight to initialize. The informational methods must be available pre-initialization, so that UI and other display-type queries can be made relatively cheaply to provide users with a list of managers and their settings. None of the entity-related methods will be called until after initialize has been called. The following methods must be callable prior to initialization:

Todo:: Finish/Document settings mechanism.

See also: initialize

Note: OpenAssetIO makes use of shared pointers to facilitate object lifetime management across multiple languages. Instances passed into API methods via shared pointer may have their lifetimes extended beyond that of your code.

Member Typedef Documentation

using BatchElementErrorCallback = std::function<void(std::size_t, errors::BatchElementError)>

Callback signature used for an unsuccessful operation on an element in a batch.

This should be called for errors that are specific to a particular reference in a batch. Exceptions can be thrown to indicate a whole-batch error.

See also: ErrorCode for appropriate error codes.

using ConstPtr = ManagerInterfaceConstPtr

using DefaultEntityReferenceSuccessCallback = std::function<void(std::size_t, std::optional<EntityReference>)>

Callback signature used for a successful default entity reference query.

using EntityTraitsSuccessCallback = std::function<void(std::size_t, trait::TraitSet)>

Callback signature used for a successful entity trait set query.

using ExistsSuccessCallback = std::function<void(std::size_t, bool)>

Callback signature used for a successful entity existence query.

using PreflightSuccessCallback = std::function<void(std::size_t, EntityReference)>

Callback signature used for a successful preflight operation on a particular entity.

using Ptr = ManagerInterfacePtr

using RegisterSuccessCallback = std::function<void(std::size_t, EntityReference)>

Callback signature used for a successful register operation on a particular entity.

using RelationshipQuerySuccessCallback = std::function<void(std::size_t, managerApi::EntityReferencePagerInterfacePtr)>

Callback signature used for a successful paged entity relationship query.

using ResolveSuccessCallback = std::function<void(std::size_t, trait::TraitsDataPtr)>

Callback signature used for a successful entity resolution.

Member Enumeration Documentation

enum Capability : std::underlying_type_t< internal::capability::manager::Capability >

strong

Capabilities that the manager implements.

Many OpenAssetIO methods are optional. This enum is used with the introspection mechanism hasCapability to provide a means of querying which sets of methods the manager provides.

These capabilities are used by both the host and the middleware to adapt their behaviour.

Enumerator
kEntityReferenceIdentification	Manager can inform the host whether a given string matches the pattern of a valid entity reference. Warning Support for this capability is required by all managers. In situations where plugins are implemented as multiple component plugins (e.g. Python and C++) at least one of the component plugins must implement this capability. This capability means the manager implements the following methods: isEntityReferenceString
kManagementPolicyQueries	Manager can provide a policy describing its behaviour with regard to specific entity types and relationships. Warning Support for this capability is required by all managers. In situations where plugins are implemented as multiple component plugins (e.g. Python and C++) at least one of the component plugins must implement this capability. This capability means the manager implements the following methods: managementPolicy
kEntityTraitIntrospection	Manager can be queried for the traits of a given entity. Warning Support for this capability is required by all managers. In situations where plugins are implemented as multiple component plugins (e.g. Python and C++) at least one of the component plugins must implement this capability. This capability means the manager implements the following methods: entityTraits
kStatefulContexts	Manager makes use of the context to persist custom state for performance reasons or otherwise. Therefore, it is required that the host persist the context across related API calls, including across distributed processes. This capability means the manager implements the following methods: createState createChildState persistenceTokenForState stateFromPersistenceToken See also Stable Entity Resolution
kCustomTerminology	Manager customizes certain human-readable strings that the host might want to use in UI/messages. This capability means the manager implements the following methods: updateTerminology
kResolution	Manager is capable of resolving Entity Reference into the data for one or more traits,. This capability means the manager implements the following methods: resolve
kPublishing	Manager allows the host to create or update an entity within the Asset Management System. This capability means the manager implements the following methods: preflight register_
kRelationshipQueries	Manager is capable of querying entity references that are related to the input references by the relationship defined by a set of traits and their properties. This capability means the manager implements the following methods: getWithRelationship getWithRelationships
kExistenceQueries	Manager is capable of confirming the existence of entities. This capability means the manager implements the following methods: entityExists
kDefaultEntityReferences	Manager may be capable of a providing an EntityReference considered to be a sensible default for a particular trait set. This capability means the manager implements the following methods: defaultEntityReference

Constructor & Destructor Documentation

ManagerInterface ( )

Constructor.

No work is done here - ManagerInterface instances should be cheap to construct. Any heavy-lifting should be done in initialize, where relevant settings are also available.

virtual ~ManagerInterface ( )

virtualdefault

Polymorphic destructor.

Member Function Documentation

virtual ManagerStateBasePtr createChildState	(	const ManagerStateBasePtr &	parentState,
		const HostSessionPtr &	hostSession
	)

virtual

Create a state that is a child of the supplied state.

This method is called whenever a child Context is made by createChildContext. The return is then stored in the newly created Context, and is consequently available to all the API calls in the ManagerInterface that take a Context instance via managerState. Your implementation can then use this to anchor the api call to a particular snapshot of the state of the asset inventory.

The default implementation will raise if called. This method must be implemented by any manager implementing createState.

Parameters

hostSession	openassetio.managerApi.HostSession, The host session that maps to the caller. This should be used for all logging and provides access to the openassetio.managerApi.Host object representing the process that initiated the API session.
parentState	obj, The new state is to be considered a 'child' of the supplied state. This may be used when creating a child Context for persistence somewhere in a UI, etc... when further processing may change the access of the Context. It is expected that the manager will migrate any applicable state components to this child context, for example - a timestamp used for 'vlatest'.

Returns: Some object that represents self-contained state of the ManagerInterface. This will be passed to future calls.

Exceptions

exceptions.StateError	If for some reason creation fails.
std::runtime_error	If called on a manager that does not implement custom state management.
errors.NotImplementedException	by default when this method is not implemented by the manager. Implementations must therefore not invoke the base class implementation.

See also: Capability::kStatefulContexts; createState; persistenceTokenForState; stateFromPersistenceToken

EntityReference createEntityReference ( Str entityReferenceString ) const

protected

Create an EntityReference object wrapping a given Entity Reference string.

This should be used for all reference creation by a manager's implementation.

No validation is performed as this method is only visible to the manager implementation, and so it is assumed that its internal business logic inherently ensures only valid strings are returned.

Parameters

entityReferenceString Raw string representation of the entity reference.

virtual ManagerStateBasePtr createState ( const HostSessionPtr & hostSession )

virtual

Create a new object to represent the state of the interface and return it (or some handle that can be persisted within the context).

You are free to implement this however you like, as long as it can be uniquely represented by the object returned from this function.

This method is called whenever a new Context is made by a createContext. The return is then stored in the newly created Context, and is consequently available to all the API calls in the ManagerInterface that take a Context instance via managerState. Your implementation can then use this to anchor the api call to a particular snapshot of the state of the asset inventory.

The default implementation of this method returns a nullptr, indicating that the manager does not perform custom state management. Manager's implementing this method must also implement createChildState, persistenceTokenForState and stateFromPersistenceToken.

Parameters

hostSession openassetio.managerApi.HostSession, The host session that maps to the caller. This should be used for all logging and provides access to the openassetio.managerApi.Host object representing the process that initiated the API session.

Returns: Some object that represents self-contained state of the ManagerInterface. This will be passed to future calls.

Exceptions

exceptions.StateError	If for some reason creation fails.
errors.NotImplementedException	by default when this method is not implemented by the manager. Implementations must therefore not invoke the base class implementation.

See also: Capability::kStatefulContexts; createChildState; persistenceTokenForState; stateFromPersistenceToken

virtual void defaultEntityReference	(	const trait::TraitSets &	traitSets,
		access::DefaultEntityAccess	defaultEntityAccess,
		const ContextConstPtr &	context,
		const HostSessionPtr &	hostSession,
		const DefaultEntityReferenceSuccessCallback &	successCallback,
		const BatchElementErrorCallback &	errorCallback
	)

virtual

Called to determine an EntityReference considered to be a sensible default for each of the given trait sets and context.

This can be used to ensure dialogs, prompts or publish locations default to some sensible value, avoiding the need for a user to re-enter such information. There may be situations where there is no meaningful default, so the caller should be robust to this situation.

For example, a host may request the default ref for the Trait Set of a 'ShotSpecification' with access 'kWrite'. If the Manager has some concept of the 'current sequence' it may wish to return this so that a 'Create Shots' action starts somewhere meaningful.

The default implementation returns a kEntityAccessError indicating that no valid default exists.

Parameters

traitSets	The relevant trait sets for the type of entities required, these will be interpreted in conjunction with the context to determine the most sensible default.
defaultEntityAccess	Intended usage of the returned entity reference(s).
context	The calling context.
hostSession	The host session that maps to the caller, this should be used for all logging and provides access to the Host object representing the process that initiated the API session.
successCallback	Callback that will be called for each successful default retrieved for each of the given sets in `traitSets`. It should be given the corresponding index of the trait set in `traitSets` along with the default entity reference. If the query is well-formed, but there is no default entity reference, then provide an `optional` without a value. The callback must called on the same thread that initiated the call to `defaultEntityReference`.
errorCallback	Callback that must be called for each failure to retrieve a sensible default entity reference. It should be given the corresponding index for each of the given sets in `traitSets` along with a populated BatchElementError (see ErrorCodes). The kEntityAccessError error must be used if no suitable default reference exists, and the kInvalidTraitSet error should be used if the requested trait set is unrecognised. The callback must be called on the same thread that initiated the call to `defaultEntityReference`.

Exceptions

errors.NotImplementedException by default when this method is not implemented by the manager. Implementations must therefore not invoke the base class implementation.

See also: Capability::kDefaultEntityReferences

virtual Str displayName ( ) const

pure virtual

Returns a human readable name to be used to reference this specific asset manager in UIs or other user-facing messaging.

One instance of its use may be in a host's preferences UI or logging. For example:

"OpenAssetIO Test Asset Manager"

Returns: Manager's display name.

virtual void entityExists	(	const EntityReferences &	entityReferences,
		const ContextConstPtr &	context,
		const HostSessionPtr &	hostSession,
		const ExistsSuccessCallback &	successCallback,
		const BatchElementErrorCallback &	errorCallback
	)

virtual

Called to determine if each Entity Reference supplied points to an entity that exists in the Asset Management System, and that they can be resolved into a meaningful string or otherwise queried.

By 'exist' we mean 'is ready to be read'. For example, entityExists may be called before attempting to read from a reference that is believed to point to an image sequence, so that alternatives can be found.

In the future, this may need to be extended to cover a more complex definition of 'existence' (for example, known to the system, but not yet finalized). For now however, it should be assumed to simply mean, 'ready to be consumed', and if only a placeholder or un-finalized asset is available, False should be returned.

The supplied context's locale may contain information pertinent to disambiguating this subtle definition of 'exists' in some cases too, as it better explains the use-case of the call.

Parameters

entityReferences	Entity references to query.
context	The calling context.
hostSession	The host session that maps to the caller, this should be used for all logging and provides access to the Host object representing the process that initiated the API session.
successCallback	Callback that must be called for each successful check of an entity reference. It should be given the corresponding index of the entity reference in `entityReferences` along with a boolean indicating the existence (as defined above) of the entity. The callback must be called on the same thread that initiated the call to `entityExists`.
errorCallback	Callback that must be called for each failed check of an entity reference. It should be given the corresponding index of the entity reference in `entityReferences` along with a populated BatchElementError (see ErrorCodes). The callback must be called on the same thread that initiated the call to `entityExists`.

Exceptions

errors.NotImplementedException by default when this method is not implemented by the manager. Implementations must therefore not invoke the base class implementation.

See also: Capability::kExistenceQueries

virtual void entityTraits	(	const EntityReferences &	entityReferences,
		access::EntityTraitsAccess	entityTraitsAccess,
		const ContextConstPtr &	context,
		const HostSessionPtr &	hostSession,
		const EntityTraitsSuccessCallback &	successCallback,
		const BatchElementErrorCallback &	errorCallback
	)

virtual

Provides the host with the Trait Set of one or more entities.

For example, a host may use this to validate that a user-provided entity reference is appropriate for an operation.

The trait set returned (via callback) for each Entity Reference should vary according to the entityTraitsAccess access mode.

If kRead is given, respond with the exhaustive trait set of the entity. Include traits whose properties you are not capable of resolving , but that nevertheless are used to categorize the entity. If an entity does not exist, then call the error callback using the kEntityResolutionError code.

If kWrite is given, respond with the minimal trait set required to publish to the entity reference. Include traits whose properties you are not capable of persisting, but which are required for categorization. If an entity is read-only, then call the error callback using the kEntityAccessError code.

Ensure your managementPolicy can be used to determine which traits hold properties that can be resolved or persisted.

An empty trait set is a valid response, for example if the entity is a new asset with no type constraints.

Parameters

entityReferences	Entity references to query.
entityTraitsAccess	The host's intended usage of the data.
context	The calling context.
hostSession	The host session that maps to the caller, this should be used for all logging and provides access to the Host object representing the process that initiated the API session.
successCallback	Callback that must be called for each trait set retrieved for the entity references. It should be given the corresponding index of the entity reference in `entityReferences` along with its Trait Set. The callback must be called on the same thread that initiated the call to `entityTraits`.
errorCallback	Callback that must be called for each failure. It should be given the corresponding index of the entity reference in `entityReferences` along with a populated BatchElementError (see ErrorCodes). The callback must be called on the same thread that initiated the call to `entityTraits`.

Exceptions

errors.NotImplementedException by default when this method is not implemented by the manager. Implementations must therefore not invoke the base class implementation.

See also: Capability::kEntityTraitIntrospection

virtual void flushCaches ( const HostSessionPtr & hostSession )

virtual

Clears any internal caches.

Only applicable if the implementation makes use of any caching, otherwise it is a no-op. In caching interfaces, this will cause any retained data to be discarded to ensure future queries are fresh.

Parameters

hostSession The API session.

virtual void getWithRelationship	(	const EntityReferences &	entityReferences,
		const trait::TraitsDataPtr &	relationshipTraitsData,
		const trait::TraitSet &	resultTraitSet,
		size_t	pageSize,
		access::RelationsAccess	relationsAccess,
		const ContextConstPtr &	context,
		const HostSessionPtr &	hostSession,
		const RelationshipQuerySuccessCallback &	successCallback,
		const BatchElementErrorCallback &	errorCallback
	)

virtual

Queries entity references that are related to the input references by the relationship defined by a set of traits and their properties in relationshipTraitsData.

This is an essential function in this API - as it is widely used to query other entities or organisational structure.

Note: Consult the documentation for the relevant relationship traits to determine if the order of entities in the inner lists of matching references is required to be meaningful.

If any relationship definition is unknown, then an empty list must be returned for that entity, and no errors raised. The default implementation returns an empty list for all relationships.

Parameters

entityReferences	A list of Entity Reference to query the specified relationship for.
relationshipTraitsData	The traits of the relationship to query.
pageSize	The size of each page of data. The page size must be fixed for the lifetime of pager object given to the `successCallback`. Guaranteed to be greater than zero.
relationsAccess	The host's intended usage of the returned references.
context	The calling context.
hostSession	The host session that maps to the caller, this should be used for all logging and provides access to the Host object representing the process that initiated the API session.
successCallback	Callback that should be called for each successful relationship query. It should be given the corresponding index of the entity reference in `entityReferences` as well as a pager capable of returning pages of entities that have the relationship to the entity at the corresponding index, specified by `relationshipTraitsData`.

The pager should be created by implementing EntityReferencePagerInterface, and should return results in pages of size specified by pageSize

If there are no relations, the pager should have no pages. The callback should be called on the same thread that initiated the call to getWithRelationship.

Parameters

errorCallback	Callback that should be called for each failed relationship query. It should be given the corresponding index of the entity reference in `entityReferences` along with a populated BatchElementError (see ErrorCodes). The callback should be called on the same thread that initiated the call to `getWithRelationship`.
resultTraitSet	A hint as to what traits the returned entities should have.

Exceptions

errors.NotImplementedException by default when this method is not implemented by the manager. Implementations must therefore not invoke the base class implementation.

See also: Capability::kRelationshipQueries

virtual void getWithRelationships	(	const EntityReference &	entityReference,
		const trait::TraitsDatas &	relationshipTraitsDatas,
		const trait::TraitSet &	resultTraitSet,
		size_t	pageSize,
		access::RelationsAccess	relationsAccess,
		const ContextConstPtr &	context,
		const HostSessionPtr &	hostSession,
		const RelationshipQuerySuccessCallback &	successCallback,
		const BatchElementErrorCallback &	errorCallback
	)

virtual

Queries entity references that are related to the input reference by the relationships defined by a set of traits and their properties.

Each element of relationshipTraitsDatas defines a specific relationship to query.

This is an essential function in this API - as it is widely used to query other entities or organisational structure.

Note: Consult the documentation for the relevant relationship traits to determine if the order of entities in the inner lists of matching references is required to be meaningful.

If any relationship definition is unknown, then an empty list must be returned for that relationship, and no errors raised. The default implementation returns an empty list for all relationships.

Parameters

entityReference	The Entity Reference to query the specified relationships for.
relationshipTraitsDatas	The traits of the relationships to query.
pageSize	The size of each page of data. The page size is fixed for the lifetime of pager object given to the `successCallback`. Guaranteed to be greater than zero.
relationsAccess	The host's intended usage of the returned references.
context	The calling context.
hostSession	The host session that maps to the caller, this should be used for all logging and provides access to the Host object representing the process that initiated the API session.
successCallback	Callback that should be called for each successful relationship query. It should be given the corresponding index of the relationship in `relationshipTraitsDatas` as well as a pager capable of returning pages of entities related to `entityReference` by the relationship at that corresponding index.

The pager should be created by implementing EntityReferencePagerInterface, and should return results in pages of size specified by pageSize

If there are no relations, the pager should have no pages. The callback should be called on the same thread that initiated the call to getWithRelationship.

Parameters

errorCallback	Callback that should be called for each failed relationship query. It should be given the corresponding index of the relationship in `relationshipTraitsDatas` along with a populated BatchElementError (see ErrorCodes). The callback should be called on the same thread that initiated the call to `getWithRelationships`.
resultTraitSet	A hint as to what traits the returned entities should have.

Note: The Trait Set of any queried relationship can be passed to managementPolicy in order to determine if the manager handles relationships of that type.

Exceptions

errors.NotImplementedException by default when this method is not implemented by the manager. Implementations must therefore not invoke the base class implementation.

See also: Capability::kRelationshipQueries

virtual bool hasCapability ( Capability capability )

pure virtual

Query the manager as to which capabilities it implements.

This method will only be called post-initialize, but must be cheap to evaluate, and always return the same values.

API methods are grouped into "capabilities", which are independent groupings of functionality. For example, publishing or resolution.

Failure to accurately reflect the capabilities of your manager may result in hosts calling into the default implementation, which throws NotImplementedException, or may cause hosts to ignore capability that you have implemented.

For information on what methods belong to which capability set,

See also: Capability.

Parameters

capability The capability to check.

Returns: Whether the manager has the capability in question.

virtual Identifier identifier ( ) const

pure virtual

Returns an identifier to uniquely identify a specific asset manager.

This may be used by a host to persist the users preferred manager via a preferences mechanism, or when spawning child processes, etc...

It should match the name used to register the plug-in with the plug-in host. The identifier should use only alpha-numeric characters and '.', '_' or '-'. Generally speaking, we recommend using the 'reverse-DNS' convention, for example:

"org.openassetio.test.manager"

Returns: Unique identifier of the manager.

See also: https://en.wikipedia.org/wiki/Reverse_domain_name_notation

virtual InfoDictionary info ( )

virtual

Returns other information that may be useful about this Asset Management System.

This can contain arbitrary key/value pairs. For example:

{ 'version' : '1.1v3', 'server' : 'assets.openassetio.org' }

There are certain optional keys that may be used by a host or the API:

constants::kInfoKey_SmallIcon (upto 32x32)
constants::kInfoKey_Icon (any size)

Because it can often be expensive to bridge between languages, info can also contain an additional field - a prefix that identifies a string as a valid entity reference. If supplied, this will be used by the API to optimize calls to isEntityReferenceString when bridging between C/Python etc. If this isn't supplied, then isEntityReferenceString will always be called to determine if a string is an Entity Reference or not. Note, not all invocations require this optimization, so isEntityReferenceString should be implemented regardless.

constants::kInfoKey_EntityReferencesMatchPrefix

Returns: Map of info string key to primitive value.

virtual void initialize	(	InfoDictionary	managerSettings,
		const HostSessionPtr &	hostSession
	)

virtual

Prepares for interaction with a host.

This method is passed a settings dictionary, that can be used to configure required local state to service requests. For example, determining the authoritive back-end service managing asset data. This is also a good opportunity to initialize any connections or fetch pre-requisite data. It is fine for this call to block for a period of time.

If an exception is raised by this call, it signifies to the host that a fatal error occurred, and this Asset Management System is not available with the current settings.

If no exception is raised, it can be assumed that the Asset Management System is ready. It is the implementations responsibility to deal with transient connection errors (if applicable) once initialized.

If called on an already initialized instance, re-initialize with any updated settings that are provided. If an error was raised previously, then initialization should be re-attempted.

Note: This will always be called prior to any Entity-related calls. An exception should be raised if this is not the case. It is however, the following functions may be called prior to initialization:

Todo:: We need a 'teardown' method to, before a manager is de-activated in a host, to allow any event registrations etc... to be removed.

virtual bool isEntityReferenceString	(	const Str &	someString,
		const HostSessionPtr &	hostSession
	)

virtual

Determines if the supplied string (in its entirety) matches the pattern of a valid Entity Reference in your system.

It does not need to verify that it points to a valid entity in the system, simply that the pattern of the string is recognised by this implementation.

Note: If possible, consider supplying a prefix in your info() dictionary, so that calls to this method can be circumvented by performing a (fast) string prefix check instead.

Return True if the string is an Entity Reference and should be considered usable with the other methods of this interface.

Return False, if this should no longer be involved in actions relating to the string as it is not recognised.

Warning: The result of this call should not depend on the context Locale, and should be trivial to compute. If for example, a manager makes use of URL-based entity references, then it is sufficient to check that the string's schema is that owned by the manager. This method should not validate the correctness of all supplied host, path or query components. The API middleware may cache or short-circuit calls to this method when bridging between languages.

Parameters

someString	str The string to be inspected.
hostSession	HostSession The API session.

Returns: bool True if the supplied string should be considered as an Entity Reference, False if the pattern is not recognised.

Note: This call should not verify an entity exits, just that the format of the string is recognised as a potential entity reference by the manager.

Exceptions

errors.NotImplementedException by default when this method is not implemented by the manager. Implementations must therefore not invoke the base class implementation. This exception being thrown constitutes a manager implementation error, as all managers must implement this method in one of their component plugins.

See also: Capability::kEntityReferenceIdentification; entityExists; resolve

virtual trait::TraitsDatas managementPolicy	(	const trait::TraitSets &	traitSets,
		access::PolicyAccess	policyAccess,
		const ContextConstPtr &	context,
		const HostSessionPtr &	hostSession
	)

virtual

Management Policy queries allow a host to ask a Manager how they would like to interact with different kinds of entity.

This includes the policy for a given trait set, as well as the per-trait policy, with the context for the policy determined by the policyAccess.

This method is usually called early on by a host to determine whether to enable OpenAssetIO related functionality when handling specific kinds of data. The host will often adapt its subsequent behaviour to minimise unsupported interactions with the manager. In high call volume scenarios (such as CG rendering), this can potentially save hundreds of thousands of redundant calls into the API for unmanaged entity traits.

As such, the implementation of this method (and careful consideration of the responses it returns) is critical. Due to the calling patterns, the manager's policy must be runtime invariant for any given set of inputs.

Note: It is not required that a Host calls this method before invoking other API methods, and so methods such as resolve or register_ must be tolerant of being called with unsupported traits (fear not, there is a simple and established failure mode for this situation).

This method must return a TraitsData for each requested Trait Set. The implementation of this method should carefully consider the given access, and imbue suitable traits in the result to define:

Whether and how that kind of entity is managed (traits with the managementPolicy usage metadata)
Which of the requested set of traits that have properties that must/can be resolved/persisted by your implementation.

The meaning of the subset of traits in the response should vary by policyAccess mode as follows

kRead: traits that have properties the manager can resolve from existing entities.
kWrite and kCreateRelated: traits that have properties the manager can persist when publishing.
kRequired: traits whose properties must be provided by the host in order for publishing to succeed.
kManagerDriven: traits that have properties that the manager can resolve for a future entity (i.e. an entity reference returned from a preflight call) that is yet to be registered. That is, traits that the manager wishes to drive, rather than have the host decide.

Entity management is an opt-in mechanism, and returning an empty TraitsData states that you do not manage data with that specific Trait Set, and hosts should avoid making redundant calls into the API or presenting asset-centric elements of a workflow to the user.

This method gives the global policy for how you wish to interact with certain categories of entity. See entityTraits for entity-specific introspection.

Note: Because traits are specific to any given application of the API, please refer to the documentation for any relevant companion project(s) that provide traits and specifications for your specific scenario. For example, the OpenAssetIO-MediaCreation project provides traits for common data types used in computer graphics and media production. Use the concrete Trait/Specification classes provided by these projects to manipulate the result TraitsData instead of directly setting traits and properties with string literals.

Warning: The given policyAccess should be carefully considered. A host will independently query the policy for both read and write access to determine if resolution and publishing features are applicable to this implementation.

Parameters

traitSets	The entity traits to query.
policyAccess	Type of operation that the host would like to perform on entities of the type given in `traitSets`.
context	The calling context.
hostSession	The API session.

Returns: a TraitsData for each element in traitSets.

Exceptions

errors.NotImplementedException by default when this method is not implemented by the manager. Implementations must therefore not invoke the base class implementation. This exception being thrown constitutes a manager implementation error, as all managers must implement this method in one of their component plugins.

See also: Capability::kManagementPolicyQueries

virtual Str persistenceTokenForState	(	const ManagerStateBasePtr &	state,
		const HostSessionPtr &	hostSession
	)

virtual

Returns a string that encapsulates the current state of the ManagerInterface represented by the supplied state object, (created by createState or createChildState) so that can be restored later, or in another process.

Returns: A string that can be used to restore the stack.

Exceptions

std::runtime_error	If called on a manager that does not implement custom state management.
errors.NotImplementedException	by default when this method is not implemented by the manager. Implementations must therefore not invoke the base class implementation.

See also: Capability::kStatefulContexts; stateFromPersistenceToken

virtual void preflight	(	const EntityReferences &	entityReferences,
		const trait::TraitsDatas &	traitsHints,
		access::PublishingAccess	publishingAccess,
		const ContextConstPtr &	context,
		const HostSessionPtr &	hostSession,
		const PreflightSuccessCallback &	successCallback,
		const BatchElementErrorCallback &	errorCallback
	)

virtual

Prepares for some work to be done to create data for the referenced entity.

The entity may not yet exist (Entity Reference). This call is designed to allow validation of the target reference, placeholder creation or any other sundry preparatory actions to be carried out.

If this does not apply to the manager's workflow, then the method can pass back the input reference once the target entity reference has been validated.

Generally, this will be called before register() when data is not already immediately available for registration, to allow placeholder actions to be performed. Note: depending on the returned managementPolicy, the host may make additional API queries using the reference returned here before registration.

This call must block until preflight is complete for all supplied references, and callbacks have been called on the same thread that called preflight

Warning: If the supplied trait data is missing required traits for any of the provided references (maybe they are mismatched with the target entity), or the populated properties are insufficient or invalid for upcoming resolve for write requests or the eventual register_, then error that element with an appropriate openassetio::v1::errors::BatchElementError::ErrorCode.

A host may use entityTraits to determine the minimal Trait Set required for publishing to an entity reference. Note that it is not necessary to persist the properties of all of these traits, they may solely aid in classification. See entityTraits docs for more information.

Parameters

entityReferences	An Entity Reference for each entity that it is desired to publish the forthcoming data to. See the notes in the API documentation for the specifics of this.
traitsHints	Trait Set for each entity, determining the type of entity to publish, complete with any properties the host owns and can provide at this time. See glossary entry for more information.
publishingAccess	Whether to perform a generic write to an entity or to (explicitly) create arelated" entity.
context	The calling context. This is not replaced with an array in order to simplify implementation. Otherwise, transactional handling has the potential to be extremely complex if different contexts are allowed.
hostSession	The API session.
successCallback	Callback to be called for each successful preflight of an entity reference. It should be called with the corresponding index of the entity reference in `entityReferences` along with the (potentially revised) working reference to be used by the host for the rest of the publishing operation for this specific entity (ie, resolve then register). This is an opportunity to update the reference to one specific to any placeholder/reserved entities if applicable. The callback must be called on the same thread that initiated the call to `preflight`.
errorCallback	Callback to be called for each failed preflight of an entity reference. It should be called with the corresponding index of the entity reference in `entityReferences` along with a populated BatchElementError (see ErrorCodes). The callback must be called on the same thread that initiated the call to `preflight`. A kEntityAccessError should be used if the access pattern cannot be adhered to, for example when attempting to write any target references that are conceptually read-only in response to kWrite, or in response to kCreateRelated if creating related entities is not supported. A kInvalidPreflightHint should be used for any target references who's corresponding `traitsHints` entry holds insufficient or invalid information.

Exceptions

errors.NotImplementedException by default when this method is not implemented by the manager. Implementations must therefore not invoke the base class implementation.

See also: Capability::kPublishing; register_

virtual void register_	(	const EntityReferences &	entityReferences,
		const trait::TraitsDatas &	entityTraitsDatas,
		access::PublishingAccess	publishingAccess,
		const ContextConstPtr &	context,
		const HostSessionPtr &	hostSession,
		const RegisterSuccessCallback &	successCallback,
		const BatchElementErrorCallback &	errorCallback
	)

virtual

Publish entities to the Asset Management System.

This instructs the implementation to ensure a valid entity exists for each given reference and to persist the data provided in the openassetio::v1::trait::TraitsData. This will be called either in isolation or after calling preflight, depending on whether there is work needed to be done to generate the data. Preflight is omitted if the data is already available at the time of publishing.

This call must block until registration is complete for all supplied references, and callbacks have been called on the same thread that called register

This is an opportunity to do other things in the host as part of publishing if required. The context's locale will tell you more about the specifics of the calling application. Depending on the implementation of your plugin, you can use this opportunity to make use of the host-native SDK to extract additional information or schedule additional processes to produce derivative data.

Warning: It is a requirement of the API that the Trait Set of the supplied TraitsData for each reference is persisted. This forms the entity's 'type'. It is also a requirement that the properties of any traits indicated as supported by your response to a managementPolicy query with write access are persisted.

If the supplied Trait Set is missing required traits for any of the provided references (maybe they are mismatched with the target entity, or missing essential data) then error that element with an appropriate ErrorCode.

A host may use entityTraits to determine the minimal Trait Set required for publishing to an entity reference. Note that it is not necessary to persist the properties of all of these traits, they may be used solely to aid in classification. See entityTraits docs for more information.

Parameters

entityReferences The Entity Reference of each entity to register_. It is up to the manager to ensure that this is meaningful, as it is most likely implementation specific. For example, if an entity with the traits of a 'Shot' specification is requested to be published to a reference that points to a 'Sequence' it makes sense to interpret this as a 'add a shot of this spec to the sequence'. For other types of entity, there may be different constraints on what makes sense.

entityTraitsDatas The data for each entity (or 'asset') that is being published. The implementation must persist the list of traits, and any supported traits with properties. Such that a subsequent call to resolve for any of these traits contains that data. It is guaranteed that the trait sets of these instances are constant across the batch.

Note: Generally speaking, the data within the supplied trait properties should be persisted verbatim. If however, the implementation has any specific understanding of any given trait, it is free to rewrite this data in any meaningful fashion. The simplest example of this is the MediaCreation LocatableContent trait, where the location URL may be updated to the long-term persistent storage location of the registered data, after it has been re-located by the manager.

Parameters

publishingAccess	Whether to perform a generic write to an entity or to (explicitly) create arelated" entity.
context	The calling context.
hostSession	The API session.
successCallback	Callback to be called for each successful registration. It should be called with the corresponding index of the entity reference in `entityReferences` along with the (potentially revised) final reference to be used by the host for subsequent interactions with this specific entity. This is an opportunity to update the reference to one specific to the resulting entity and/or its specific version as applicable. The callback must be called on the same thread that initiated the call to `register`.
errorCallback	Callback to be called for each failed registration. It should be called with the corresponding index of the entity reference in `entityReferences` along with a populated BatchElementError (see ErrorCodes). The callback must be called on the same thread that initiated the call to `register`.

Exceptions

errors.NotImplementedException by default when this method is not implemented by the manager. Implementations must therefore not invoke the base class implementation.

See also: Capability::kPublishing; TraitsData; preflight

virtual void resolve	(	const EntityReferences &	entityReferences,
		const trait::TraitSet &	traitSet,
		access::ResolveAccess	resolveAccess,
		const ContextConstPtr &	context,
		const HostSessionPtr &	hostSession,
		const ResolveSuccessCallback &	successCallback,
		const BatchElementErrorCallback &	errorCallback
	)

virtual

Provides the host with a TraitsData populated with the available data for the properties of the requested set of traits for each given Entity Reference.

This call should block until all resolutions are complete and callbacks have been called. Callbacks must be called on the same thread that called resolve.

Requested traits that aren't applicable to any particular entity, have no properties, or are not supported by your implementation, should be ignored and not imbued to the result. Your implementation of managementPolicy when called with a read access mode should accurately reflect which traits you understand and are capable of resolving data for here.

The entityTraits method may be called by hosts to determine the Trait Set of an entity. It is not necessary to be able to resolve the properties for all of an entity's traits - they may be used solely to aid classification. See docs for entityTraits for more information.

Warning: See the documentation for each respective trait as to which properties are considered required. It is the responsibility of the caller to handle optional property values being missing in a fashion appropriate to its intended use.

Note: Some trait properties may support substitution tokens, or similar. The conventions for these will be defined in the trait's documentation. See the originating project for more information on their specifics. Don't forget to add a scheme and URL encode any paths that are stored in properties defined as holding a URL.

The resolveAccess should also be carefully considered to ensure that it does not violate any rules of the system - for example, resolving a read-only entity reference for write.

The supplied entity references will have already been validated as relevant to this manager (via isEntityReferenceString).

There may still be errors during resolution. An exception can be thrown for unexpected errors that should fail the whole batch, and it is up to the host to handle the exception. For errors specific to a particular entity, where other entities may still resolve successfully, an appropriate BatchElementError should be given to the errorCallback. Using HTTP status codes as an analogy, typically a server error (5xx) would correspond to an exception whereas a client error (4xx) would correspond to a BatchElementError.

Parameters

entityReferences	Entity references to query.
traitSet	The traits to resolve for the supplied list of entity references.
resolveAccess	The host's intended usage of the data.
context	The calling context.
hostSession	The API session.
successCallback	Callback that must be called for each successful resolution of an entity reference. It should be given the corresponding index of the entity reference in `entityReferences` along with its `TraitsData`. The callback must be called on the same thread that initiated the call to `resolve`.
errorCallback	Callback that must be called for each failed resolution of an entity reference. It should be given the corresponding index of the entity reference in `entityReferences` along with a populated BatchElementError (see ErrorCodes). The callback must be called on the same thread that initiated the call to `resolve`.

Exceptions

errors.NotImplementedException by default when this method is not implemented by the manager. Implementations must therefore not invoke the base class implementation.

See also: Capability::kResolution; entityExists; isEntityReferenceString; BatchElementError

virtual InfoDictionary settings ( const HostSessionPtr & hostSession )

virtual

Todo:: Document settings mechanism

Parameters

hostSession The API session.

Returns: Any settings relevant to the function of the manager with their current values (or their defaults if initialize has not yet been called).

The default implementation returns an empty dictionary.

virtual ManagerStateBasePtr stateFromPersistenceToken	(	const Str &	token,
		const HostSessionPtr &	hostSession
	)

virtual

Restores the supplied state object to a previously persisted state.

Returns: A state object, as per createState(), except restored to the previous state encapsulated in the token, which is the same string as returned by persistenceTokenForState.

Exceptions

exceptions.StateError	If the supplied token is not meaningful, or that a state has already been restored.
std::runtime_error	If called on a manager that does not implement custom state management.
errors.NotImplementedException	by default when this method is not implemented by the manager. Implementations must therefore not invoke the base class implementation.

See also: Capability::kStatefulContexts

virtual StrMap updateTerminology	(	StrMap	terms,
		const HostSessionPtr &	hostSession
	)

virtual

This call gives the manager a chance to customize certain strings used in a host's UI/messages.

See terminology for known keys. The values in stringDict can be freely updated to match the terminology of the asset management system you are representing.

For example, you may way a host's "Publish Clip" menu item to read "Release Clip", so you would set the openassetio.hostApi.terminology.kTerm_Publish value to "Release".

See also: terminology.defaultTerminology

Parameters

terms	Map of terms to be substituted by the manager.
hostSession	The host session that maps to the caller. This should be used for all logging and provides access to the Host object representing the process that initiated the API session.

Returns: Substituted map of terms.

Exceptions

errors.NotImplementedException by default when this method is not implemented by the manager. Implementations must therefore not invoke the base class implementation.

See also: Capability::kCustomTerminology

Member Data Documentation

constexpr std::array kCapabilityNames

static

Initial value:

{"entityReferenceIdentification",
                                                                "managementPolicyQueries",
                                                                "statefulContexts",
                                                                "customTerminology",
                                                                "resolution",
                                                                "publishing",
                                                                "relationshipQueries",
                                                                "existenceQueries",
                                                                "defaultEntityReferences",
                                                                "entityTraitIntrospection"}

Mapping of ManagerCapability enum value to human-readable name.

The documentation for this class was generated from the following file:

/src/src/openassetio-core/include/openassetio/managerApi/ManagerInterface.hpp

Public Types

Public Member Functions

Protected Member Functions

Asset Management System Information

Entity Reference Inspection

Entity Reference Resolution

Related Entities

Publishing

Detailed Description

Logging and Error Handling

Threading

Hosts

Initialization

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation