Here is the quick list of registration links for my upcoming webinar series. See my earlier post for full descriptions of each one.
As promised, I came up with something for those of you who want to customize Vault through the use of scripts. I decided to use PowerShell as the scripting engine since it has a lot of tools ready-to-use for this sort of thing. If you are not familiar with PowerShell, you can find tons of information on the internet, including the Microsoft web site.
vLogic Features:
Requirements:
Click here to download the application
Click here to download the source code
To use:
Run the install and start Vault Explorer.
Under the Tools menu is the vLogic menu. This is where you can run existing scripts or create new scripts.
To create a new script, select Create New Command from the vLogic menu. After giving your script a name, you will have to re-start Vault Explorer. When the program re-starts, your command should show up in the vLogic menu.
To edit a script, hold the shift key and click on the command. The PowerShell ISE should pop up, allowing you to edit the script while Vault Explorer is running. When you are done with your changes, save the file in the editor.
To run a script, run the command from the vLogic menu.
To delete a script, go to %ProgramData%\Autodesk\Vault 2012\Extensions\vLogic and remove the .ps1 file. You can also add commands by putting .ps1 files in this folder.
There are some downsides to vLogic. If you are not familiar with PowerShell, then it’s basically a new language that you have to learn. If you have complex operations or UI, then you are better off using Visual Studio. As this moment, I have no good story for debugging a vLogic script.
This is just my first pass at adding scripting to Vault. There is lots of room for improvement for future releases.
As with all the samples on this site, the legal disclaimer applies.
Put on your Ramones T-shirt and get out your beige box because it’s hacker time. Not real hacking, of course, since I work for Autodesk. This is more of a “programmer for a major software corporation posting to a blog” style of hacking.
Anyway, the goal is to display up a better message when our programs run across an error from Vault. For example, instead of “303” as the error message, I’ll show you how to display “PermissionDenied” or whatever else you want.
There are over 800 error codes that the Vault server might return, and they always take the form of a number. We want to display something human readable and we don’t want to spend all day typing.
Here are the hax0r tools you will need:
Step 1: Get the error codes
You can find the list of error codes in the SDK documentation. Go to the “Error Codes – Server” page has our list. It has all the codes, and it has text names of the codes.
Right click on the page and click on “View Source.” This will pop up the raw HTML. Save the text as an HTML file. Now we have the codes out of the CHM. The codes are in table form, which is good, but we need to do more with this data. So let’s fire up a spreadsheet program.
Step 2: Edit in Excel
Open the HTML file in Excel, which will take the error code table and put it in spreadsheet format. Feel free to delete everything outside the error code table.
We need to put a text prefix in front of our error numbers. Visual studio won’t like it if we have a number as our first character, so we are going to add the word “error” in front of all error number. Select all the error numbers, right click, and choose “Format Cells.” In the number tab, put in “error”0 as the custom format. Now we have a word in front of our error codes.
Your error code table should look like this. 
Step 3: Copy into Visual Studio
Inside of your Visual Studio project, create a new RESX file if you don’t have one already. To create a new one, you need to add a new Resources File to your project. If you are not familiar with the concept, a resources file is a place to store things in your program like images and string tables. It’s the perfect place for this error code table.
In Excel, select the first two columns from our error code table. Don’t select all rows, just the rows with error codes in them. Copy these cells.
In Visual Studio, select your RESX file and go to the Strings part. Run the paste command and it should put in all our data. Now we have all our error codes in a format where it is easy to look up from our code.
Step 4 (optional): Error handling with Invoke Events
As I mentioned in my Invoke Events article, you have common hook point for handling all the errors coming back from the server. So here is some example code that makes that happen…
|
// C#
using (WebServiceManager serviceManager = new WebServiceManager(login)) { // add hooks to all services that you use // do this right after the manager is created serviceManager.DocumentService.PostInvokeEvents += Service_PostInvokeEvents; serviceManager.PropertyService.PostInvokeEvents += Service_PostInvokeEvents;
// do stuff }
// gets called after every web service call void Service_PostInvokeEvents(object sender, WebServiceInvokeEventArgs e) { if (e.Exception != null) { DisplayError(e.Exception); return; } }
// show the message to the user void DisplayError(Exception ex) { string errorCode; List<string> restrictionCodes;
GetErrorAndRestrictionCodesString(ex, out errorCode, out restrictionCodes);
string errorMsg = String.Empty; if (errorCode != null) { string desc = Resource.ResourceManager.GetString("error" + errorCode);
if (desc == null) desc = "Unknown error";
errorMsg = "Error retuned from Vault Server: " + desc; } else errorMsg = "Error: " + ex.Message;
MessageBox.Show(errorMsg); } |
|
' VB.NET
Using serviceManager As New WebServiceManager(login) ' add hooks to all services that you use ' do this right after the manager is created AddHandler serviceManager.DocumentService.PostInvokeEvents, AddressOf Service_PostInvokeEvents AddHandler serviceManager.PropertyService.PostInvokeEvents, AddressOf Service_PostInvokeEvents
' do stuff End Using
' gets called after every web service call Private Sub Service_PostInvokeEvents(ByVal sender As Object, ByVal e As WebServiceInvokeEventArgs) If e.Exception IsNot Nothing Then DisplayError(e.Exception) Return End If End Sub
' show the message to the user Private Sub DisplayError(ByVal ex As Exception) Dim errorCode As String Dim restrictionCodes As List(Of String)
GetErrorAndRestrictionCodesString(ex, errorCode, restrictionCodes)
Dim errorMsg As String = [String].Empty If errorCode IsNot Nothing Then Dim desc As String = Resource.ResourceManager.GetString("error" & errorCode) If desc Is Nothing Then desc = "Unknown error" End If errorMsg = "Error retuned from Vault Server: " & desc Else errorMsg = "Error: " & Convert.ToString(ex.Message) End If
MessageBox.Show(errorMsg) End Sub |
The code for the GetErrorAndRestrictionCodesString is from an earlier article.
By default, Vault Explorer provides the View Properties Grid which provides a list of all property values for the selected object. This is a nice default view, but us developers commonly want to have customized property views (aka. property pages). So here is a quick primer on creating property pages in Vault Explorer.
Note: This article is basically a condensed version of Dan Leighton’s excellent AU 2011 class, Manage Dozens of Autodesk Vault Workgroup Properties with Custom Forms and Reports. If you have the time, feel free to skip the rest of this post and view the video on the AU site. Also, his handout is full of sample code!
The first step is to set up your project for writing a Vault Explorer extension. You can read up on this in the SDK documentation. Or you can just copy the HelloWorld example and build off that.
Property pages in Vault Explorer most commonly take the form of custom tabs or custom dialogs. I’ll be showing an example of a custom tab, which means we start by defining our own User Control (right click on your project and select Add –> User Control). Now we have a blank control. Next you drag and drop controls from the Toolbox into your custom control. Usually each property will have two controls, one to display the property name and one to display the property value. A Label control is usually used for the property name. The value is usually represented by a TextBox, but there are tons of controls to choose from. Other useful controls are ComboBoxes, CheckBoxes, DateTimePickers, RadioButtons, and so on. For this example, I’ll keep it simple and just stick to TextBoxes.
Now that we have our controls in place, we need a way to map the specific property values to the correct controls. Sure we could just hard code the mapping for each TextBox, but that doesn’t leave us with any reusable code. It also doesn’t make things easy for us in the future if we have to make changes to our property page. A better way is to add meta-data to our controls. At runtime we route the property data to the correct control based on the meta-data.
There are a couple of ways to set the meta-data on a control. In this example, I’ll use the “Tag” property. I want to set my TextBox Tag values to something that will let me locate the Vault property. You can use the display name of the Vault property if you are sure that it won’t change. Otherwise, I suggest using the system name.
Now we have our control, and our TextBoxes are smart enough to know what Vault property they are supposed to display. The next step is to write code that looks up the Vault properties on a File and routes those values to the correct TextBox…
Or you could just copy my code from the examples below.
Click here for C# code
Click here for VB.NET code
Here is the final output.
If we ever need to display more properties on the page, it’s as easy as dropping in the new TextBox and setting the Tag value.
This is just a simple example to get you started. More complex cases involve different data types, different control types and allowing the user to edit values through your property page.
If you are getting started with the Vault API, there is a lot of information out there. Unfortunately, it’s all over the place. Some of it is on this blog, some of it is on AU Virtual, some of it is on ADN. Here is my attempt to fix all that. I’ll be doing a 5 part webinar series, covering all the major aspects of the Vault 2012 API.
In total, there will be about 4.5 hours of content for the low price of free. If you do the math, that’s an infinite amount of content per dollar!
This series is perfect for those of you new to Vault programming or those of you that want a refresher course.
The Vault API - Part 1 – Overview
This webinar is an overview of the Vault API. The main purpose is to explain what you can do through custom programming using the Vault API. We will also go over some of the logistical aspects, such as licensing.
Recommended audience: People new to Vault programing and people curious about Vault customization capabilities. This is the only webinar in the series that does not require programming knowledge.
Date and Time: Thu, Feb 2, 2012 - 11:00 AM - 11:45 AM EST
Registration link: Click here to register
Note: This webinar will have the same content as the "Getting Started with Autodesk Vault Programming" videos on AU Virtual, but without the code examples.
The Vault API - Part 2 - Server Communication
This webinar will explain how to communicate with the Vault Server through the API. We will be going over the basic concepts and common workflows, such as sign-in, sign-out, file upload and file download.
Recommended audience: People new to Vault programing or people who want a refresher course. We will be going over sample code, so programming knowledge is required.
Date and Time: Tue, Feb 7, 2012 11:00 AM - 12:30 PM EST
Registration link: Click here to register
The Vault API - Part 3 - Vault Explorer Customization
This webinar explains how to extend the Vault Explorer client. We will demonstrate how to write custom commands and tab views. We will also go over tips and tricks for getting the most out of your customization.
Recommended audience: People new to Vault programing or people who want a refresher course. We will be going over sample code, so programming knowledge is required.
Date and Time: Thu, Feb 9, 2012 11:00 AM - 12:30 PM EST
Registration link: Click here to register
The Vault API - Part 4 - Job Server Customization
This webinar explains how to extend the Job Server feature. Basically Vault manages a central queue for distributing tasks to other computers on the network. We will see how the Vault API can be used to create custom jobs and custom handlers for those jobs.
Recommended audience: People new to Vault programing or people who want a refresher course. We will be going over sample code, so programming knowledge is required.
Date and Time: Tue, Feb 14, 2012 11:00 AM - 12:30 PM EST
Registration link: Click here to register
The Vault API - Part 5 - Business Logic Customization Through Events
This webinar explains how to extend the Vault business logic through the API event mechanisms. There are several different types of events in the Vault API. We will go through each of the event types, learning the pros and cons of each time. We will go over best practices and tips for getting the most out of the event APIs.
Recommended audience: People with Vault programing experience or people who have viewed the previous webinars in the series. Events is a complex programming topic, so this session is geared more for professional programmers.
Date and Time: Thu, Feb 16, 2012 11:00 AM - 12:30 PM EST
Registration link: Click here to register
Note: This is the exact same content as the "Autodesk Vault Programming: Now with Events" class at AU 2011. I'll even be recycling the same jokes.
Jim Quanci, the director of the Autodesk Developer Network, has started a new blog. Dances with Elephants focuses on how small companies can leverage big companies to build their business. I think Autodesk is one of the elephants, but I’ve never been good with allegories. Anyway, put your dance shoes on and head on over.
Although most Autodesk blogs are focused on Autodesk products, there are a few blogs that barely mention our products. Basically, these blogs are just employees that feel they have useful information to share, and I think it’s very cool that Autodesk provides an outlet.
I think I speak for all Autodesk bloggers when I say that we blog because we like to. There’s no corporate mandate on this content. We are free to post whatever we want, whenever we want, and I think the results speak for themselves. So keep on reading and we’ll keep on posting.
The below code will save you a round-trip for each of your Vault API web service calls.
| System.Net.ServicePointManager.Expect100Continue = false; |
If you have your own Vault client, you should put the code sometime during startup. If you are running inside an Vault client from Autodesk, this value should already be set to false.
I don’t have much more to say on this. You find out more about the Expect100Continue property on MSDN.
The third type of event we introduced in Vault 2012 is the Web Service Invoke Events. If you want to read up on the other two types, you can go here and here. The purpose of the Invoke events is to give you a single choke point for whenever your code invokes a web service call to the Vault Server.
Notice that I stressed the word your. This type of event is not for hooking to the existing Vault features. That’s what the Web Service Command Events are for.
The Invoke events just helps you manage your own code. And because it’s limited to you code, there is a lot more you can do with it. For example, you can alter parameters going in and out. With all the other event types, you are just an observer.
So what is this good for? Offhand, I can think of 4 uses:
1. Common Error Handling – I find that I want to handle Exceptions from the Vault Server in the same way most of the time. I don’t want to have the same handler code sprinkled all over my app, so I can just put it all in an event handler.
2. Logging – Let’s say you’re a consultant, and you developed an app for a customer. That app is not working properly, and you have to figure out why. You can’t just run in the debugger on the customer’s machine. So how to you get information on what is happening inside your app? The solution is to sprinkle logging capability throughout your code so that you can get a nice trace from the customer. Using Invoke events you now have a way to log every Vault server call.
3. Debugging – Even during the development process it’s good to have a print out of what is going on between your code and the Vault server. If you code is very complex, it’s very difficult to keep track of which commands result in which API calls. These events can help sort things out for you.
4. Performance – If you app is slow, it’s helpful to know how much time is being used by calls to the Vault server. Based on my past experience, slowness is usually due to redundant API calls or calls that can be optimized.
Coming soon: Sample code....
For the millions and millions of people using the Vault integration for SharePoint 2010, here is a utility that you might find useful. It’s a calendar web part that shows you when your Vault ECOs are due.
(click for full image)
The data can be driven from any Vault Change Order list in SharePoint. Clicking on the calendar entry brings up the detail view for that ECO.
Requirements:
NOTE: The SharePoint administrator needs to deploy and enable the web part before it can be used. See readme file for instructions.
Click here to download the application
Click here to download the source code
Note from the programmer:
I’ll admit, I have next to no experience building web parts. The end result seems to work fine, but the code probably doesn’t comply with the standards and practices.
Also, if you know an easier way to deploy a web part, please let me know.
As with all the samples on this site, the legal disclaimer applies.
The Beta is now available for the next release of Vault. There are some nice new API features that you will want to take a look at, but I can't talk about them here. Sign up for the Beta, and let's chat about it on the Beta forums.
Subscribe
My Take-away from AU
I was busy at AU last week, which is why there wasn't much activity from me online. I'm not going to repeat AU news that has already been posted elsewhere (PLM, Autodesk 360, etc), that's not what this blog is about. I'll keep things focused on the Vault API and share some things I learned.
Yes, I learn things at AU. Not things about the Vault API, but how people perceive and use the Vault API. The more I understand my users, the better I can distribute information.
I've known for some time that the API consumers fall into two camps, the professional programmers and the non-professional "scripters". Since I'm a professional programmer myself, I'm good at providing information targeted at the first group. The second group is where I rely heavily on feedback.
The Scripter persona
Let me take a crack at describing the Scripter (feel free to let me know if I missed something). This person wants to customize the Vault but doesn't want to spend days learning the entire Vault API. Usually they want to write tools tailored to their own environment. There is a task that they do over and over and they want to automate the process or reduce mouse clicks. The best-case scenario for them is to find a similar tool that they can tailor to their own needs. Having to start from scratch is a big pain and sometimes a show stopper.
Cost of entry is also a big factor. It's very important that a scripter can get something working early on, even if its just a Hello World example. Spending hours figuring out how to get a command to load is not acceptable.
Feedback
Most of the feedback I get from scripters is positive so I'd like to share that with you. I don't get much feedback on things that aren't working, but I do get questions like "Do you have an app that does X?"
The good: SDK Samples
These examples are easy to read and easy for scripters to modify.
How to make it better: More samples in the same style. In other words, samples that illustrate one useful concept in a clear and simple way.
The good: .NET
It's an easy-to-use and powerful programming platform. It's free and supports VB.
How to make it better: Get rid of the "compile" step. This goes back to reducing cost-of-entry. The less steps equals lower cost-of-entry. And, technically, scripting means that the code does not need to be compiled. There are a couple of techniques that can help with this goal, such as PowerShell and run-time compilation. I haven't yet taken a serious look at these techniques, but it's on my agenda.
Posted at 08:09 AM in Commentary | Permalink | Comments (0) | TrackBack (0)
Tweet This!