It's All Just Ones and Zeros

DevExpress DLLs

The Vault 2014 SDK contains a bunch of DLLs from a third-party vendor, DevExpress.  Autodesk and DevExpress entered into an agreement for usage and distribution of these DLLs in the Vault SDK.  Here is my understanding of that agreement.  Keep in mind that I do not represent the Autodesk legal department.

Background

The Vault 2014 API contains re-usable UI components, which make use of DevExpress controls.  Therefore those controls needed to be included in the Vault SDK.

The Agreement

The DevExpress DLLs in the Vault SDK (these are the ones in the bin folder that start with “DevExpress”) are free for you (the user of the Vault SDK) to use and re-distribute within the context of the Vault SDK. 

However, if you use the DevExpress controls directly, then you need to get a developer license from DevExpress.  Things like cost, and usage are between you and DevExpress.  Autodesk has no involvement.

If you try to make direct use of DevExpress controls without a license, you should see a pop-up in Visual Studio indicating unlicensed usage.

DevExpress website:  http://www.devexpress.com/

Examples

If you paste a VaultBrowserControl in your dialog, that’s free, even though VaultBrowserControl makes use of DevExpress controls internally.

If you paste a DevExpress.XtraGrid control in your dialog, you need a DevExpress developer license.

DLL Redistribution

The Vault Client installs all the needed DevExpress controls into the GAC.  So if your app requires the Vault Client, then you don’t need to re-distribute the DevExpress DLLs.  It’s only in cases where the user may not have the Vault Client that you need to worry about re-distributing the DLLs. 

Although the DLLs can go in the GAC, I recommend putting the DevExpress DLLs in the running folder.

Special Thanks

Thanks goes out to the people at DevExpress.  Not only did they let us include their DLLs in he Vault SDK, but they also make good controls.  Since the very first Vault release, the Vault client has been using DevExpress controls to great satisfaction.

How to Acquire Files

Downloading and checking-out is so last year.  The fashionable Vault API developer acquires their files.  It has more style and class.  Also, DocumentService.DownloadFile and DocumentService.CheckoutFile are no more in the 2014 API.  So that kind of forces the issue.  Connection.FileManager.AcquireFiles is the replacement.  I’ll go over the architectural reason for the change in a later article.

---

Benefits of AcquireFiles

Yes, it’s a pain to have to update your code, but let me go over the benefits before you get too distraught. 

• Downloads files to the working folder by default.
• Automatically handles large files.
• Automatically repairs broken references for known CAD file types.
• Can download entire assemblies in one call.
• Multi-thread download.  It’s about 2x quicker when downloading an assembly.
• Get/checkout dialog available.
• Automatically sets file attributes, such as read-only and create date.

The only disadvantage that I have come across is that you can’t read a file directly into memory.  You always acquire to a location on disk.  The workaround is to acquire to a temp location, read the file to memory, then delete the temp file.

---

Here is some sample code.

// C# using VDF = Autodesk.DataManagement.Client.Framework;   public void DownlodFiles(ICollection<VDF.Vault.Currency.Entities.FileIteration> fileIters) {     // download individual files to a temp location     VDF.Vault.Settings.AcquireFilesSettings settings =         new VDF.Vault.Settings.AcquireFilesSettings(m_conn);     settings.LocalPath = new VDF.Currency.FolderPathAbsolute(@"c:\temp");     foreach (VDF.Vault.Currency.Entities.FileIteration fileIter in fileIters)     {         settings.AddFileToAcquire(fileIter,             VDF.Vault.Settings.AcquireFilesSettings.AcquisitionOption.Download);     }       VDF.Vault.Results.AcquireFilesResults results = m_conn.FileManager.AcquireFiles(settings); }   public void DownloadAssembly(VDF.Vault.Currency.Entities.FileIteration topLevelAssembly) {     // download the latest version of the assembly to working folders     VDF.Vault.Settings.AcquireFilesSettings settings =         new VDF.Vault.Settings.AcquireFilesSettings(m_conn);     settings.OptionsRelationshipGathering.FileRelationshipSettings.IncludeChildren = true;     settings.OptionsRelationshipGathering.FileRelationshipSettings.RecurseChildren = true;     settings.OptionsRelationshipGathering.FileRelationshipSettings.VersionGatheringOption =         VDF.Vault.Currency.VersionGatheringOption.Latest;     settings.AddFileToAcquire(topLevelAssembly,         VDF.Vault.Settings.AcquireFilesSettings.AcquisitionOption.Download);       VDF.Vault.Results.AcquireFilesResults results =         m_conn.FileManager.AcquireFiles(settings); }   public void DownloadDialog(VDF.Vault.Currency.Entities.FileIteration fileIter,     IntPtr parentWindowHandle) {     // pop up the Get/Checkout dialog     VDF.Vault.Forms.Settings.InteractiveAcquireFileSettings settings =         new VDF.Vault.Forms.Settings.InteractiveAcquireFileSettings(             m_conn, parentWindowHandle, "Download files");     settings.AddEntityToAcquire(fileIter);       VDF.Vault.Forms.Library.AcquireFiles(settings); }

