OpenAssetIO
An abstract API for generalising interactions between a host application and an asset management system
|
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 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.
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.
For examples of how to correctly call these parts of the API within a host, see the Examples page.
| |
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... | |
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 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.
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.
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.
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.
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:
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.
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.
|
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.
This capability means the manager implements the following methods: |
kManagementPolicyQueries |
Manager can provide a policy describing its behaviour with regard to specific entity types and relationships.
This capability means the manager implements the following methods: |
kEntityTraitIntrospection |
Manager can be queried for the traits of a given entity.
This capability means the manager implements the following methods: |
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:
|
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: |
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: |
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: |
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: |
kExistenceQueries |
Manager is capable of confirming the existence of entities. This capability means the manager implements the following methods: |
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: |
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.
|
virtualdefault |
Polymorphic destructor.
|
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.
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'. |
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. |
|
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.
entityReferenceString | Raw string representation of the entity reference. |
|
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.
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. |
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. |
|
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.
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 . |
errors.NotImplementedException | by default when this method is not implemented by the manager. Implementations must therefore not invoke the base class implementation. |
|
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"
|
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.
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 . |
errors.NotImplementedException | by default when this method is not implemented by the manager. Implementations must therefore not invoke the base class implementation. |
|
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.
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 . |
errors.NotImplementedException | by default when this method is not implemented by the manager. Implementations must therefore not invoke the base class implementation. |
|
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.
hostSession | The API session. |
|
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.
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.
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
.
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. |
errors.NotImplementedException | by default when this method is not implemented by the manager. Implementations must therefore not invoke the base class implementation. |
|
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.
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.
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
.
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. |
errors.NotImplementedException | by default when this method is not implemented by the manager. Implementations must therefore not invoke the base class implementation. |
|
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,
capability | The capability to check. |
|
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"
|
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:
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.
|
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.
|
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.
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.
someString | str The string to be inspected. |
hostSession | HostSession The API session. |
bool
True
if the supplied string should be considered as an Entity Reference, False
if the pattern is not recognised.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. |
|
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.
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:
managementPolicy
usage metadata)The meaning of the subset of traits in the response should vary by policyAccess
mode as follows
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.
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.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. |
TraitsData
for each element in traitSets
.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. |
|
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.
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. |
|
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
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.
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. |
errors.NotImplementedException | by default when this method is not implemented by the manager. Implementations must therefore not invoke the base class implementation. |
|
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.
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.
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. |
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.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 . |
errors.NotImplementedException | by default when this method is not implemented by the manager. Implementations must therefore not invoke the base class implementation. |
|
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.
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
.
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 . |
errors.NotImplementedException | by default when this method is not implemented by the manager. Implementations must therefore not invoke the base class implementation. |
|
virtual |
hostSession | The API session. |
The default implementation returns an empty dictionary.
|
virtual |
Restores the supplied state object to a previously persisted state.
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. |
|
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".
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. |
errors.NotImplementedException | by default when this method is not implemented by the manager. Implementations must therefore not invoke the base class implementation. |
|
static |
Mapping of ManagerCapability enum value to human-readable name.
Copyright 2013-2023 The Foundry Visionmongers Ltd. OpenAssetIO is released under the Apache 2.0 License