The Manager is the Host facing representation of an Asset Management System. More...

#include <Manager.hpp>

Classes
struct	BatchElementErrorPolicyTag
	Tag dispatching structure intended for use selecting appropriate overloads for various error-handling modes. More...

Public Types
using	Ptr = ManagerPtr

using	ConstPtr = ManagerConstPtr

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
Asset Management System Identification
These functions provide general identity information about the Asset Management System itself. These can all be called before initialize has been called.
Identifier	identifier () const
	Returns an identifier to uniquely identify the Manager. More...

Str	displayName () const
	Returns a human readable name to be used to reference this specific asset manager in user-facing displays. More...

Initialization
InfoDictionary	settings ()

void	initialize (InfoDictionary managerSettings)
	Prepares the Manager for interaction with a host. More...

void	flushCaches ()
	Clears any internal caches. More...

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

Context Management
See also Stable Entity Resolution
ContextPtr	createContext ()
	Creates a new Context for use with the manager. More...

ContextPtr	createChildContext (const ContextPtr &parentContext)
	Creates a child Context for use with the manager. More...

Str	persistenceTokenForContext (const ContextPtr &context)
	Returns a serializable token that represents the supplied context's managerState, such that it can be persisted or distributed between processes to associate subsequent API usage with the supplied context. More...

ContextPtr	contextFromPersistenceToken (const Str &token)
	Returns a Context linked to a previous manager state, based on the supplied persistence token derived from persistenceTokenForContext. More...

Static Public Member Functions
static ManagerPtr	make (managerApi::ManagerInterfacePtr managerInterface, managerApi::HostSessionPtr hostSession)
	Constructs a new Manager wrapping the supplied manager interface and host session. 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 > { 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...

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

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

StrMap	updateTerminology (StrMap terms)
	This call gives the Manager a chance to customize certain strings that you might want to use in your UI/messages. More...

Entity Reference Inspection
Functionality for validating and creating 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...

bool	isEntityReferenceString (const Str &someString)

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

std::optional< EntityReference >	createEntityReferenceIfValid (Str entityReferenceString)
	Create an EntityReference object wrapping a given Entity Reference string, if it is valid according to isEntityReferenceString. More...

void	entityExists (const EntityReferences &entityReferences, const ContextConstPtr &context, 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 EntityTraitsSuccessCallback &successCallback, const BatchElementErrorCallback &errorCallback)
	Retrieve the Trait Set of one or more entities. More...

trait::TraitSet	entityTraits (const EntityReference &entityReference, access::EntityTraitsAccess entityTraitsAccess, const ContextConstPtr &context, const BatchElementErrorPolicyTag::Exception &errorPolicyTag={})
	Retrieve the Trait Set of an entity. More...

std::variant< errors::BatchElementError, trait::TraitSet >	entityTraits (const EntityReference &entityReference, access::EntityTraitsAccess entityTraitsAccess, const ContextConstPtr &context, const BatchElementErrorPolicyTag::Variant &errorPolicyTag)
	Provides either a populated Trait Set or a BatchElementError. More...

std::vector< trait::TraitSet >	entityTraits (const EntityReferences &entityReferences, access::EntityTraitsAccess entityTraitsAccess, const ContextConstPtr &context, const BatchElementErrorPolicyTag::Exception &errorPolicyTag={})
	Retrieve the Trait Set of one or more entities. More...

std::vector< std::variant< errors::BatchElementError, trait::TraitSet > >	entityTraits (const EntityReferences &entityReferences, access::EntityTraitsAccess entityTraitsAccess, const ContextConstPtr &context, const BatchElementErrorPolicyTag::Variant &errorPolicyTag)
	Provides either a populated Trait Set or a BatchElementError for each given Entity Reference. More...

Entity 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...

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

trait::TraitsDataPtr	resolve (const EntityReference &entityReference, const trait::TraitSet &traitSet, access::ResolveAccess resolveAccess, const ContextConstPtr &context, const BatchElementErrorPolicyTag::Exception &errorPolicyTag={})
	Provides a TraitsData populated with the available data for the requested set of traits for the given Entity Reference. More...

std::variant< errors::BatchElementError, trait::TraitsDataPtr >	resolve (const EntityReference &entityReference, const trait::TraitSet &traitSet, access::ResolveAccess resolveAccess, const ContextConstPtr &context, const BatchElementErrorPolicyTag::Variant &errorPolicyTag)
	Provides either a populated TraitsData or a BatchElementError. More...

std::vector< trait::TraitsDataPtr >	resolve (const EntityReferences &entityReferences, const trait::TraitSet &traitSet, access::ResolveAccess resolveAccess, const ContextConstPtr &context, const BatchElementErrorPolicyTag::Exception &errorPolicyTag={})
	Provides a TraitsData populated with the available data for the requested set of traits for each given Entity Reference. More...

std::vector< std::variant< errors::BatchElementError, trait::TraitsDataPtr > >	resolve (const EntityReferences &entityReferences, const trait::TraitSet &traitSet, access::ResolveAccess resolveAccess, const ContextConstPtr &context, const BatchElementErrorPolicyTag::Variant &errorPolicyTag)
	Provides either a populated TraitsData or a BatchElementError for each given Entity Reference. More...

void	defaultEntityReference (const trait::TraitSets &traitSets, access::DefaultEntityAccess defaultEntityAccess, const ContextConstPtr &context, const DefaultEntityReferenceSuccessCallback &successCallback, const BatchElementErrorCallback &errorCallback)
	Called to determine an EntityReference considered to be a sensible default for each of the given entity 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 the 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 workflow, where you 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 manager to determine how that maps to its own data model. Hopefully this allows a host to work with a broader range of asset management systems, without providing any requirements of their structure or data model within the system itself.
using	RelationshipQuerySuccessCallback = std::function< void(std::size_t, EntityReferencePagerPtr)>
	Callback signature used for a successful paged entity relationship query. More...

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

void	getWithRelationships (const EntityReference &entityReference, const trait::TraitsDatas &relationshipTraitsDatas, size_t pageSize, access::RelationsAccess relationsAccess, const ContextConstPtr &context, const RelationshipQuerySuccessCallback &successCallback, const BatchElementErrorCallback &errorCallback, const trait::TraitSet &resultTraitSet={})
	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 the host to create or update an entity within the Asset Management System represented by the Manager. 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 TraitsData 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 you are about to create some new media/asset. Registration When you wish to publish media that exists. For examples of how to correctly call these parts of the API, 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 Manager to standardize some of the language and terminology used in your presentation of the asset management system with other integrations of the system. 3 - Thumbnails The API provides a mechanism for a manager to request a thumbnail for an entity as it is being published, see: Thumbnails.
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...

void	preflight (const EntityReferences &entityReferences, const trait::TraitsDatas &traitsHints, access::PublishingAccess publishingAccess, const ContextConstPtr &context, const PreflightSuccessCallback &successCallback, const BatchElementErrorCallback &errorCallback)
	This call signals your intent as a host application to do some work to create data in relation to each supplied Entity Reference. More...

EntityReference	preflight (const EntityReference &entityReference, const trait::TraitsDataPtr &traitsHint, access::PublishingAccess publishingAccess, const ContextConstPtr &context, const BatchElementErrorPolicyTag::Exception &errorPolicyTag={})
	This call signals your intent as a host application to do some work to create data in relation to a supplied Entity Reference. More...

std::variant< errors::BatchElementError, EntityReference >	preflight (const EntityReference &entityReference, const trait::TraitsDataPtr &traitsHint, access::PublishingAccess publishingAccess, const ContextConstPtr &context, const BatchElementErrorPolicyTag::Variant &errorPolicyTag)
	This call signals your intent as a host application to do some work to create data in relation to a supplied Entity Reference. More...

EntityReferences	preflight (const EntityReferences &entityReferences, const trait::TraitsDatas &traitsHints, access::PublishingAccess publishingAccess, const ContextConstPtr &context, const BatchElementErrorPolicyTag::Exception &errorPolicyTag={})
	This call signals your intent as a host application to do some work to create data in relation to each supplied Entity Reference. More...

std::vector< std::variant< errors::BatchElementError, EntityReference > >	preflight (const EntityReferences &entityReferences, const trait::TraitsDatas &traitsHints, access::PublishingAccess publishingAccess, const ContextConstPtr &context, const BatchElementErrorPolicyTag::Variant &errorPolicyTag)
	This call signals your intent as a host application to do some work to create data in relation to each supplied Entity Reference. More...

void	register_ (const EntityReferences &entityReferences, const trait::TraitsDatas &entityTraitsDatas, access::PublishingAccess publishingAccess, const ContextConstPtr &context, const RegisterSuccessCallback &successCallback, const BatchElementErrorCallback &errorCallback)
	Register should be used to 'publish' new entities either when originating new data within the application process, or referencing some existing file, media or information. More...

EntityReference	register_ (const EntityReference &entityReference, const trait::TraitsDataPtr &entityTraitsData, access::PublishingAccess publishingAccess, const ContextConstPtr &context, const BatchElementErrorPolicyTag::Exception &errorPolicyTag={})
	Register should be used to 'publish' new entities either when originating new data within the application process, or referencing some existing file, media or information. More...

std::variant< errors::BatchElementError, EntityReference >	register_ (const EntityReference &entityReference, const trait::TraitsDataPtr &entityTraitsData, access::PublishingAccess publishingAccess, const ContextConstPtr &context, const BatchElementErrorPolicyTag::Variant &errorPolicyTag)
	Register should be used to 'publish' new entities either when originating new data within the application process, or referencing some existing file, media or information. More...

std::vector< EntityReference >	register_ (const EntityReferences &entityReferences, const trait::TraitsDatas &entityTraitsDatas, access::PublishingAccess publishingAccess, const ContextConstPtr &context, const BatchElementErrorPolicyTag::Exception &errorPolicyTag={})
	Register should be used to 'publish' new entities either when originating new data within the application process, or referencing some existing file, media or information. More...

std::vector< std::variant< errors::BatchElementError, EntityReference > >	register_ (const EntityReferences &entityReferences, const trait::TraitsDatas &entityTraitsDatas, access::PublishingAccess publishingAccess, const ContextConstPtr &context, const BatchElementErrorPolicyTag::Variant &errorPolicyTag)
	Register should be used to 'publish' new entities either when originating new data within the application process, or referencing some existing file, media or information. More...

Detailed Description

The Manager is the Host facing representation of an Asset Management System.

The Manager class shouldn't be directly constructed by the host. An instance of the class for any given asset management system can be retrieved from a ManagerFactory, using the ManagerFactory.createManager() method with an appropriate manager identifier.

factory = openassetio.hostApi.ManagerFactory(
    hostImpl, consoleLogger, pluginFactory)
manager = factory.createManager("org.openassetio.test.manager")

A Manager instance is the single point of interaction with an asset management system. It provides methods to uniquely identify the underlying implementation, querying and resolving entity references and publishing new data.

The Manager API is threadsafe and can be called from multiple threads concurrently.

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 will be called for errors that are specific to a particular reference in a batch. Exceptions can be thrown to indicate a whole-batch error.

The appropriate error code should be used for these errors. See ErrorCode.

using ConstPtr = ManagerConstPtr

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 = ManagerPtr

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, EntityReferencePagerPtr)>

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.