' VB Imports VDF = Autodesk.DataManagement.Client.Framework   Public Sub DownlodFiles(fileIters As ICollection(Of VDF.Vault.Currency.Entities.FileIteration))        ' download individual files to a temp location        Dim settings As New VDF.Vault.Settings.AcquireFilesSettings(m_conn)        settings.LocalPath = New VDF.Currency.FolderPathAbsolute("c:\temp")        For Each fileIter As VDF.Vault.Currency.Entities.FileIteration In fileIters               settings.AddFileToAcquire(fileIter, _ _                VDF.Vault.Settings.AcquireFilesSettings.AcquisitionOption.Download)        Next          Dim results As VDF.Vault.Results.AcquireFilesResults = _            m_conn.FileManager.AcquireFiles(settings) End Sub   Public Sub DownloadAssembly(topLevelAssembly As VDF.Vault.Currency.Entities.FileIteration)        ' download the latest version of the assembly to working folders        Dim settings As New VDF.Vault.Settings.AcquireFilesSettings(m_conn)     settings.OptionsRelationshipGathering.FileRelationshipSettings.IncludeChildren = True     settings.OptionsRelationshipGathering.FileRelationshipSettings.RecurseChildren = True     settings.OptionsRelationshipGathering.FileRelationshipSettings.VersionGatheringOption = _            VDF.Vault.Currency.VersionGatheringOption.Latest        settings.AddFileToAcquire(topLevelAssembly, _            VDF.Vault.Settings.AcquireFilesSettings.AcquisitionOption.Download)          Dim results As VDF.Vault.Results.AcquireFilesResults = _            m_conn.FileManager.AcquireFiles(settings) End Sub   Public Sub DownloadDialog(fileIter As VDF.Vault.Currency.Entities.FileIteration, _     parentWindowHandle As IntPtr)        ' pop up the Get/Checkout dialog        Dim settings As New VDF.Vault.Forms.Settings.InteractiveAcquireFileSettings( _            m_conn, parentWindowHandle, "Download files")        settings.AddEntityToAcquire(fileIter)          VDF.Vault.Forms.Library.AcquireFiles(settings) End Sub

Finally a Good Splash Screen

I’ve been waiting for this for almost 9 years, and it’s finally here.  Vault has a good splash screen!

Don’t get me wrong.  The old splash screens were not bad, they just didn’t fit well with the product.  Commonly the Vault screens would be very CAD related.

The above image would look perfect on AutoCAD or Inventor, but it just doesn’t fit Vault.  It’s not a bad image, but it doesn’t describe what the product is about.

---

Some of the early releases of Vault used “guys standing around a table” imagery.

This is better, but it doesn’t quite hit the mark.  Notice the lack of computers or anything hi-tech.  Some of the images even featured people staring at blueprints.  Although there is a collaboration aspect to Vault, it’s not really meant to simulate face-to-face meetings like what is being shown.

---

Vault is really about connecting and organizing CAD data, which brings us to the Vault 2014 splash screen.

