It's All Just Ones and Zeros

API Versioning for PLM 360

The PLM 360 API, like most REST API’s, have a version component to their URLs.  However, the meaning of the version changes from system to system.  So let me explain what that version means for the PLM 360 API.

The API version is the part you see in the URL for a REST call.  So if you are getting a list of workspaces from https://mytenant.autodeskplm360.net/api/v2/workspaces/, 2 is the API version number.  In PLM 360, this number identifies a compatible API set.  In other words, v2 will maintain compatibility as new releases of PLM come out.  Things may be added to REST v2, but existing content will still work the same as before.

At some point in the future, there will be a v3 API, which will probably not be compatible with v2.  When new API versions are introduced, they will live side-by-side with existing API versions.  This gives developers ample time to move their code to the latest API version.  Here is a rough diagram of what I’m talking about.

There is no set time for any of this.  The v3 API may come out in a year, two years, or maybe never at all.  Likewise the end-of-life for v2 is not set either.  It may be a year after v3 comes out, or two years, or maybe never.  All I can say is that the end-of-life for an API version will be announced ahead of time. 

---

The product version for PLM 360 gets updated for every major PLM 360 release, which happens about every month.  You can easily find the current version by going to /version.txt on your tenant.  At the time of writing, 9.1 is the current version.  When PLM updates, new features may be added to the API.  So if you want to name a specific API schema, you need to include both the API version and the product version.  For example, “API schema 2:9.1” or something like that.  Most of you shouldn’t have to care about exact schemas.  The API version is usually sufficient.  However, I do recommend that you record the current PLM 360 product version somewhere in your code and/or readme documentation.  It will be a helpful data point if you run into issues later on.

---

Cloud Based APIs

Is using a cloud API really any different than any other client/server API?  If you have developed with the Vault API, then you should already be familiar with many of the core concepts.  Things like latency, user permissions and multi-user environments all still apply to the cloud.  So is the cloud just a larger scale version of client/server programming?

No, there are some fundamental differences.  Differences that need to be accounted for in your code.

---

Frequent updates, whether you want them or not 

When a new version of PLM 360 goes live, customers have no choice but to accept the new version.  For the end-user, this is usually a good thing.  At the API level, it adds an element of instability.  Gone are the days where you get your customization running and breathe a sigh of relief, knowing that things are working and stable for the next year or two until the next upgrade.

PLM 360 upgrades are about every 4 weeks, and everyone gets the update.  These upgrades are not something you can plan for like with installed software.  For example, a typical Vault upgrade involves the admin testing the new version, then planning when the upgrade should take place.  PLM 360 is not like that.  It updates without warning, so you can’t plan for it.  And you definitely can’t pick the date.

Sometimes a Vault upgrade will go wrong and the customer will decide to stick with the older version for a while longer.  Which brings me to my next point...

---

You can’t go back

Once the PLM 360 upgrade happens, that’s it.  You can’t go back to the older version.  In fact, the old version doesn’t even exist anymore.

This fact adds an extra complexity to debugging.  If you notice a new bug, it’s hard to determine if it’s because of a PLM update or if it’s a bug that was always there, and you just never noticed.  With a desktop app, you could always install the prior version and get a definitive answer, but you don’t get that with the cloud.

Sometimes it’s not a bug, but your app is... different.  For example, the data is being displayed differently or a command has different results than before... you think.  Again, it’s hard to know if it’s because of the PLM update or old age.

---

Tips for working with the cloud

Here are some pieces of advice for working with a cloud API.  If you have an more advice, let me know in the comment section.

• Forward Compatibility - Your code should always expect the unexpected.  Avoid assumptions as much as possible.  For example, PLM 360 currently has 6 types of workspaces.  Next week, it may have 7.  You code can’t crash if it comes across a workspace type it has never seen before.
• Smoke Tests - Create an automated test of your app’s functionality.  The advantages are numerous.  You have an easy way to spot issues before users do.  You have a mechanism for pinpointing the exact failure.  Saving the smoke test results gives you a document of how things worked in past PLM 360 versions.
• Documentation - Be thorough in documenting your app’s behavior.  Record videos if you can.  If not, then take lots of screenshots.  Again, the goal is to have something to reference if you believe there is a change in behavior.

---

The Autodesk side of things

Obviously, we here at Autodesk also want your apps to be as stable as possible.  Here is what you can expect from us.

