It's All Just Ones and Zeros

Vault sample from AU 2018 class available online

Hello everyone, my name is Paul Gunn.

I'm a software architect on Vault and recently taught a class on the Vault 2019 API at Autodesk University 2018. Doug attended my class and graciously offered the opportunity to share this information with you as a guest blogger.

My class delved into new server APIs that provide (what we believe to be) new and powerful capabilities to developers. Here at Autodesk we have implemented a major client-side feature on this platform and other features in the pipe are similarly leveraging this functionality. The class downloads section includes the class handout and demo application ('material' zip file) - and a recording of the class is also available.

Here are resources available online:

General class information

Class downloads

Hope folks find this information useful!

Vault API Support

Please go to the Vault Customization discussion group if you have any questions about the Vault API.  Don’t use the comments section in this blog.

There are a few reasons for this: 

1. The discussion group is monitored by the Vault team and the Autodesk Developer Network.  So more people will see your question and respond.
2. The discussion group is better designed for highly-detailed questions.  You can have formatted text, code snippets, file attachments and so on.
3. Your question may have already been answered.  You can easily search the discussion group to see if there are similar issues.
4. I’m no longer on the Vault team.  I actually left about 2 years ago, so it’s getting hard for me to provide detailed help.

---

Project Thunderdome 2016 Source Code

We are still keeping Thunderdome open source for the 2016 release.  The app itself can be downloaded from Autodesk Exchange.  If you want the source code, it’s provided in the link below.

Click here for Project Thunderdome 2016 source code

Special thanks to Matt Smith from the Vault team for updating the app to Vault 2016.

---

Syncing Vault Properties for Property Equivalence

In prior posts, Doug introduced a couple undocumented methods in the Filestore Service and described how you could use them to roll your own copy design. In this installment, I’ll show you how to use them to sync up properties to get rid of property equivalence errors.

A vaulted file will have property equivalence errors if it needs to have property values written back to it.  This behavior is controlled by the write mappings in the property definitions. The errors mean that the property values in the vault database not matching the property values stored within the file. You can remedy this situation by doing a property sync in Vault Explorer, but that’s too easy – instead let’s do the property sync via the Vault 2016 API.

In the Document Service there is a rather obscure method called GetComponentProperties, whose description in the help reads: “Gets property data for a file which has been assigned to an item”. What this method really does (in 2015-R2 and beyond) is provide exactly what needs to be written back to a file in order for it to have property equivalence. And it isn’t limited to files that have been assigned to items – it works perfectly fine where no items are present (such as in Vault Workgroup or Vault Basic).

Since nothing is easy, there are a number of potential issues that we will need to work around. First of all, if you were to blindly take the property data from GetComponentProperties and feed it to CopyFile, you may notice datetimes shifting by your timezone offset; or numerical values shifting by orders of magnitude in locales where the thousandths separator is a period (“.”) and the decimal point is a comma (“,”). That is some serious badness that must be avoided. Also, we don’t want to create a new version of each file we sync if we didn’t actually do anything – that would be really annoying.

I have wrapped up everything that needs to happen to avoid these issues in a simple class (“PropertySync”) which just has a constructor and one method. The idea is to gather the files you want to do the sync for, construct the PropertySync object once and then call its SyncProperties method on each file. The reason for the two-step process is so it only needs to get property definitions once. Many more details are in the comments.