Enumerator
kStatefulContexts	Manager makes use of the context to persist custom state for performance reasons or otherwise. Note If this capability is true, then the host must reuse the same context across related API calls (including the use of persistenceTokenForContext when the calls are distributed cross-process). 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

Member Function Documentation

ContextPtr contextFromPersistenceToken ( const Str & token )

Returns a Context linked to a previous manager state, based on the supplied persistence token derived from persistenceTokenForContext.

This context, when used with API methods will be considered part of the same logical series of actions.

Parameters

token A token previously returned from persistenceTokenForContext by this manager.

Returns: A context that will be associated with the same logical group of actions as the context supplied to persistenceTokenForContext to generate the token.

Warning: The context's access or locale is not restored by this action.

See also: Stable Entity Resolution

Exceptions

errors.NotImplementedException Thrown when this method is not implemented by the manager. Check that this method is implemented before use by calling hasCapability with Capability::kStatefulContexts.

See also: Capability::kStatefulContexts

Todo:: Should we concatenate the manager id in persistenceTokenForContext so we can verify that they match?

ContextPtr createChildContext ( const ContextPtr & parentContext )

Creates a child Context for use with the manager.

The new context will have the same configuration as the parent and be considered to be part of the same logical group, but may be modified independently. Useful when performing multiple operations in parallel.

Note: The locale is deep-copied so that the child's locale can be freely modified without affecting the parent.

Warning: Contexts should never be directly constructed, always use this method or createContext to create a new one.

Parameters

parentContext The new context will clone the supplied Context, and the Manager will be given a chance to migrate any meaningful state etc... This can be useful when certain UI elements need to 'take a copy' of a context in its current state in order to parallelise actions that are part of the same logical group, but have different locales or access.

See also: createContext; Context

ContextPtr createContext ( )

Creates a new Context for use with the manager.

The locale will be initialized with an empty TraitsData instance.

Warning: Contexts should never be directly constructed, always use this method or createChildContext to create a new one.

See also: createChildContext; Context

EntityReference createEntityReference ( Str entityReferenceString )

Create an EntityReference object wrapping a given Entity Reference string.

First validates that the given entity reference string is meaningful for this manager via isEntityReferenceString, throwing a std::domain_error if not.

Parameters

