ftrack Perforce storage allows you to store and manage files and assets in the Perforce Helix Core version control system. It consists of a number of parts:
-
The storage scenario, for managing company-wide settings (e.g. Perforce server address and port) and configuring Connect to use the Perforce location
-
A simple GUI for user-based settings (i.e. selecting a workspace)
-
An action to create a new depot for an ftrack Project.
Prerequisites
This assumes you already have a Perforce Helix Core server setup and a user account created.
Setup
Head over to the ftrack Perforce technical documentation for installation.
Since the user settings plugin is active, it will attempt to write certain settings to a configuration file. If any of those settings are empty, it will launch a GUI to prompt the user to choose options to fill them in.
System settings > Media Management > Storage Scenario > Configure Storage Scenario
Enter the server name and port number. Indicate whether the Perforce connection should use SSL or TCP. Indicate whether to enforce one depot per project (further details and implications following).
Restart Connect to activate the new Storage Scenario and Location
Username and Workspace
We believe that many companies will use consistent usernames across applications. ftrack provides the ability to sync user accounts with gSuite or LDAP, and ftrack Enterprise also includes support for SAML. Accordingly, we will try to derive your Perforce username from your ftrack username. In the case of an email address, we will use the portion before the @ symbol.
The ftrack Perforce plugin will also try to detect your workspace by querying the Perforce server. In the event that you specify a workspace in use by another user, or that there are no workspaces matching your user and host, we will ask you for a root directory and create a new one.
Folder structure
The included PerforceStructure plugin borrows from the StandardStructure and DiskAccessor classes, building the final file path out of a root directory (in our case, the p4 workspace root), and a directory for each part of the project hierarchy (e.g., Project, Folder, AssetBuild, Component). Therefore a project hierarchy like this:
{project1}
{assets Folder}
{chars Folder}
{hero Asset Build}
{Task}
yields a filepath like this:
{root_directory}/{project1}/{assets}/{chars}/{hero}/{asset name}/{component name}.{extension}
Type Map
Different file types demand different handling in a version control system. From the basic different between text and binary files, to the subtle nuance of line endings, it's important to make sure Perforce is handling your files in the best way. We use the ftrack event system to populate the Perforce type map with some sensible defaults, but you are free to edit those, or add your own by editing the plugin, or responding to the events yourself.
Storing each Project in a separate depot
With a single depot, the default setup will put all files under the depot workspace root, and everything is great. However, in order to support easier archiving of projects, you can also use one depot per project. Instead of the default mapping:
//depot/... //workspace/...
You must incorporate one level of the on-disk representation of the project hierarchy:
//depot/... //workspace/...
//project1/... //workspace/project1/...
Now, the same path as above will map to our new depot, *project1*, while all other projects will still map to *depot*.
Validation
If the storage scenario is set to enforce one depot per project, Connect will validate the Perforce workspace at startup time. If there is a problem, a dialog like this will be raised:
You can correct these problems and restart Connect. Depending on the specific workspace and project settings, you may still be able to publish to some or all Projects even while errors are raised.
Publishing to Perforce
File publishing to the Perforce Location happens in a number of steps.
-
First, the workspace file is created in or checked out of Perforce as needed.
-
Then the new contents are written to the workspace file.
-
Next, the new ComponentLocation record is created in ftrack and an event is published.
-
Finally, in response to the event, the file is sync’d with the Perforce server.
Working with versions
Though not reflected in the web UI, each component has the Perforce version stored within its resource identifier, like so:
//{project1}/{assets}/{chars}/{hero}/{asset name}/{component name}.{extension}#{version}
When you use an ftrack asset manager to switch between versions, behind the scenes we use p4 sync to change which version of that file is on disk. Like many version control systems, Perforce operates by changing the contents of files on disk. Due to this, you can only work with a single version of a file at a time. For an example of the consequence of this Perforce behavior, changing the AssetVersion number of a read node in Nuke will affect every other file read using the same path.
It is possible that the version number of an AssetVersion in ftrack will not match the version number of the corresponding file in Perforce. If files are submitted to Perforce without going through the ftrack storage system, new versions can be created which do not correspond to any version of a Component known to ftrack. Similarly, because ftrack Perforce storage retrieves files based on the resource id associated with a Component on an AssetVersion, an ftrack asset manager will not be able to load these orphaned versions.
Helpful, but not required reading