File Resolution

Update:  There is a great video explaining the end-user experience of this feature.  Contine reading for the technical details that make this feature possible.

File Associations have gone through some changes for Vault 2012.  Most of the changes are around a new feature which I will refer to as File Resolution.  Basically, the feature is about fixing up broken file references if a file is moved or renamed.

To enable this feature, we needed to add extra meta-data to file associations.  This meta-data is used to A) detect when a reference is broken and B) provide information necessary to fix the reference.

The first change you will notice is that AddFile and CheckinFile methods are different.  Instead of passing in 4 parameters (dependFileIds, dependSources, attachFileIds, attachSources) related to file associations, there is now only 1 parameter (associations). 

The association parameter is an array of FileAssocParam objects.  The FileAssocParam class contains the child file ID, the source meta data and the association type (attachment or dependency).  So it contains all the information from before, just in a different form.  The new pieces of information are the RefId and the ExpectedVaultPath properties. 

RefId is metadata indicating how to locate the reference within the parent file.  This data is file-type specific and is not something you want to set yourself.  The CAD plug-in will set this up when files are added in.  If you are doing an update, you need to re-specify the associations at check in, so just pass in the RefIds from the associations on the previous version.

ExpectedVaultPath is the vault location of the child file.  This piece is used to detect when moves or renames happen.  The word expected is there because you can never be 100% sure of that location.  Because Vault is a multi-user environment, it's possible that someone else renamed that child right before you do yout check-in.  The system is architected so that you don't need to know the exact path at the moment of check-in.  You just need to know the path that the parent is expecting the child to be in.  The File Resolve framework will do the rest.

If you are reading file associations on existing file, there some new parameters on FileAssoc.  The ExpectedVaultPath shows up here.  There is also a new property called VaultPathChanged.  This property is a boolean that indicates that broken reference has been found.  If the current Vault path is not equal to the expected Vault path for either the parent or the child, the value will be TRUE. 

When broken references are detected, components called Resolvers are in charge of fixing up the references.  Resolvers run client-side and are file-type specific.  Currently we only have resolvers for AutoCAD, Inventor and Navisworks files.  All other files cannot participate in the file resolution feature.

A Resolver is not something you should be dealing with directly. The new utility Autodesk.Connectivity.Explorer.ExtensibilityTools.IExplorerUtil contains DownloadFile() functions that will do the download and run the Resolver.  However, the older function Autodesk.Connectivity.WebServices.DocumentService.DownloadFile() will not run the resolver.  The reason is that the WebServices DLL is about server communication, not client-side operations. 

If you used checksum in the past to locate files, that's no longer a good mechanism.  Because the files are modified client-side, the checksum will no longer match the Vault checksum.  So you need to use things like filename, path, and last modified date to match between local and Vault files.  If you feel you absolutely need checksum capability, let me know and I will find you a workaround.

The File Resolution feature is a difficult one to consume from an API standpoint, but the end user experience is a very positive one.  In earlier versions of vault it was very difficult for a user to move and rename files, especially if a file was used in many places.  Under the new model, files can be easily and quickly moved and renamed.