• Backward Compatibility - Just like your app needs to be forward compatible, the PLM 360 API needs to be backward compatible.  Although content will be added to REST v2, existing content will not be changed or removed.  If a situation arises where the data model needs to change, that new model will go into REST v3.
• Defect Fixing - If you believe there is a defect in the API, let us know.  One of the major advantages of the cloud is the ability for us to fix defects quickly.
• Developer Services - We are working on some initiatives that should alleviate some of the pain points that I mentioned.  But, I can’t say anything more at this time. 

---

Features of the PLM 360 REST API

OK, great, there is an API for PLM 360.  So what can one do with it?  How is it different than scripting?  What does REST even mean?

Ultra short definition of REST:  
REST allows a client to communicate with a server via HTTP.

You can read more about REST if you want. But for the purposes of this article, REST means that you can write a client app that talks to PLM 360 over HTTP.

Scripting vs REST:
PLM 360 has a scripting engine for performing server-site tasks in response to certain events.  Scripting is great but it can’t integrate two systems or plug-in to AutoCAD.  For client-side operations, you need the REST API.

---

Features of the API:
There are a lot of things PLM does, but not all those features are available yet in the API.  The initial focus of the API is to provide a stable framework to build on.  I believe we now have that framework, so the next steps are to add more features.

Current feature set:

• Login / logout.
• Get all the workspaces.
• Get detailed information on a workspace (item details tab only).
• Get a list of all the items in the workspace.
• Get a filtered list of items in a workspace.
• Read data on an item (item details tab only).
• Add / edit / delete an item.
• Get a list of all files attached to an item.
• Upload /download files.
• Checkin / checkout / undo checkout of a file.

Note: All operations and data are scoped to the permissions of the logged in user.

---

Uses for the API:
There is enough functionality here to start writing some interesting apps.  Here are some ideas.  Some of these ideas can already be seen in sample apps.

• Take a picture with your mobile device and attach it to an item in PLM 360.  (see Java sample)
• CAD plug-in that pulls data from PLM 360 and uses it in the model. (see Material Profile example)
• Integrations with other systems.
• Custom views of PLM data.

---

API Updates:
In theory, the API can be updated any time PLM 360 updates, and PLM 360 updates about every 4 weeks.   That means there will be a constant stream of new API functionality.  It’s not like with Vault where you have to wait a year for API updates.  If there is a specific feature you want API support for, let us know in the idea station.  That will help us prioritize what to work on next.

---

PLM 360 REST API is Live

If you go to PLM 360 Online Help, you may notice a new section at the bottom.  The “REST API v2 Reference” has everything you need to get started developing client applications for PLM 360.

Since I’m an engineer, I’ll immediately dive in to the bad news...

---

The API is in tech preview mode.  That means we are still stabilizing it.  Support is limited, and breaking API changes may occur without warning.  It’s perfect if you want to be an early adopter, but I highly discourage writing anything mission critical at this time.  Please keep your apps limited to prototypes and easy-to-update utilities. 

Once the API stabilizes, we will remove the tech preview restrictions and provide official support.  I have no ETA for when this will happen since stability isn’t something I want to rush.

---

The next piece of bad news is that you need an Oxygen key to log in.  Oxgyen is the service that let’s users log in with their Autodesk ID.  You need to first request a key.  Once you have your key, you have to write a fair amount of code to allow your app to log in to PLM.  All these steps are outlined in the “Authentication” section of the online API help.

The good news is that one you are logged in, the rest of the PLM 360 API is pretty straightforward.

---

Lastly, there is a distinct lack of API libraries.  Most of the burden is on the client developer to deal with the low level REST details.  Again, this is because the API is for early adopters.  There are some sample apps to help you, but they don’t contain full API coverage.  If you want to do anything not shown in a sample app, you will have to write the proxy code yourself.

We will eventually have a set of libraries to hide the low level REST details, but I don’t have an ETA at this time.  If you are a long time reader of this blog, you know that I like to write sample apps.  So I’m very motivated to get these libraries in place.

---

If you have any questions or comments about the REST API, I suggest posting to the PLM 360 discussion group.  Please put “REST API” in the title, so that I can easily find it.

Keep reading this blog for the latest PLM 360 API announcements, sample apps, articles, tips and tricks, etc.  From here on out, this blog will be covering the APIs for both Vault and PLM 360.

---

The Loader Framework

