If you want to update a Vault property and that property is mapped to a value within the file, you have a couple of options, and they both suck. This post is to introduce a third, and non-sucky, option in Vault 2015 R2. Again, I’ll be using the previously undocumented functions from Copy Design.
Sucky option 1 is to checkout and download the CAD file. Next, use the appropriate CAD API to update the file on disk. Lastly, check the file back in to Vault. What makes this option so difficult is that you need to involve the CAD API. It would be nice to do just everything from within the Vault API.
Sucky option 2 is to use IExplorerUtil.UpdateFileProperties in the Vault API. On paper, this is a great function. It loads up core pieces of Vault Explorer libraries and executes the Edit Properties command just as if a user had done it through the UI. It even handles the checkout/checkin. The problem is that it’s a bulky operation and prone to failure. Vault Explorer simply wasn’t meant to be invoked from the API. IExplorerUtil was always indented to be a temporary solution until something better came along. And that something better is here....
The new option is to use the Copy Design features. Similar to how you can ‘roll your own’ copy design, you can also run a property update without ever invoking a CAD API or downloading the file. It’s a 4 step process:
Step 1: Check out the file
This step reserves the file to you for editing. It also gives you a download ticket, which you will need in the next 2 steps. Although you are not actually downloading anything, the ticket is the currency that the FilestoreService uses.
Step 2: Read the property definitions from the file
This step interrogates the binary file and pulls out the names properties that you may be able to edit. Unfortunately, it doesn’t tell you the current values on those properties. Also keep in mind that this is the property as it appears in the file, which may not be the same name that it appears in Vault. In fact, it may not be mapped to a Vault property at all.
Step 3: Copy the binary contents file
This step will create a new binary blob of data in the Vault filestore. It also lets you update properties on that blob. The ‘writeReqs’ parameter let’s you pass in new values for the properties you discovered in part 2. Only properties you pass in are updated. All others are left with their existing value.
It’s possible that not all properties you supplied will get updated, so check the ‘writeResults’ out parameter for confirmation.
Step 4: Check-in the file
This steps ties the binary data in the filestore with actual records in the Vault database. Without this step, you just have a blob of data floating in limbo. Although you copied binary data, it won't be used for creating a new File Master like with copy design. Instead, you are creating a new version of an existing file. From the filestore’s point of view, there is no difference between the two. Both are just blobs of binary data.
You didn’t think I would go through all this without providing any sample code, did you? Not a chance. I actually have an mini app that illustrates this workflow and the a simple Copy Design workflow from the previous post. Includes C# and VB.NET source code. Enjoy.