It's All Just Ones and Zeros

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

---