One interesting little API gem is the ExtensionLoader.  Well, it’s interesting to me because I designed it, but maybe you will find it interesting too.  I basically took the mechanism for loading plug-ins and made it public in the API.  In theory, you can make use of this tool to load extensions of your own.  Another use is interrogating the system to see which Vault plug-ins are available, where they live, what their settings are, and so on.

In order to be loaded by the framework, a plug-in has to meet certain requirements.

• The plug-in has to work through an interface.
• The plug-in needs a class that implements the interface.
• The loader app needs to be aware of the interface.
• The implementing class needs a default constructor.
• There needs to be .vcet.config file, which is what tells the loader framework about the plug-in.

If you take a closer look at the .vcet.config for a 2014 plug in, you will notice that an <extension> contains an interface and type.  Interface can be anything you want.  IExplorerExtension, IJobHandler and IWebServiceExtension are the ones provided by the Vault API.  But the loader framework doesn’t care about that.  It will work with any .NET interface.  Type is the class that implements the interface.  The Loader creates a new instance of that class when loading the plug-in.

---

The loader framework can be access through the ExtensionLoader, which is in Autodesk.Connectivity.Extensibility.Framework.  Here is a quick example I put together.  It’s for an EXE that prints out the Vault Explorer extensions along with their custom commands and tabs.

// C# using Autodesk.Connectivity.Extensibility.Framework; using Autodesk.Connectivity.Explorer.Extensibility;     ExtensionLoader loader = newExtensionLoader();   // load the plug-ins matching the IExplorerExtension interface var extensions = loader.LoadExtensions<IExplorerExtension>(); foreach (Extension<IExplorerExtension> extension in extensions) {     output.AppendLine("Extension " +         extension.ExtensionAssembly.ProductName);         // create a new instance of the plug-in     // we are not going to run it     // we just want to read data from it     IExplorerExtension explorerExt = extension.NewInstance();       // ask the plug-in for it's commands     IEnumerable<CommandSite> customCommands =         explorerExt.CommandSites();     if (customCommands != null && customCommands.Any())     {         output.AppendLine("- Custom commands: ");         foreach (CommandSite site in customCommands)         {             foreach (CommandItem command in site.CommandItems)             {                 output.AppendLine("-- " + command.Label);             }         }     }       // ask the plug-in for it's custom tabs     IEnumerable<DetailPaneTab> customTabs =         explorerExt.DetailTabs();     if (customTabs != null && customTabs.Any())     {         output.AppendLine("- Custom tabs: ");         foreach (DetailPaneTab tab in customTabs)         {             output.AppendLine("-- " + tab.Label);         }     } }

' VB.NET Imports Autodesk.Connectivity.Extensibility.Framework Imports Autodesk.Connectivity.Explorer.Extensibility     Dim loader AsNewExtensionLoader()   ' load the plug-ins matching the IExplorerExtension interface Dim extensions = loader.LoadExtensions(OfIExplorerExtension)() ForEach extension AsExtension(OfIExplorerExtension) In extensions     output.AppendLine("Extension " + extension.ExtensionAssembly.ProductName)       ' create a new instance of the plug-in     ' we are not going to run it     ' we just want to read data from it     Dim explorerExt AsIExplorerExtension = extension.NewInstance()       ' ask the plug-in for it's commands     Dim customCommands AsIEnumerable(OfCommandSite) = _         explorerExt.CommandSites()     If customCommands IsNotNothingAndAlso customCommands.Any() Then         output.AppendLine("- Custom commands: ")         ForEach site AsCommandSiteIn customCommands             ForEach command AsCommandItemIn site.CommandItems                 output.AppendLine("-- " + command.Label)             Next         Next     EndIf       ' ask the plug-in for it's custom tabs     Dim customTabs AsIEnumerable(OfDetailPaneTab) = _         explorerExt.DetailTabs()     If customTabs IsNotNothingAndAlso customTabs.Any() Then         output.AppendLine("- Custom tabs: ")         ForEach tab AsDetailPaneTabIn customTabs             output.AppendLine("-- " + tab.Label)         Next     EndIf Next

---

Here is what the output looks like on my computer.  As you can expect, I have a good number of plug-ins installed.

Extension AdvancedAdvancedFind - Custom commands: -- Advanced Advanced Find... Extension Deco Extension EffectiveFolderPermissions - Custom commands: -- Effective Permissions -- Permissions Overview -- Administrator List -- Settings -- Effective Permissions -- Effective Permissions Extension Thunderdome - Custom commands: -- Backup Vault Settings -- Create Deployment Extension VaultWebView - Custom commands: -- Configure Web View... - Custom tabs: -- Web View 1 -- Web View 1 -- PLM 360