entityReferenceString Raw string representation of the entity reference. Taken by value to enable move semantics, on the assumption that an invalid entity reference is a rare case.

Returns: Validated entity reference object.

Exceptions

errors::InputValidationException If the given string is not recognized as an entity reference by this manager.

Todo:: Use a custom exception type rather than std::domain_error.

std::optional<EntityReference> createEntityReferenceIfValid ( Str entityReferenceString )

Create an EntityReference object wrapping a given Entity Reference string, if it is valid according to isEntityReferenceString.

See also: createEntityReference

Parameters

entityReferenceString Raw string representation of the entity reference. Taken by value to enable move semantics, on the assumption that an invalid entity reference is a rare case.

Returns: std::optional containing an EntityReference value if valid, not containing a value otherwise.

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

Called to determine an EntityReference considered to be a sensible default for each of the given entity 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.

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.
successCallback	Callback that will be called for each successful default retrieved for each of the given sets in `traitSets`. It will 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 available default entity reference, then the `optional` entity reference will not contain a value. The callback will be called on the same thread that initiated the call to `defaultEntityReference`.
errorCallback	Callback that will be called for each failure to retrieve a sensible default entity reference. It will be given the corresponding index for each of the given sets in `traitSets` along with a populated BatchElementError (see ErrorCodes). The kEntityAccessError error will be used if no suitable default reference exists, and the kInvalidTraitSet error will be used if the requested trait set is not recognised by the manager. The callback will be called on the same thread that initiated the call to `defaultEntityReference`.

Exceptions

errors.NotImplementedException Thrown when this method is not implemented by the manager. Check that this method is implemented before use by calling hasCapability with Capability::kDefaultEntityReferences.

See also: Capability::kDefaultEntityReferences

Str displayName ( ) const

Returns a human readable name to be used to reference this specific asset manager in user-facing displays.

For example:

"OpenAssetIO Test Manager"