Ahh, look at it.  A thing of beauty.  It has a nice hi-tech vibe to it and is pleasing to the eye.  So what do the interconnected balls represent?  The vault client and server components?  CAD files?  People?  Data management systems?  The answer is all of the above.  Vault does all of those things, and those things are a fitting description of Vault. 

Vault is a hard product to describe, so it doesn’t surprise me that it took so long to get it right.  I’m just glad it happened.  As a programmer, I usually don’t care about things like branding, but it looks like some real effort was put in to understand the products.  I’m not just talking about Vault either.  All the new Autodesk product releases are accompanied by amazing imagery.

Getting to Know the VDF

The VDF will feel a lot different than the rest of the Vault API.  It’s almost as if it was built by a completely different team.  The reason is because it was built by a completely different team.  There are other reasons too.  Working with UI components is different than working with server calls.  Also, the VDF is able to follow a more object oriented approach than the web service layer.

But I'm getting ahead of myself.  This post is about getting to know the VDF.  No talk of commitment or marriage or anything.  It's just a nice casual tour of the major components.

---

The DLLs

There are 4 DLLs that make up the VDF.  They are the ones that start with Autodesk.DataManagement.

Autodesk.DataManagement.Client.Framework.dll - This contains components that are not Vault-specific and do not contain UI.  Features include logging and error parsing.

Autodesk.DataManagement.Client.Framework.Forms.dll - This contains UI components that are not Vault-specific.  Features include an error dialog and progress dialog.

Autodesk.DataManagement.Client.Framework.Vault.dll - This contains Vault utilities but no UI.  Features include Connection management, download/upload workflows, working folder information, and Entity objects.

Autodesk.DataManagement.Client.Framework.Vault.Forms.dll - This contains Vault UI.  Features include the login dialog, browse control, and checkout dialog.

---

Entry Points

Each DLL has a Library object which contains a set of static methods.  The methods themselves are dependent on the feature set of the DLL.  The other major entry point is the Connection object, which has a set of managers.  Each manager contains methods for invoking high level workflows.  There is some overlap between VDF managers and web service managers.  For example, you can add a category through Connection.CategoryManager.AddCategory or Connection.WebServiceManager.CategoryService.AddCategory.

---

Currency and Services

The VDF has its own set of currency objects.  These are basic objects used only for structured data.  Objects that perform actions are referred to as services (aka. managers).  VDF currency is similar to the Web Service currency, but there is usually more information in the VDF currency.  For example, the VDF’s FileIteration object has object references to the parent Folder and Category object reference.  The web service equivalent, File, has only ID references to parent Folder and Category.

You will frequently have to convert between the VDF and web service currency.  You can construct a VDF object from a web service object.  You can also cast down from VDF to web service object.  So it’s not too bad, but you still have to keep track of the different sets of currency.

---

Settings and Results

The VDF supports many complex workflows, which may have multiple configuration options.  Instead of having functions with 20+ inputs, the VDF uses a settings object instead.  If you want the default behavior, you can just new up a settings object and pass it in to the workflow or UI.  Alter the settings object if you want non-default behavior.

The results of a workflow can be just as complex as the inputs, which is where the results object comes in.  If something goes wrong, don’t assume you will get an exception.  In many cases, you need to check the results object to see if there were failures or not.  Also, when UI is involved, you can’t assume that the user did what they were supposed to do.

DECO 2014

Time to start updating my apps.  The first on the list is DECO (Design Editor for Custom Objects).  Not only is this a must-have when using custom objects, but it gave me a chance to play with the new grid control in the Vault SDK.  If you are unfamiliar with DECO, have a look at the page for the 2013 version.

I added one cool new feature for DECO 2014: a grid containing all the linked children.  You can now view/add/delete links using UI created with DECO.

Have a look at this short video...

---

Requirements:

• Vault Professional 2014
• XAML editor such as Visual Studio Express or Expression Blend

Click here for the application
Click here for the source code

---

Issues / Limitations:

• Custom Objects only.  No support for files, folders, items, and so on.
• The grid control only works with links to child entities.  There is no way to show “where used” data in a DECO control.
• Visual Studio 2010 has problems editing a XAML file with a WindowsFormsHost control.  I don’t know about Visual Studio 2012.
• The XAML files and Settings.xml need to be distributed to all clients in order for them to see the custom UI.  This issue will be addressed in the next release of Project Thunderdome.
• When adding a link, the browse dialog only lets you browse items available through Project Explorer.  In other words, only files, folders and linked entities.

As with all the samples on this site, the legal disclaimer applies.

Vault 2014 SDK - What’s New

The Vault 2014 SDK has some nice goodies for the development community.  Of course there are also changes that you need to make when upgrading your old code.  I’ll be going into each of these topics in more detail.  For now, here is a quick overview of what’s new.

---

The VDF

We came up with a set of tools so cool, we had to come up with a new acronym.  The Vault Development Framework (VDF) is a set of client-side libraries to support higher level operations and workflows.  It’s basically there so that you can do more with less code.

Here is a brief look at the architecture.

The VDF doesn’t provide complete feature coverage, so there are still many cases where you need to make web service calls.  If you are updating your code from a previous release, your web service calls can stay in place for the most part.

There are some VDF pages on the Vault Wiki.  I’ll be covering the same content on my blog in the upcoming weeks.

---

Filestore Server

The web services have shifted around to incorporate the concept of a filestore server.  For many years now, the top tier Vault products have allowed for the filestore and database to be on separate servers.  This is a good feature, but the API wasn’t reflecting the architecture.  All API calls used to go through the server with the filestore on it.  It’s not a very good approach since a second hop would be needed for database data.

In Vault 2014, the API has been re-designed so that database-related calls go straight to the database server and file-related calls go straight to the file store.  The WebService manager takes care of most of this for you, but there are some changes that will impact your code...

---

Uploading and Downloading

Uploading and Downloading requires both database and filestore data, so those operations can no longer be done in a single call.  The good news is that the VDF wraps the extra complexity.  I suggest you use Connection.FileManager.AcquireFiles for download and check out.  The FileManager also has AddFile and CheckinFile for the upload-related tasks.

---

API Compatibility

Vault 2014 continues with the web service API compatibility feature from the last release.  This time around, Vault supports 2 releases back, which means Vault 2012 and Vault 2013 clients will still be able to talk to a Vault 2014 server. 

Just like before, the compatibility feature only applies to the web service layer.  All other API features are version-specific.

Vault 2014 will be the last release that supports the 2012 web services.

---

.vcet.config Syntax

The XML syntax has changed for the .vcet.config files.  The new format is more flexible and allows for new extension types.  The easiest thing to do is copy-paste from the Getting Started section of the SDK documentation.  If you want to see the full spec, it’s in the Knowledgebase section of the SDK documentation.

---

Vault Explorer and Job Processor Extensions

The VaultContext class has been removed.  Instead your extension will be given a fully working Connection object.  Things are much cleaner this way since you don’t have to construct your own WebServiceManager.  It also fixes a couple of other issues, such as error 300.

The interface for Vault Explorer extensions has been renamed from IExtension to IExplorerExtension.

---

Persistent IDs

In the past, there was never a reliable way to reference a File from outside Vault.  File names can change, so that’s not good.  File ID and MasterId are database keys, so it’s not a good idea to use those.  In Vault 2014, we now support persistent IDs, which are guaranteed to never change.  The feature applies to Files, Folders, Items, Change Orders, and Custom Entities.

The relevant functions are GetPersistentIds and ResolvePersistentIds in the KnowledgeVaultService.

Logging in through the Vault 2014 API

Now the Vault 2014 is out, I thought I would just jump in and show off one of the new API features - the Login Dialog.  Next week I’ll take a step back and explain all the new stuff.  For now, just sit back and enjoy my new intro sequence...

The Package Service

The Package Service is harder to describe than the rest of the Vault web services.  It was designed with one thing in mind, but ended up doing something else.  As a result, there are some artifacts left around that make it confusing to work with.  The main use nowadays is to import and export BOM data between the Item service and a file.  But there is still some active legacy behavior that you might find useful.

---

File Import/Export:

The Package Service implements the Import and Export commands for Item BOM data.  You can find sample code in the ItemEditor example in the SDK.

The biggest confusion with import/export API is that the Package Service has its own BOM objects, which act as an intermediate between the Item Service BOM and the imported/exported file.  Another point of confusion is the fact that the words "import" and "export" don't show up in any of the API functions.  

For example, to export, you call PackageService.GetItemsAndBOMsFromItemIds() to convert the Item BOM to the Package BOM.  Next you call PackageService.DownloadPackage() to convert the Package BOM into a file.

Import works pretty much the same way but in reverse.  The major difference is that the Package BOM has can detect conflicts in the import.  For example, if you try to import revision A of an item but Vault has the same item at revision B, that's a conflict.  The Package BOM allows you to see, and sometimes fix, conflicts like these before the Item BOM gets updated.

---

Legacy Behavior:

The original intent of the Package service was to be an integration point between Vault and ERP Systems.  The original name for the service was the ERPService and you can still see ERP used in a few class names.  Out of the box, Vault supported compatibility to Microsoft Great Plains.  There was an Axapta integration too, but I think it required Autodesk Consulting.  Both integrations consisted of Vault importing/exporting data to a Microsoft Message Queue (MSMQ).

The intent was to support more integrations and maybe even have a pluggable interface.  But once the Job Server feature was developed, it became the main focus for integrations.  I wouldn’t go as far to say that the Package Service is gathering dust, but I don’t expect any other systems to be added to the Package Service.  You can basically import/export to an MSMQ or a file (which is labeled as “other” in the UI).  As far as I know, the MSMQ features still work, so you can use it as an alternative to Vault job queue.

Status Update

Vault 2014 is out but only the Basic version.  I’m waiting until Vault Professional 2014 is released before I dive into the technical details of the API.  Stay tuned... or whatever the 21st century equivalent is.

This upcoming year, I will try a new format for my videos.  Currently most of the content is contained is a 6-hour block of videos, which I realize is probably intimidating to some people.  The new format will favor more videos with a smaller size.  I’m hoping for around 10 minutes in length.  Each video will cover only one topic to make it more bite size.

I’m officially on the PLM 360 team.  In fact, I’ve been on the team since the new year.  But don’t worry, Vault API Expert isn't a title I will be parting with anytime soon. I’ll still be providing plenty of Vault content on this blog and in the development community.  You will also see a few others from the Vault team contributing to things like API support and discussion groups.

As to what I’m working on in PLM 360, I’ll leave it to your speculation.  As you probably know, I can’t talk about things that haven’t been released yet.

Sacred Tome of Vault Knowledge - Update

Well, that didn’t work out very well.  A couple of weeks ago I asked for people to submit useful Vault links.  I got a total of two responses.  As promised, I will be highlighting each of these links.  I’ll also add some links of my own to round out the article.

---

Autodesk Inventor FAQ

As the name implies, this German blog focuses mainly Inventor.  However, there is a very good Vault section with some original content.  For example, using Vault with Dropbox and instructions on using a script to show who is currently logged into Vault.  There is also a good set of articles on Productstream Professional.

Thanks Jürgen

---

Design and Motion

A good blog that covers many Autodesk products including Vault and PLM 360.  Most posts are quick tips, but there are also some good article-length postings.  For example, using Vault and iLogic to override mass properties in iParts and using multiple Inventor libraries.

Thanks Scott

---

coolOrange

I feature these guys a lot, and for good reason.  Their blog has some excellent articles on Vault programming.  Each one is filled with technial information and a generous helping of source code.  I'm not going to highlight any individual articles because I literally can't decide wich ones to choose.  All the articles are worth checking out.

---

CAD.de forums

This site has the best Vault form that I have come across outside of Autodesk.  I even post there from time to time.  My only wish is that Google was better with German to English translations.  They also have a very good Productstream Professional forum. 

---

Autodesk Vault по-русски

I’m pretty sure this is the best Vault blog in Russian.  There you will find interesting articles such as using Vault and Revit Server and a history of Vault.  Although the main focus is Vault, there are a lot of PLM related articles popping up.