It’s not quite perfect.  Duplicates show up because the command/tab shows up in different contexts.  Also, DECO does have custom commands, but they are not shown here.  The reason is that the plug-in was loaded outside the context of Vault Explorer, and DECO doesn’t like that.

---

Logging in the Hard Way

Because of the new Filestore Server architecture, logging in to Vault 2014 takes up more steps than it did before.  If you are using the WebServiceManager or Connection object, fell free to skip this article because the extra steps are performed automatically for you.  But if you are making direct calls to the web service URLs, then keep reading.  I’ll outline the new steps for logging in.

First, make sure you understand the AVFS architecture.  Even if everything is installed on the same computer, your code needs to see Vault as two separate servers.  The link above also lists which services are on which server.

The SignIn calls are in the AuthService and WinAuthService, which are part of AVFS.  If you are showing a login dialog to the user, for example, then the user is expected to type in the name of the Filestore Server, not the Data Server.

If you are logging in with Vault username/password, use the AuthService.  If you are logging in with Windows credentials, use WinAuthService.  Depending on the needs of your app, use either SignIn(), SignIn2() or SignInReadOnly() to authenticate.

---

Once you are authenticated, you need to figure out where the Data Server is located.  You do this by calling IdentificationService.GetServerIdentities, which returns an array of ServerIdentities.  Each ServerIdentity represents a Filestore Server and it’s related Data Server.  There may be multiple results if there are multiple filestores installed. 

Find the ServerIdentity that matches the filestore you just authenticated to.  Remember the DataServer value, because that is the server to call for all web services on the data server. 

Once you have it set up  so that each web service calls are going to the correct server, you mostly don't have to worry about about the different server types.  The glaring exception is file IO, which I explain in my article: File Transfer - Doing it the Hard Way.

---

Effective Permissions 2014

If you are a Vault Administrator using the advanced security features in Vault, you need this app.  Period.

Here is the video from the 2013 version if you need some background on the app.  I didn’t add any new features in 2014.

---

Requirements:

• Vault 2014 Workgroup / Professional
• Administrative Rights

Click here to download the application
Click here to download the source code

Click here for 2013 version

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

---

AU Classes of Interest

Here are some AU classes and events for the technically oriented readers of my blog.  If you are a Vault programmer, AU is a good opportunity to get up to speed on PLM 360 and its APIs.

NOTE:  PLM 360 scripting and REST API are two completely different things.  People with little to no programming experience can benefit from scripting.  However, the REST API is much more complex and is geared toward programming professionals.

---

Let’s start with the content that I’ll be presenting:

DevDays - Las Vegas - MFG Breakout Session - I’ll be going over the upcoming features in Vault.  I’ll also be going over PLM 360 for those that haven’t used it yet.  Since this is for developers, emphasis will be placed on programming and customization.

DV1518 - Programming PLM 360 using REST - I’ve been working on this API for many months, so I’m looking forward to helping people get started writing custom applications. 

At the time of this writing, the PLM 360 REST API is only available to early adopters, but that may change by the time AU rolls around.

DV1670 - Programming the Vault with the VDF - I’ll be co-presenting this class with Dennis Mulonas, who is one of the architects on Vault.  We’ll go into the new Vault 2014 features, with emphasis on the Vault Development Framework. 

DV2227 - Autodesk Cloud and Mobile API/Technologies: Meet the Experts - We gathered up all the experts on the various Autodesk cloud APIs and put them together in one room.  So come with your questions, or just sit back and listen to what others are doing.  I’ll be on the panel to field any PLM 360 questions.

---

Here are classes being presented by others:

MA2948 - High Dividend on Autodesk PLM 360 Exchange Apps - The cloud nature of PLM 360 makes this app store a bit different than for other Autodesk products.  However, there is still great opportunity for developers to “get in on the action.”

PL2758-P PLM 360 Automation Solutions with Scripting - Get an in-depth look at scripting in PLM 360 and how it can enhance your processes.

PL2760-L PLM 360 Developers Delight - A hands on PLM 360 Scripting overview - A lab on PLM 360 scripting.

UT1628-R - Practical Integration Between Autodesk AutoCAD Utility Design and Autodesk Vault Professional - I have no idea what this is about, but it looks cool.  I’ve attended Dan Leighton’s classes in the past, and they have always been awesome. 

---