void entityExists	(	const EntityReferences &	entityReferences,
		const ContextConstPtr &	context,
		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.

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 should be well-configured as it 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.
successCallback	Callback that will be called for each successful check of an entity reference. It will be given the corresponding index of the entity reference in `entityReferences` along with a boolean indicating existence, as defined above. The callback will be called on the same thread that initiated the call to `entityExists`.
errorCallback	Callback that will be called for each failed check of an entity reference. It will be given the corresponding index of the entity reference in `entityReferences` along with a populated BatchElementError (see ErrorCodes). The callback will be called on the same thread that initiated the call to `entityExists`.

Exceptions

errors.NotImplementedException Thrown when this method is not implemented by the manager. Check that this method is implemented before use by calling hasCapability with Capability::kExistenceQueries.

See also: Capability::kExistenceQueries

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

virtual

Retrieve the Trait Set of one or more entities.

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

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

If kRead is given, the response will be an exhaustive trait set for the entity. This may also include traits whose properties the manager is not capable of resolving, in order to aid categorisation. If an entity does not exist, then the error callback will be invoked using the kEntityResolutionError code.

If kWrite is given, the response will be the minimal trait set required to categorize the entity during publishing. This may include traits whose properties the manager is not capable of persisting. If an entity is read-only, the error callback will be invoked using the kEntityAccessError code.

Since the trait set will include all relevant traits for the access mode, not just those with properties that the manager can supply/store, call managementPolicy to determine which of those 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 intended usage of the data.
context	The calling context.
successCallback	Callback that will be called for each trait set retrieved for the entity references. It will be given the corresponding index of the entity reference in `entityReferences` along with its Trait Set. The callback will be called on the same thread that initiated the call to `entityTraits`.
errorCallback	Callback that will be called for each failure. It will be given the corresponding index of the entity reference in `entityReferences` along with a populated BatchElementError (see ErrorCodes). The callback will be called on the same thread that initiated the call to `entityTraits`.

trait::TraitSet entityTraits	(	const EntityReference &	entityReference,
		access::EntityTraitsAccess	entityTraitsAccess,
		const ContextConstPtr &	context,
		const BatchElementErrorPolicyTag::Exception &	errorPolicyTag = `{}`
	)

Retrieve the Trait Set of an entity.

See documentation for the callback variation for more details on resolution behaviour.

Errors that occur will be thrown as an exception, either from the manager plugin (for errors not specific to the entity reference) or as a BatchElementException-derived error.

Parameters

entityReference	Entity reference to query.
entityTraitsAccess	The intended usage of the data.
context	The calling context.
errorPolicyTag	Parameter for selecting the appropriate overload (tagged dispatch idiom). See BatchElementErrorPolicyTag::Exception.

Returns: Populated trait set.

Exceptions

errors.BatchElementException Converted exception thrown when the manager emits a BatchElementError.

std::variant<errors::BatchElementError, trait::TraitSet> entityTraits	(	const EntityReference &	entityReference,
		access::EntityTraitsAccess	entityTraitsAccess,
		const ContextConstPtr &	context,
		const BatchElementErrorPolicyTag::Variant &	errorPolicyTag
	)

Provides either a populated Trait Set or a BatchElementError.

If successful, the result is populated with the trait set of the entity.

Otherwise, the result is populated with an error object detailing the reason for the failure to retrieve the traits this particular entity.

Errors that are not specific to the entity being queried will be thrown as an exception.

See documentation for the callback variation for more details on resolution behaviour.

Parameters

entityReference	Entity reference to query.
entityTraitsAccess	The intended usage of the data.
context	The calling context.
errorPolicyTag	Parameter for selecting the appropriate overload (tagged dispatch idiom). See BatchElementErrorPolicyTag::Variant.

Returns: Object containing either the populated trait set or an error object.

std::vector<trait::TraitSet> entityTraits	(	const EntityReferences &	entityReferences,
		access::EntityTraitsAccess	entityTraitsAccess,
		const ContextConstPtr &	context,
		const BatchElementErrorPolicyTag::Exception &	errorPolicyTag = `{}`
	)

Retrieve the Trait Set of one or more entities.

See documentation for the callback variation for more details on resolution behaviour.

Any errors that occur will be immediately thrown as an exception, either from the manager plugin (for errors not specific to the entity reference) or as a BatchElementException-derived error.

Parameters

entityReferences	Entity references to query.
entityTraitsAccess	The intended usage of the data.
context	The calling context.
errorPolicyTag	Parameter for selecting the appropriate overload (tagged dispatch idiom). See BatchElementErrorPolicyTag::Exception.

Returns: List of populated trait sets.

Exceptions

errors.BatchElementException	Converted exception thrown when the manager emits a BatchElementError.
errors.NotImplementedException	Thrown when this method is not implemented by the manager. Check that this method is implemented before use by calling hasCapability with Capability::kResolution.

std::vector<std::variant<errors::BatchElementError, trait::TraitSet> > entityTraits	(	const EntityReferences &	entityReferences,
		access::EntityTraitsAccess	entityTraitsAccess,
		const ContextConstPtr &	context,
		const BatchElementErrorPolicyTag::Variant &	errorPolicyTag
	)

Provides either a populated Trait Set or a BatchElementError for each given Entity Reference.

For successful references, the corresponding element of the result is populated with its trait set.

Otherwise, the corresponding element of the result is populated with an error object detailing the reason for the failure to entityTraits that particular entity.

Errors that are not specific to an entity will be thrown as an exception, failing the whole batch.

See documentation for the callback variation for more details on resolution behaviour.

Parameters

entityReferences	Entity references to query.
entityTraitsAccess	The intended usage of the data.
context	The calling context.
errorPolicyTag	Parameter for selecting the appropriate overload (tag dispatch idiom). See BatchElementErrorPolicyTag::Variant.

Returns: List of objects, each containing either the populated trait set or an error.

void flushCaches ( )

Clears any internal caches.

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

void getWithRelationship	(	const EntityReferences &	entityReferences,
		const trait::TraitsDataPtr &	relationshipTraitsData,
		size_t	pageSize,
		access::RelationsAccess	relationsAccess,
		const ContextConstPtr &	context,
		const RelationshipQuerySuccessCallback &	successCallback,
		const BatchElementErrorCallback &	errorCallback,
		const trait::TraitSet &	resultTraitSet = `{}`
	)

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

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 considered meaningful.

If any relationship definition is unknown, then an empty list will be returned for that entity, and no errors will be raised.

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 is fixed for the lifetime of pager object given to the `successCallback`. Must be greater than zero.
relationsAccess	The intended usage of the returned references.
context	The calling context.
successCallback	Callback that will be called for each successful relationship query. It will 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`. If there are no relations, the pager will have no pages. The callback will be called on the same thread that initiated the call to `getWithRelationship`. To access the data, retrieve the EntityReferencePager from the callback, and use its interface to traverse pages.
errorCallback	Callback that will be called for each failed relationship query. It will be given the corresponding index of the entity reference in `entityReferences` along with a populated BatchElementError (see ErrorCodes). The callback will 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.InputValidationException	if `pageSize` is zero.
errors.NotImplementedException	Thrown when this method is not implemented by the manager. Check that this method is implemented before use by calling hasCapability with Capability::kRelationshipQueries.

See also: Capability::kRelationshipQueries

void getWithRelationships	(	const EntityReference &	entityReference,
		const trait::TraitsDatas &	relationshipTraitsDatas,
		size_t	pageSize,
		access::RelationsAccess	relationsAccess,
		const ContextConstPtr &	context,
		const RelationshipQuerySuccessCallback &	successCallback,
		const BatchElementErrorCallback &	errorCallback,
		const trait::TraitSet &	resultTraitSet = `{}`
	)

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

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 considered meaningful.

If any relationship definition is unknown, then an empty list will be returned for that relationship, and no errors will be raised.

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`. Must be greater than zero.
relationsAccess	The intended usage of the returned references.
context	The calling context.
successCallback	Callback that will be called for each successful relationship query. It will 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. If there are no relations, the pager will have no pages. The callback will be called on the same thread that initiated the call to `getWithRelationships`. To access the data, retrieve the EntityReferencePager from the callback, and use its interface to traverse pages.
errorCallback	Callback that will be called for each failed relationship query. It will be given the corresponding index of the relationship in `relationshipTraitsDatas` along with a populated BatchElementError (see ErrorCodes). The callback will 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.InputValidationException	if `pageSize` is zero.
errors.NotImplementedException	Thrown when this method is not implemented by the manager. Check that this method is implemented before use by calling hasCapability with Capability::kRelationshipQueries.

See also: Capability::kRelationshipQueries

bool hasCapability ( Capability capability )

Query the manager as to which capabilities it implements.

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

Support for each of these capabilities is optional for the manger, and the default implementation will throw a NotImplementedException.

This method can be called after initialize to determine whether a manager supports a given capability. It's a low-overhead call, whose return value remains constant once the manager has been initialized.

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.

Identifier identifier ( ) const

Returns an identifier to uniquely identify the Manager.

This identifier is used with the ManagerFactory to select which Manager to initialize, and so can be used in preferences etc to persist the chosen Manager. The identifier will use only alpha-numeric characters and '.', '_' or '-'. They generally follow the 'reverse-DNS' style, for example:

"org.openassetio.test.manager"

InfoDictionary info ( )

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 is no requirement to use any of the information in the info dict, but it may be useful for optimisations or display customisation.

There are certain well-known keys that may be set by the Manager. They include things such as openassetio.constants.kInfoKey_EntityReferencesMatchPrefix.

void initialize ( InfoDictionary managerSettings )

Prepares the Manager for interaction with a host.

In order to provide light weight inspection of available Managers, initial construction must be cheap. However most system require some kind of handshake or back-end setup in order to make entity-related queries. As such, the initialize method is the instruction to the Manager to prepare itself for full interaction.

If an exception is raised by this call, its is safe to assume that a fatal error occurred, and this Asset Management System is not available, and should be retried later.

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.

The behavior of calling initialize() on an already initialized Manager is to re-initialize the manager with any updated settings that are provided. If an error was raised previously, then initialization will be re-attempted.

Note: This must be called prior to any entity-related calls or an Exception will be raised.; This method may block for extended periods of time.

bool isEntityReferenceString ( const Str & someString )

Warning: It is essential, as a host, that only valid references are supplied to Manager API calls. Before any reference is passed to any other methods of this class, they must first be validated through this method.

Determines if the supplied string (in its entirety) matches the pattern of an Entity Reference. It does not verify that it points to a valid entity in the system, simply that the pattern of the string is recognised by the manager.

If it returns true, the string is an Entity Reference and should be considered as a managed entity (or a future one). Consequently, it should be resolved before use. It also confirms that it can be passed to any other method that requires an Entity Reference.

If false, this manager should no longer be involved in actions relating to the string.

This function is useful for control flow where constructing an EntityReference object is not (yet) needed. For other situations, consider using createEntityReferenceIfValid instead, to validate and (potentially) return an EntityReference in a single call.

Parameters

someString str The string to be inspected.

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

Note: This call does not verify an entity exits, just that the format of the string is recognised. The call is notionally trivial and does not involve back-end system queries.

See also: entityExists; resolve

static ManagerPtr make	(	managerApi::ManagerInterfacePtr	managerInterface,
		managerApi::HostSessionPtr	hostSession
	)

static

Constructs a new Manager wrapping the supplied manager interface and host session.

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

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.

More specifically, depending on the policyAccess mode, the response can tell you

Whether the manager is capable of resolving or persisting a particular kind of entity at all.
Which specific traits can be resolved, for existing or future entities.
Which traits can be persisted when publishing.
Which traits must have their required properties filled for publishing to succeed.

This allows you to adapt application logic or user-facing behaviour accordingly.

This is an opt-in mechanism, such that if result is empty, then the manager does not handle entities with the supplied traits. In this situation, OpenAssetIO based functionality should be disabled in the host when processing data of that type, and traditional mechanisms used instead.

This is particularly relevant for data types that may generate large volumes of API requests, that can be avoided if the data in question is not managed by the manager, or it can't resolve a required trait. Policy is runtime invariant and so only needs to be checked once for any given set of inputs (which includes the Context and its locale).

When querying this API, each Trait Set should be composed of:

The trait set of the entity type in question. This is usually obtained from the relevant Specification.
For read usage, any additional traits with properties that you wish to resolve for that type of entity.
For publishing usage, any additional traits with properties that you wish to publish for that type of entity.

Along with the traits that describe the manager's desired interaction pattern (ones with the managementPolicy usage metadata), the resulting TraitsData will be imbued with (potentially a subset of) the requested traits, signalling the manager's capability or requirements for resolving/persisting their properties.

The meaning of the subset of traits in the response varies 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.

This method gives the global policy for how the manager wishes 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 retrieve data from the supplied trait::TraitsData instead of querying directly using string literals.; There is no requirement to call this method before any other API interaction, though it is strongly recommended to do so where such information enables high-level behavioural changes or optimisations that improve user experience.

Parameters

traitSets	The entity traits to query.
policyAccess	Intended operation type to perform on entities.
context	The calling context.

Returns: a TraitsData for each element in traitSets.

Str persistenceTokenForContext ( const ContextPtr & context )

Returns a serializable token that represents the supplied context's managerState, such that it can be persisted or distributed between processes to associate subsequent API usage with the supplied context.

Note: Using this within the same process to store a context for use with subsequent API calls or other threads is redundant. Retain the Context object directly in this situation.

The returned token can be passed to contextFromPersistenceToken for future API use in another session with the same manager.

Parameters

context The context to derive a persistence token for.

Returns: A persistence token that can be used with contextFromPersistenceToken to create a context associated with the same logical group of actions as the one supplied to this method.

Warning: This only encapsulates the logical identity of the Context, such that when restored, any API calls made using the resulting Context will be logically associated with the one supplied here. It does not encode the current locale or other propeties.

Exceptions

errors.NotImplementedException Thrown when this method is not implemented by the manager. Check that this method is implemented before use by calling hasCapability with Capability::kStatefulContexts.

See also: Capability::kStatefulContexts; Stable Entity Resolution

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

This call signals your intent as a host application to do some work to create data in relation to each supplied Entity Reference.

The entity does not need to exist yet (see Entity Reference) or it may be a parent entity that you are about to create a child of or some other similar relationship (it actually doesn't matter really, as this Entity Reference will ultimately have been determined by interaction with the Manager, and it will have returned you something meaningful).

It should be called before register_() if you are about to create media or write to files. If the file or data already exists, then preflight is not needed. It will return a working Entity Reference for each given entity, which can be resolved in order to determine a working path that the files should be written to.

This call is designed to allow sanity checking, placeholder creation or any other sundry preparatory actions to be carried out by the Manager. In the case of file-based entities, the Manager may even use this opportunity to switch to some temporary working path or some such.

Note: If the supplied trait data is missing traits or properties required by the manager for any input entity reference, then that element will error. See glossary entry for details.

The entityTraits method may be used to determine the minimal Trait Set required for publishing. Note that the manager may not persist all trait properties in the given set, they may be required solely for classification. See entityTraits docs for more information.

Warning: The working Entity Reference returned by this method should always be used in place of the original reference supplied to preflight for resolves prior to registration, and for the final call to register_ itself. See Publishing a File.

Parameters

entityReferences	The entity references to preflight prior to registration.
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 details.
publishingAccess	Whether to perform a generic write to an entity or to (explicitly) create arelated" entity.
context	The calling context.
successCallback	Callback that will be called for each successful preflight of an entity reference. It will be given the corresponding index of the entity reference in `entityReferences` along with an updated reference to use for future interactions as part of the publishing operation. The callback will be called on the same thread that initiated the call to `preflight`.
errorCallback	Callback that will be called for each failed preflight of an entity reference. It will be given the corresponding index of the entity reference in `entityReferences` along with a populated BatchElementError (see ErrorCodes). The callback will be called on the same thread that initiated the call to `preflight`.

See also: register_

Exceptions

errors.NotImplementedException Thrown when this method is not implemented by the manager. Check that this method is implemented before use by calling hasCapability with Capability::kPublishing.

See also: Capability::kPublishing

EntityReference preflight	(	const EntityReference &	entityReference,
		const trait::TraitsDataPtr &	traitsHint,
		access::PublishingAccess	publishingAccess,
		const ContextConstPtr &	context,
		const BatchElementErrorPolicyTag::Exception &	errorPolicyTag = `{}`
	)

This call signals your intent as a host application to do some work to create data in relation to a supplied Entity Reference.

See documentation for the callback variation for more details on preflight behaviour.

Any errors that occur during the preflight call will be immediately thrown as an exception, either from the manager plugin (for errors not specific to the entity reference) or as a BatchElementException-derived error.

Parameters

entityReference	The entity reference to preflight prior to registration.
traitsHint	Trait Set for the entity, determining the type of entity to publish, complete with any properties that can be provided at this time.
publishingAccess	Whether to perform a generic write to an entity or to (explicitly) create arelated" entity.
context	The calling context.
errorPolicyTag	Parameter for selecting the appropriate overload (tag dispatch idiom). See BatchElementErrorPolicyTag.

Returns: Updated reference to use for future interactions as part of the publishing operation

Exceptions

errors.BatchElementException	Converted exception thrown when the manager emits a BatchElementError.
errors.NotImplementedException	Thrown when this method is not implemented by the manager. Check that this method is implemented before use by calling hasCapability with Capability::kPublishing.

See also: Capability::kPublishing

std::variant<errors::BatchElementError, EntityReference> preflight	(	const EntityReference &	entityReference,
		const trait::TraitsDataPtr &	traitsHint,
		access::PublishingAccess	publishingAccess,
		const ContextConstPtr &	context,
		const BatchElementErrorPolicyTag::Variant &	errorPolicyTag
	)

This call signals your intent as a host application to do some work to create data in relation to a supplied Entity Reference.

See documentation for the callback variation for more details on preflight behaviour.

If successful, the result is populated with an updated reference for use in future interactions in the publishing operation.

Otherwise, the result is populated with an error object detailing the reason for the failure to preflight this particular entity.

Errors that are not specific to the entity will be thrown as an exception.

Parameters

entityReference	The entity reference to preflight prior to registration.
traitsHint	Trait Set for the entity, determining the type of entity to publish, complete with any properties that can be provided at this time.
publishingAccess	Whether to perform a generic write to an entity or to (explicitly) create arelated" entity.
context	The calling context.
errorPolicyTag	Parameter for selecting the appropriate overload (tag dispatch idiom). See BatchElementErrorPolicyTag.

Returns: Either an updated reference to use for future interactions as part of the publishing operation, or an error object detailing the reason for the failure of this particular entity.

Exceptions

errors.NotImplementedException Thrown when this method is not implemented by the manager. Check that this method is implemented before use by calling hasCapability with Capability::kPublishing.

See also: Capability::kPublishing

EntityReferences preflight	(	const EntityReferences &	entityReferences,
		const trait::TraitsDatas &	traitsHints,
		access::PublishingAccess	publishingAccess,
		const ContextConstPtr &	context,
		const BatchElementErrorPolicyTag::Exception &	errorPolicyTag = `{}`
	)

This call signals your intent as a host application to do some work to create data in relation to each supplied Entity Reference.

See documentation for the callback variation for more details on preflight behaviour.

Any errors that occur during the preflight call will be immediately thrown as an exception, either from the manager plugin (for errors not specific to an entity reference) or as a BatchElementException-derived error.

Parameters

entityReferences	The entity references to preflight prior to registration.
traitsHints	Trait Set for each entity, determining the type of entity to publish, complete with any properties that can be provided at this time.
publishingAccess	Whether to perform a generic write to an entity or to (explicitly) create arelated" entity.
context	The calling context. The same calling context is used for each entity reference.
errorPolicyTag	Parameter for selecting the appropriate overload (tag dispatch idiom). See BatchElementErrorPolicyTag.

Returns: Updated references to use for future interactions as part of the publishing operation

Exceptions

errors.BatchElementException	Converted exception thrown when the manager emits a BatchElementError.
errors.NotImplementedException	Thrown when this method is not implemented by the manager. Check that this method is implemented before use by calling hasCapability with Capability::kPublishing.

See also: Capability::kPublishing

std::vector<std::variant<errors::BatchElementError, EntityReference> > preflight	(	const EntityReferences &	entityReferences,
		const trait::TraitsDatas &	traitsHints,
		access::PublishingAccess	publishingAccess,
		const ContextConstPtr &	context,
		const BatchElementErrorPolicyTag::Variant &	errorPolicyTag
	)

This call signals your intent as a host application to do some work to create data in relation to each supplied Entity Reference.

See documentation for the callback variation for more details on preflight behaviour.

For successful references, the corresponding element of the result is populated with an updated reference for use in future interactions in the publishing operation.

Otherwise, the corresponding element of the result is populated with an error object detailing the reason for the failure to preflight that particular entity.

Errors that are not specific to an entity will be thrown as an exception.

Parameters

entityReferences	The entity references to preflight prior to registration.
traitsHints	Trait Set for each entity, determining the type of entity to publish, complete with any properties that can be provided at this time.
publishingAccess	Whether to perform a generic write to an entity or to (explicitly) create arelated" entity.
context	The calling context. The same calling context is used for each entity reference.
errorPolicyTag	Parameter for selecting the appropriate overload (tag dispatch idiom). See BatchElementErrorPolicyTag.

Returns: A list where each element is either an updated reference to use for future interactions as part of the publishing operation, or an error object detailing the reason for the failure of that particular entity.

Exceptions

errors.NotImplementedException Thrown when this method is not implemented by the manager. Check that this method is implemented before use by calling hasCapability with Capability::kPublishing.

See also: Capability::kPublishing

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

Register should be used to 'publish' new entities either when originating new data within the application process, or referencing some existing file, media or information.

Note: The registration call is applicable to all kinds of Manager (path managing, or librarian), as long as it includes a suitable trait in the response to managementPolicy for the traits of the entities you are intending to register. Otherwise, the Manager is saying it doesn't handle entities with those traits, and it should not be registered.

Warning: The list of supported traits a manager returns in its managementPolicy response may be a subset of the trait set you requested. This means that when data is registered, only property values for those specific traits will be persisted, the rest will be ignored. The full Trait Set will always be stored though, to facilitate future identification.

The entityTraits method may be used to determine the minimal Trait Set required for publishing. Note that the manager may not persist all trait properties in the given set, they may be required solely for classification. See entityTraits docs for more information.

As each Entity Reference has (ultimately) come from the manager (either in response to delegation of UI/etc... or as a return from another call), then it can be assumed that the Manager will understand what it means for you to call register on this reference with the supplied TraitsData. The conceptual meaning of the call is:

"I have this reference you gave me, and I would like to register a new entity to it with the traits I told you about before. I trust that this is ok, and you will give me back the reference that represents the result of this."

It is up to the manager to understand the correct result for the particular trait set in relation to this reference. For example, if you received this reference in response to browsing for a target to kWrite and the traits of a ShotSpecification, then the Manager should have returned you a reference that you can then register a ShotSpecification entity to without error. The resulting entity reference should then reference the newly created Shot.

Warning: When registering traits that contain URLs or file paths (for example the MediaCreation LocatableContent trait), it should never be assumed that the resulting Entity Reference will resolve to the same path. Managers may freely relocate, copy, move or rename data as part of registration. Data for other trait properties may also change if the entity has been otherwise modified by some other interaction with the manager.

Parameters

entityReferences	Entity references to register to.
entityTraitsDatas	The data to register for each entity. NOTE: All supplied instances should have the same trait set, batching with varying traits is not supported.
publishingAccess	Whether to perform a generic write to an entity or to (explicitly) create arelated" entity. Note that if the `entityReference` came from a preflight call, then kWrite is the only valid value here.
context	Context The calling context.
successCallback	Callback that will be called for each successful registration of an entity reference. It will be given the corresponding index of the entity reference in `entityReferences` along with an updated reference to use for future interactions with the resulting new entity. The callback will be called on the same thread that initiated the call to `register`.
errorCallback	Callback that will be called for each failed registration of an entity reference. It will be given the corresponding index of the entity reference in `entityReferences` along with a populated BatchElementError (see ErrorCodes). The callback will be called on the same thread that initiated the call to `register`.

Exceptions

std::out_of_range	If `entityReferences` and `entityTraitsDatas` are not lists of the same length. Other exceptions may be raised for fatal runtime errors, for example server communication failure.
errors.NotImplementedException	Thrown when this method is not implemented by the manager. Check that this method is implemented before use by calling hasCapability with Capability::kPublishing.

See also: TraitsData; preflight; Capability::kPublishing

EntityReference register_	(	const EntityReference &	entityReference,
		const trait::TraitsDataPtr &	entityTraitsData,
		access::PublishingAccess	publishingAccess,
		const ContextConstPtr &	context,
		const BatchElementErrorPolicyTag::Exception &	errorPolicyTag = `{}`
	)

Register should be used to 'publish' new entities either when originating new data within the application process, or referencing some existing file, media or information.

See documentation for the callback variation for more details on register_ behaviour.

Any errors that occur during the register_ call will be immediately thrown as an exception, either from the manager plugin (for errors not specific to the entity reference) or as a BatchElementException-derived error.

Parameters

entityReference	Entity reference to register to.
entityTraitsData	The data to register for the entity.
publishingAccess	Whether to perform a generic write to an entity or to (explicitly) create arelated" entity. Note that if the `entityReference` came from a preflight call, then kWrite is the only valid value here.
context	Context The calling context.
errorPolicyTag	Parameter for selecting the appropriate overload (tag dispatch idiom). See BatchElementErrorPolicyTag.

Returns: Updated reference to use for future interactions with the resulting new entity.

Exceptions

errors.BatchElementException	Converted exception thrown when the manager emits a BatchElementError.
errors.NotImplementedException	Thrown when this method is not implemented by the manager. Check that this method is implemented before use by calling hasCapability with Capability::kPublishing.

See also: Capability::kPublishing

std::variant<errors::BatchElementError, EntityReference> register_	(	const EntityReference &	entityReference,
		const trait::TraitsDataPtr &	entityTraitsData,
		access::PublishingAccess	publishingAccess,
		const ContextConstPtr &	context,
		const BatchElementErrorPolicyTag::Variant &	errorPolicyTag
	)

Register should be used to 'publish' new entities either when originating new data within the application process, or referencing some existing file, media or information.

See documentation for the callback variation for more details on register_ behaviour.

If successful, the result is populated with an updated reference for use in future interactions with the resulting new entity

Otherwise, the result is populated with an error object detailing the reason for the failure to register this particular entity.

Errors that are not specific to the entity will be thrown as an exception.

Parameters

entityReference	Entity reference to register to.
entityTraitsData	The data to register for the entity.
publishingAccess	Whether to perform a generic write to an entity or to (explicitly) create arelated" entity. Note that if the `entityReference` came from a preflight call, then kWrite is the only valid value here.
context	Context The calling context.
errorPolicyTag	Parameter for selecting the appropriate overload (tag dispatch idiom). See BatchElementErrorPolicyTag.

Returns: Updated reference to use for future interactions with the resulting new entity or an error object detailing the reason for the failure of this particular entity.

Exceptions

errors.NotImplementedException Thrown when this method is not implemented by the manager. Check that this method is implemented before use by calling hasCapability with Capability::kPublishing.

See also: Capability::kPublishing

std::vector<EntityReference> register_	(	const EntityReferences &	entityReferences,
		const trait::TraitsDatas &	entityTraitsDatas,
		access::PublishingAccess	publishingAccess,
		const ContextConstPtr &	context,
		const BatchElementErrorPolicyTag::Exception &	errorPolicyTag = `{}`
	)

Register should be used to 'publish' new entities either when originating new data within the application process, or referencing some existing file, media or information.

See documentation for the callback variation for more details on register_ behaviour.

Any errors that occur during the register_ call will be immediately thrown as an exception, either from the manager plugin (for errors not specific to the entity reference) or as a BatchElementException-derived error.

Parameters

entityReferences	Entity references to register to.
entityTraitsDatas	The data to register for each entity. NOTE: All supplied instances should have the same trait set, batching with varying traits is not supported.
publishingAccess	Whether to perform a generic write to an entity or to (explicitly) create arelated" entity. Note that if the `entityReference` came from a preflight call, then kWrite is the only valid value here.
context	Context The calling context.
errorPolicyTag	Parameter for selecting the appropriate overload (tag dispatch idiom). See BatchElementErrorPolicyTag.

Returns: Updated references to use for future interactions with the resulting new entities.

Exceptions

errors.BatchElementException	Converted exception thrown when the manager emits a BatchElementError.
errors.NotImplementedException	Thrown when this method is not implemented by the manager. Check that this method is implemented before use by calling hasCapability with Capability::kPublishing.

See also: Capability::kPublishing

std::vector<std::variant<errors::BatchElementError, EntityReference> > register_	(	const EntityReferences &	entityReferences,
		const trait::TraitsDatas &	entityTraitsDatas,
		access::PublishingAccess	publishingAccess,
		const ContextConstPtr &	context,
		const BatchElementErrorPolicyTag::Variant &	errorPolicyTag
	)

Register should be used to 'publish' new entities either when originating new data within the application process, or referencing some existing file, media or information.

See documentation for the callback variation for more details on register_ behaviour.

For successful references, the corresponding element of the result is populated with an updated reference for use in future interactions with the resulting new entity.

Otherwise, the corresponding element of the result is populated with an error object detailing the reason for the failure to register that particular entity.

Errors that are not specific to the entity will be thrown as an exception.

Parameters

entityReferences	Entity references to register to.
entityTraitsDatas	The data to register for each entity. NOTE: All supplied instances should have the same trait set, batching with varying traits is not supported.
publishingAccess	Whether to perform a generic write to an entity or to (explicitly) create arelated" entity. Note that if the `entityReference` came from a preflight call, then kWrite is the only valid value here.
context	Context The calling context.
errorPolicyTag	Parameter for selecting the appropriate overload (tag dispatch idiom). See BatchElementErrorPolicyTag.

Returns: A list where each element is either an updated reference to use in future interactions with the resulting new entity, or an error object detailing the reason for the failure of that particular entity.

Exceptions

errors.NotImplementedException Thrown when this method is not implemented by the manager. Check that this method is implemented before use by calling hasCapability with Capability::kPublishing.

See also: Capability::kPublishing

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

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

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

Warning: Only traits that are applicable to each entity, and for which the manager has data, will be imbued in the result. See the documentation for each respective trait to determine 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. The managementPolicy query can be used ahead of time with a read Context to determine which specific traits any given manager supports resolving property data for.

To determine the Trait Set for a particular entity, use entityTraits. Note that this will give a complete trait set, including traits that solely aid classification and whose properties cannot be resolved. See the docs for entityTraits for more information.

Note: EntityReference objects must be constructed using either createEntityReference or createEntityReferenceIfValid. As a convenience, you may check if a string is a valid entity reference for the manager using isEntityReferenceString first.

Note that any properties that are defined as being a URL will be URL encoded. If it is expected that trait properties may contain substitution tokens or similar, their convention and behaviour will be defined in the documentation for the respective trait. Consult the originating project of the trait for more information.

There may be errors during resolution. These can either be exceptions thrown from resolve, or BatchElementErrors given to the errorCallback. Exceptions are unexpected errors that fail the whole batch. BatchElementErrors are errors that are specific to a particular entity - other entities may still resolve successfully. 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.

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

Parameters

entityReferences	Entity references to query.
traitSet	The trait IDs to resolve for the supplied list of entity references. Only traits applicable to the supplied entity references will be set in the resulting data.
resolveAccess	The intended usage of the data.
context	The calling context.
successCallback	Callback that will be called for each successful resolution of an entity reference. It will be given the corresponding index of the entity reference in `entityReferences` along with its `TraitsData`. The callback will be called on the same thread that initiated the call to `resolve`.
errorCallback	Callback that will be called for each failed resolution of an entity reference. It will be given the corresponding index of the entity reference in `entityReferences` along with a populated BatchElementError (see ErrorCodes). The callback will be called on the same thread that initiated the call to `resolve`.

Exceptions

errors.NotImplementedException Thrown when this method is not implemented by the manager. Check that this method is implemented before use by calling hasCapability with Capability::kResolution.

See also: Capability::kResolution

trait::TraitsDataPtr resolve	(	const EntityReference &	entityReference,
		const trait::TraitSet &	traitSet,
		access::ResolveAccess	resolveAccess,
		const ContextConstPtr &	context,
		const BatchElementErrorPolicyTag::Exception &	errorPolicyTag = `{}`
	)

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

See documentation for the callback variation for more details on resolution behaviour.

Errors that occur during resolution will be thrown as an exception, either from the manager plugin (for errors not specific to the entity reference) or as a BatchElementException-derived error.

Parameters

entityReference	Entity reference to query.
traitSet	The trait IDs to resolve for the supplied entity reference. Only traits applicable to the supplied entity reference will be set in the resulting data.
resolveAccess	The intended usage of the data.
context	The calling context.
errorPolicyTag	Parameter for selecting the appropriate overload (tagged dispatch idiom). See BatchElementErrorPolicyTag::Exception.

Returns: Populated data.

Exceptions

errors.BatchElementException	Converted exception thrown when the manager emits a BatchElementError.
errors.NotImplementedException	Thrown when this method is not implemented by the manager. Check that this method is implemented before use by calling hasCapability with Capability::kResolution.

See also: Capability::kResolution

std::variant<errors::BatchElementError, trait::TraitsDataPtr> resolve	(	const EntityReference &	entityReference,
		const trait::TraitSet &	traitSet,
		access::ResolveAccess	resolveAccess,
		const ContextConstPtr &	context,
		const BatchElementErrorPolicyTag::Variant &	errorPolicyTag
	)

Provides either a populated TraitsData or a BatchElementError.

If successful, the result is populated with the available data for the requested set of traits for the given Entity Reference.

Otherwise, the result is populated with an error object detailing the reason for the failure to resolve this particular entity.

Errors that are not specific to the entity being resolved will be thrown as an exception.

See documentation for the callback variation for more details on resolution behaviour.

Parameters

entityReference	Entity reference to query.
traitSet	The trait IDs to resolve for the supplied entity reference. Only traits applicable to the supplied entity reference will be set in the resulting data.
resolveAccess	The intended usage of the data.
context	The calling context.
errorPolicyTag	Parameter for selecting the appropriate overload (tagged dispatch idiom). See BatchElementErrorPolicyTag::Variant.

Returns: Object containing either the populated data or an error object.

Exceptions

errors.NotImplementedException Thrown when this method is not implemented by the manager. Check that this method is implemented before use by calling hasCapability with Capability::kResolution.

See also: Capability::kResolution

std::vector<trait::TraitsDataPtr> resolve	(	const EntityReferences &	entityReferences,
		const trait::TraitSet &	traitSet,
		access::ResolveAccess	resolveAccess,
		const ContextConstPtr &	context,
		const BatchElementErrorPolicyTag::Exception &	errorPolicyTag = `{}`
	)

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

See documentation for the callback variation for more details on resolution behaviour.

Any errors that occur during resolution will be immediately thrown as an exception, either from the manager plugin (for errors not specific to the entity reference) or as a BatchElementException-derived error.

Parameters

entityReferences	Entity references to query.
traitSet	The trait IDs to resolve for the supplied list of entity references. Only traits applicable to the supplied entity references will be set in the resulting data.
resolveAccess	The intended usage of the data.
context	The calling context.
errorPolicyTag	Parameter for selecting the appropriate overload (tagged dispatch idiom). See BatchElementErrorPolicyTag::Exception.

Returns: List of populated data objects.

Exceptions

errors.BatchElementException	Converted exception thrown when the manager emits a BatchElementError.
errors.NotImplementedException	Thrown when this method is not implemented by the manager. Check that this method is implemented before use by calling hasCapability with Capability::kResolution.

See also: Capability::kResolution

std::vector<std::variant<errors::BatchElementError, trait::TraitsDataPtr> > resolve	(	const EntityReferences &	entityReferences,
		const trait::TraitSet &	traitSet,
		access::ResolveAccess	resolveAccess,
		const ContextConstPtr &	context,
		const BatchElementErrorPolicyTag::Variant &	errorPolicyTag
	)

Provides either a populated TraitsData or a BatchElementError for each given Entity Reference.

For successful references, the corresponding element of the result is populated with the available data for the requested set of traits.

Otherwise, the corresponding element of the result is populated with an error object detailing the reason for the failure to resolve that particular entity.

Errors that are not specific to an entity will be thrown as an exception, failing the whole batch.

See documentation for the callback variation for more details on resolution behaviour.

Parameters

entityReferences	Entity references to query.
traitSet	The trait IDs to resolve for the supplied list of entity references. Only traits applicable to the supplied entity references will be set in the resulting data.
resolveAccess	The intended usage of the data.
context	The calling context.
errorPolicyTag	Parameter for selecting the appropriate overload (tag dispatch idiom). See BatchElementErrorPolicyTag::Variant.

Returns: List of objects, each containing either the populated data or an error.

Exceptions

errors.NotImplementedException Thrown when this method is not implemented by the manager. Check that this method is implemented before use by calling hasCapability with Capability::kResolution.

See also: Capability::kResolution

InfoDictionary settings ( )

Todo:: Document settings mechanism

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

Some managers may not have any settings, so this function will return an empty dictionary.

StrMap updateTerminology ( StrMap terms )

This call gives the Manager a chance to customize certain strings that you might want to use in your UI/messages.

See terminology for well-known keys. These keys are updated in the returned map to the most appropriate term for the Manager. You should then use these substitutions in any user-facing messages or display text so that they feel at home.

It's rare that you need to call this method directly, the openassetio.hostApi.terminology API provides more utility for far less effort.

See also: terminology; Mapper.replaceTerms; terminology.defaultTerminology

Parameters

terms Map of terms to be substituted by the manager.

Returns: Substituted map of terms.

Exceptions

errors.NotImplementedException Thrown when this method is not implemented by the manager. Check that this method is implemented before use by calling hasCapability with Capability::kCustomTerminology.

See also: Capability::kCustomTerminology

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

/src/src/openassetio-core/include/openassetio/hostApi/Manager.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Asset Management System Information

Entity Reference Inspection

Entity Resolution

Related Entities

Publishing

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Member Function Documentation