Click here for sample code (C#)

-- Dave Mink

Another Way to Update Properties

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
DocumentService.CheckoutFile(...)

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
FilestoreService.GetContentSourcePropertyDefinitions(...)

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
FilestoreService.CopyFile(...)

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
DocumentService.CheckinUploadedFile(...)

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.

---

Sample Code

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.

Click here to download

---

Roll Your Own Copy Design

Previously, I documented two new functions related to the new Copy Design app in Vault 2015 R2.  Now I would like to explore some uses for those functions.  The most obvious usage is to build your own Copy Design algorithm that meets your specific needs.

Technically, a custom Copy Design as always possible in Vault, but these new functions make things easier.  Most significantly, your app does not have to engage in any CAD-specific APIs.  Assuming, of course, the CAD file is one of the types that Vault recognizes. 

I said that the new functions make a custom Copy Design easier, but it’s still not something I would describe as simple.  You still have to manage things like file relationships, and file naming.

---

For each file you want to copy, you basically have to do three steps:

Step 1:  Get a download ticket.
DocumentService.GetDownloadTicketsByFileIds(...)

You are not actually downloading anything, but let’s not worry about that for the moment.  The important thing is that we are swapping the File Id for ticket, and the ticket is required in step 2. 

Step 2:  Copy the binary file contents.
FilestoreService.CopyFile(...)

This step will do a server-side copy of the file bits.  Nothing is actually download or uploaded from your computer.  The operation just does a copy of the binary data.  The meta data still has not been copied yet, so it doesn’t really exist in Vault.  It has no file name, no folder location, no create time, and so on.  It’s basically a set of data floating in limbo.

Step 3:  Add the file to Vault
DocumentService.AddUploadedFile(...)

This step is where you tell the Vault database about the file.  It’s here that you set the new name, new location, and new relationships for the copied file.  Again, the function name isn’t technically correct.  We didn’t upload the file, but this function doesn’t care.  It just needs an uploadTicket so that it can cement the binary data to the meta data.

---

Another key aspect of the copy is that the internal file relationships have not yet been modified.  Step 2 is a perfect copy, so it still has pointers to old file names.  Vault is designed so that file relationships are updated when the file is downloaded.  This is another reason you want to use AcquireFiles when downloading.  It fixes up the references for your local files.

The new copy design app works the same way.  It relies on download to fix up and broken references.  Those references will technically stay broken until an engineer checks out the files, makes changes and checks the files back in.

---

2 Undocumented Functions

There are some undocumented functions in Vault 2015 R2 I’d like to tell you about.  Of course, the process of me telling you about them essentially makes them documented.  So by the time you get to the bottom of this article, the title becomes untrue. 

Yes, I did get permission from the team before going public with this information.  So feel free to use the knowledge that I am about to impart upon you as long as you are in Vault 2015 R2.  In fact, I’ll be going into more details in the upcoming posts on how you can use these functions to do cool things.  But first, some background.

You know that new Copy Design app in 2015 R2?  It’s more than just a UI redesign.  There are some server side enhancements too.  Specifically the copy happens entirely on the server side.  Previously, the client would download all the files, copy them, modify the copies and upload them as new files.  The new mechanism saves network bandwidth and reduces the load on the client.  But in order to develop the new Copy Design client, some new server APIs needed to be made...

---

CopyFile

This function copies the binary contents of a file in the filestore.  The Vault meta data, such as Name and Version Number, are not copied.

byte[] FilestoreService.CopyFile (
    byte[] downloadTicket,
    bool allowSync,
    PropWriteReq[] writeReqs, 
    out PropWriteResults writeResults)

downloadTicket – The identifier to the file you want to copy. The FilestoreService doesn’t care about File.Id values. Download/upload tickets are the identifiers here.  Call DocumentService.GetDownloadTicketsByFileIds to get a download ticket.

allowSync – If true and the file is not on the local filestore, the file is copied as part of the operation. If false, the operation fails if the file is not in the local filestore.

writeReqs – A set of properties to update within the file. For example, you can update Inventor iProperties in the copied file.

writeResults – The result of the property updates.  Just because you requested a property change, doesn’t mead the change actually happened.

Return value – The upload ticket for the new file.

---

GetContentSourcePropertyDefinitions

This function gets you the list of property names contained within the file.  The CAD file is the source of the content.  This type of property is different than Vault properties, which are stored in the Vault database. 

CtntSrcPropDef[] FilestoreService.GetContentSourcePropertyDefinitions (
    byte[] downloadTicket,
    bool allowSync)

downloadTicket – The identifier for the file to read property names from. Call DocumentService.GetDownloadTicketsByFileIds to get a download ticket.

allowSync – If true and the file is not on the local filestore, the file is copied as part of the operation. If false, the operation fails if the file is not in the local filestore.

Return value – The properties that may be read from or written to in the file.

---

Changing the Item Lifecycle State

In the Vault 2015 R2 release, the old Item lifecycle engine was replaced with the entity-based engine used by Files and Folders.  The good news is that the entity-based engine is filled with awesome features to make your Items more useful.  The bad news is that you have to update your code.

If you already know how to change File Lifecycle States, then you pretty much know how to change Item Lifecycle States.  This article is geared mostly to those that use Items but are not familiar with the File/Folder lifecycle engine.

---

Step 1:  Figuring out the States and Transitions

In Vault 2015 and earlier, it was easy to know the possible Item states and transitions because they were hard coded.  There were only 4 states and they were all connected.  In 2015 R2, the administrator can define their own states and transitions.  They can even define multiple lifecycle definitions.  For example, one Item may be in the “Engineering Release Process” while another is in the “Document Approval Process”. 

So your app has to figure out what the states and transitions are.  The Item itself knows what Lifecycle State it is in.  But to get more context about the surrounding States you need to go to the LifeCycleService.  Not only can you find out about all the states and transitions, you can also update them if you have admin rights.

---

Step 2:  Updating the Item object

The LifeCycleService does everything at the Entity level.  If you want to modify the Item itself, you need to go to the ItemService.  When changing the state on an Item, you will use one of two functions...

UpdateItemLifeCycleStates is the function to use when moving an Item from one state to another within a lifecycle definition.  For example, when moving from “Released” to “Quick Change”.

UpdateItemLifeCycleDefinitions is the function to use when moving an Item to a different lifecycle entirely.  For example, when moving from “Flexible Release Process” to “Item Release Process”.

The nice thing about both functions is that they are one-shot functions.  No need to call EditItems prior or UpdateAndCommitItems afterward.  Everything happens in a single call.

---

Sample code:

Here is a quick sample app you can use to see how it all comes together.  Both C# and VB.NET code are included.

Click here to download

---

Updated Vault 2015 R2 SDK

Many of you doing development on Vault 2015 R2 have noticed some issues with the SDK.  For example, the What’s New page is for the 2015 release and there is no list of changes for 2015 R2.

Those issues should now be fixed.  Sorry for the inconvenience.  Please un-install your current Vault 2015 R2 SDK and install the fixed SDK: Vault_2015_R2_SDK-Fixed.zip

If you have questions about the Vault API, the best place to go is the Vault Customization discussion group.

---

Quick Change

I may be exaggerating slightly when I say that the Quick Change state on Items is the greatest invention mankind has ever or will ever achieve. The bad news is that it’s only available for Vault 2015 R2.  But that’s also a good thing, because once you start using it, there is no going back.  You are changed forever.

(click for full size image)

If you are wondering why I am so excited about the Quick Change state, then you probably have never tried programming with Items in the Vault.  In Vault 2015 and earlier, the lifecycle states are rigidly defined, which made it really difficult to perform operations on a Released item.  And 99% of the time, Released Items are the only type of Items your app cares about.

Take this scenario.  You are writing an app that pushes Item data to an ERP system automatically when an Item gets released.  You when the new entry gets created in the ERP system, you would like to save that ERP object ID on the Vault Item.  But Vault won't let you, it’s released, which means it’s read only.  Your app needs to find a way to move the Item to WIP without bumping the revision.  Then, it needs a way to move back to Released without triggering the update again.  It’s possible, but it’s a pain.

Quick change fixes all of that.  Your app can safely move in and out of the Released state without worrying about a revision bump.  The permissions are configurable, so you can guarantee that nobody will mess with the Item while your app is editing it.

Even outside the context of custom programming, Quick Change is useful.  If you are a Vault admin and you notice a small detail that needs fixing, you can, um, quickly change it.  Files have had the Quick Change state for years now.  It’s still highly useful for Files, but I think it will be even more useful for the Item world. 

When you upgrade to Vault 2015 R2, Quick Change is automatically added.  If, for some strange reason, you don’t want it, you can always just delete it from the Vault settings dialog.  If you hear loud sobbing while you delete it, that’s just me.  I hate to see a good lifecycle state die.

I’ll leave you with an clip from the movie Quick Change.  That's right, the Quick Change state is so awesome that Hollywood made a movie about it 24 years before it was invented.  If you are a Bill Murray fan and have not seen the move, then you are not actually a Bill Murray fan.

---