Publish asset versions
Before you get into publishing via the API, please make sure you have a good understanding of the different ways to handle files and media in ftrack. Sure, here's a gradually built-out version of the mermaid diagram along with its textual explanation.
Files are represented as components in ftrack. Components can be associated with different entities in ftrack and represent thumbnails, attachments to notes, or files on published versions.
Here is a simple diagram with one component:
AssetVersions, also known as versions, are the main UI representation when publishing files to ftrack. An AssetVersion needs a parent entity that groups different versions together and forms an Asset. The Asset entity holds information about the versions, such as name and type.
Components are attached directly to the AssetVersion, and an AssetVersion can have zero, one or multiple components representing different files that belong to the same published version. This diagram shows a single component attached to an AssetVersion:
Now, adding another component to the AssetVersion:
The Asset entity should be attached to a Context. A context is either a Project or an object inheriting from the TypedContext, such as a shot, asset build, or folder.
A task represents the work that should be published but cannot be used as the parent of the Asset. Instead, the parent of the task should be used as the parent of the Asset. The task itself should be associated directly with the AssetVersion.
This completes the full diagram with the associations between files, versions, assets, tasks, and contexts.
When another version of the same asset is published, it should be created with the already existing asset as its parent.
Components
A components is the representation of a file, but only the metadata such as name, type, and size. The actual existence of the file is represented by a ComponentLocation which represents a certain file in a certain location.
When you publish a version, you also need to create the components and add the components to one or more locations which will make sure the file is transferred to its correct place and given its correct name. Often API clients have already been configured to automatically add components to the preferred location.
Here are some examples using the python client to publish versions.