It's All Just Ones and Zeros

.NET 4

In Vault 2013, we shifted over to .NET 4.  This isn’t just an API change, the product itself shifted too.  In fact, I think all Autodesk products using .NET were told to shift over.  The whole suites thing forces our products to be on the same technology platforms whenever possible.

Anyway, here is what you need to know as a programmer.  .NET 2 through 3.5 used the same CLR (common language runtime), which meant that they were very compatible.  However .NET 4 uses a new CLR, which means that there are now compatibility issues between .NET 4 and older .NET versions.  For example, a .NET 3.5 app cannot load a 4.0 assembly.

If you are working with a 3.5 app and want to communicate with Vault 2013 server, you have a few options.  One option is to use the 2012 version of Autodesk.Connectivity.WebServices, which will have 16 as the version number.  Those DLLs will still be able to communicate with the 2013 server.  The downside is that you will not have the newest features, such as custom entities.  Another option is to use the Autodesk.Connectivity.WebServices from the SharePoint 2010 integration.  Because SharePoint 2010 uses .NET 3.5, we had to create a special DLL for it.  You can get this DLL from ADN, however we do not provide official support for it.

Other aspects of .NET 4:

• Visual Studio 2010 or higher must be used
• Any project referencing a Vault API assembly must be .NET 4
• .NET 4 framework must be installed on computers running the app.  The Vault installers definitely do this step during their install, and I think most other Autodesk installers do too.
• If you are writing an extension to Vault, such as a custom command, you can load in older version assemblies.  However it’s recommended to use .NET 4 whenever possible.

Autodesk PLM 360 Sync

The first release of the Vault/PLM 360 integration has been released.  Just like with the SharePoint 2010 integration, I was involved in the design and implementation of this tool.  So I thought I would share my thoughts on the project and go over the technical details.

You can get PLM 360 Sync from the subscription center.  PLM 360 Sync only works with Vault Professional 2013 since items are the only things synchronized in R1.

---

Integration is in the eye of the beholder

Everyone reading this post probably has a different idea on what a Vault/PLM 360 integration means.  For this reason, it’s hard to put out a single utility that is supposed to serve everyone’s needs.  We solved this problem by taking an incremental approach.  This first release is not meant to be everything to everyone.  It has a limited feature set which we will be building on in future releases. 

This incremental approach allows us to gather feedback.  Based on that feedback we will add new features, expand on what is working well and fix things that are not working well.

Currently, the PLM 360 discussion group is the best place to give feedback.  Your suggestions will definitely get more eyeballs than comments on blog.

---

The R1 Feature Set

Item Synchronization (one way) -  Released and obsolete items in Vault get replicated to PLM. 

Seamless Integration - The idea is that the average Vault user doesn’t have to do anything special.  They just use Vault as normal, and all the integration stuff happens in the background. 

Configurability - The Vault administrator has a lot of options regarding what and how data gets synchronized.

Property Mapping - Any Vault item property (except thumbnails) can be mapped to a PLM field. 

Revision History - When an item is synchronized, all revisions get synchronized.  So you can view the item history in PLM 360 just like you can in Vault.

BOM - The entire BOM is synchronized, not just a single item.  Again, the result is an identical data in Vault and PLM 360.

Item Selection - By default, all released and obsolete items get synchronized.  However, you can use the search mechanism to specify exactly what Vault items should be copied.

Multiple Tenants\Workspaces - Your items don’t have to go to one and only one spot in PLM 360.  You can sync your items to multiple locations in PLM 360.  Each location can have its own criteria.  For example, all Vault items from project X can go to one spot in PLM 360 while items from project Y go to a different location.

Bulk Load - If you are starting with a lot of Vault items, you can queue them up for synchronization with a click of the Rebuild History button.  This is also a good tool to have if something goes wrong and you are unsure of which items are replicated and which are not.

Error Handling - If something goes wrong with a synchronization, for example a mapped property no longer exists in PLM 360, the result is an error job in the Vault Job queue.  Once the problem is fixed, the Vault admin can re-submit the job.

Does Not Consume a Vault License - During regular operations, the sync tool does not use up a Vault license.  This feature is possible because the tool only reads from Vault.  If/when we add a 2-way sync feature, we may have to require a license at that point.

---

Technical Details

There are 2 main parts to PLM 360 Sync.  There is a Sync Service and there is a configuration command.  The configuration command is in Vault Explorer, and it’s what the administrator uses to determine which Vault items go to which workspaces in PLM 360.

The Sync Service is a Windows Service that does the actual work.  It reads data from Vault, connects to PLM 360, determines what needs to be updated and makes the changes to PLM 360.

Here is the basic order of operations:

1. User releases an item in Vault.
2. Vault server adds a job to the job queue indicating that an item has changed.  This step does not happen immediately.
3. Sync Service reads the job off the job queue and performs the necessary updates in PLM 360.  This step also does not happen immediately.

The Job Queue is pretty central to how PLM 360 Sync works.  The queue tells the Sync Service which items may need to be synchronized.  It also is a repository for errors that may happen.  It’s very important that there be a way to re-do a sync in the case of a failure.

Even though the job queue is used, Job Processor has nothing to do with PLM 360 Sync.  The Sync Service talks directly to the job queue, so Job Processor is not required.  Sync Service and Job Processor are completely orthogonal to each other.  The actions of one do not affect the actions of the other.  For example, if Job Processor is busy with 1000 DWF create jobs, the Sync Service runs as normal.  It does NOT have to wait for the 1000 DWF jobs to complete.

---

Additional Resources

Under the Hood - Brian Schanen goes through the configuration steps.
Design and Motion - Scott Moyse provides his insights. 
PLM 360 Discussion Group - Give us your feedback.
Cracking the Vault - Where to get the tool.

Vault is “Insanely Configurable” Too 2

Welcome to part 2 of my articles on custom objects.  In part 1, I went over the UI features.  Now I will go over the API features, which is where the real fun begins.  If you want some sample code, have a look at my Discussion Thread app.  But first... terminology.

---

Terminology

Custom Object and Custom Entity

These are the exact same things.  Custom Object is the name we use in the UI.  Custom Entity is the name we use in the API.

Entity Class and Custom Entity Definition

I’ve talked before about entities.  As you probably guessed, custom entities are entities.  What can be confusing is that all custom entities belong to the same Entity Class, which has “CUSTENT” as the ID value. 

Custom Entity Definitions can be considered a sub-type of CUSTENT.  So if I create custom entity definitions called “Foo” and “Bar”, they are both part of the CUSTENT entity class. 

This distinction is important because a lot of things operate on the CUSTENT level.  For example, FindCustomEntitiesBySearchConditions will search across custom entities of all sub-types.  If you want to scope the search to a specific sub-type, you can do that with a search condition.

Permissions is another thing that operates on the CUSTENT level.  If a user has the Custom Object Editor (Level 2) role, it applies to all custom entity sub-types.  If you want each sub-type to have their own permissions, you can use the ACL settings.

---

API Features

Custom Commands
Your custom commands in Vault Explorer can be bound to specific custom entity sub types.  That way the command is only visible when an object of your custom object sub-type is selected.  Also, you can add commands to the context menu for your sub types.

To make use of this feature, create custom commands just like normal.  The only difference is that you set the navigation type to a new SelectionTypeId which points to your sub-type.

Custom Tabs
You can define your own Vault Explorer tabs which only show up when your custom entity sub-type is selected.  You also have the option of hiding the default tabs.

Just like with custom commands, you create a new SelectionTypeId to hook the tab to your sub-type.

New and Delete Override
You can take over the New and Delete commands in Vault Explorer so that your code gets called instead of the default.  The IExtension interface has a new method, CustomEntityHandlers.  Pass back a new CustomEntityHandler, which has New and Delete events that you can hook to.

Update Lifecycle State - Web Service Command Event
Through the CustomEntityService, you can hook to the GetRestrictions, Pre and Post events whenever a custom entity changes lifecycle state.  These hooks apply to all CUSTENT state changes regardless of sub-type.

Update Lifecycle State - Lifecycle Event Job
Through the Lifecycle Event Editor you can configure the server to fire jobs when custom entities change lifecycle states.  These jobs fire on sepecific state transitions regarless of entity type or sub-type.

System Name vs Display Name

This scenario should be familiar if you have used the Vault API.  Your code relies on a specific configuration which you need to look up in your code.  For example, you have a UDP and your code needs to look up the ProdDef object.  How do you do it?  What piece of information do you use?

Let’s start with the completely wrong answer.  The ID value should not be used.  It’s not consistent between Vaults, you don’t know the value ahead of time, and the value may change when you migrate to the next Vault release.

The Display Name is usable in certain cases, but is not bullet proof.  The main problem is that the display name can be changed through the Vault settings.  If your app is specific to a single Vault installation, then you can sometimes get away with this approach.  If you are developing something for a mass market, then you can’t depend on the display name.

System Name is the most solid thing to use.  Once this value is set, it can’t be changed.  The Vault admins can change the display name all they want, the system name will not change. 

In Vault 2012 and earlier, the server would create the system name for you using a randomly generated GUID.  So there is no way you could know that value when you are writing your code.

In Vault 2013, we updated most of the Add functions so that you pass in the system name.  This way, you can know ahead of time what the system name is.  You can store that value in you code and be secure in the knowledge that it will locate the correct object.

When calling an Add function, you can’t set the system name to be whatever you want.  It must be a GUID in the format (lower case) xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.  If you have a .Net Guid object, you can just call ToString(“D”) to get that string.  Even though your system name will not be human readable, but it will be reliable.  And you are safe from naming collisions (as long as people don’t just cut and paste code from the sample apps on your blog).

Another caveat to this architecture is that you need to add the object through the API.  If you do it through the UI, then the client will give it a random system name.

Vault is “Insanely Configurable” Too

It looks like Brian Schanen is only blogging about PLM 360.  So that leaves it to me to explain the Custom Entity feature in Vault Professional 2013.  It’s probably better this way.  Although you can create Custom Entities without API programming, it’s like setting off fireworks in the daytime.  You just don’t get the full effect.

I don’t think I’ll be able to cover everything in just one article, so I’ll just focus on the UI aspects for today.  In the coming weeks, I’ll dig deeper into the API details.  And if your nose is detecting a nice meaty aroma, that’s the smell of a sample app coming soon.

You can manage your custom entities through the Vault Settings dialog.  You may notice that there is a new tab for Custom Objects. (NOTE: custom entities are called “custom objects” in the UI).  This tab is mostly empty.  The only thing you can do is click the Configure button, which lets you manage the custom entity definitions.  You can think of a custom entity definition as a class definition in .NET or a table definition in SQL.

If you create a new definition, you’ll see that there are various fields to set.  There the display name and plural display name determines how the objects will be shown to the user.  The security defines the default ACL for new objects.  The icon is the image that will get displayed next to your objects.  This is an .ico file, so you can define multiple sizes.  We recommend 16x16 , 32x32, 64x64, or 128x128.

After a custom object definition is created, you need to restart Vault Explorer to see it properly.

Our custom entities get their own section in Vault Explorer.  If we go to one of these sections and create a new object, you will see the default New behavior, which is pretty basic.  All you can set is the name for the entity.  In another post, I’ll show you how to override this dialog.

Now we have our object, but I’m guessing you are going to want to set more than just the name.  To configure things like properties, category, you need to go to the property and category sections of Vault Settings.  You will see that Custom Object capability has been added to these settings.  Through the category configuration you can set things like property definitions and lifecycle.

It’s also a good idea to set up a rule to move your custom objects to their own category upon creation. 

The last thing I want to go over is the default tabs.  The Contents tab works like the Uses tab for files; it shows the children entities.  The Were Used tab works the same way but it identifies parents.  To set these relationships you use the Link feature.  Just copy an entity and “Paste as Link” into the Contents tab of your custom entity.  You can link your custom object to and from all the major entity types (files, folders, items, change orders and custom entities).

Hopefully you are starting to see the possibilities, and I’ve only gone over the standard UI behavior.  The real fun begins when we get into the API features in part 2.

Web Service Invoke Events

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....

Vault Explorer Command Events

Vault 2012 was a very eventful release for the API in the sense that we added a 3 event engines for you to hook to in your programs.  I've already talked about Web Service Command Events, which is the most complex of the 3.  Now let me switch to the most simple type, Vault Explorer Command Events.

Whenever any UI command is invoked in Vault Explorer, it will fire a pre and a post to anyone that subscribes.  The UI command is basically everything in the main menu, toolbars, and context menus.  In your handler, you get passed in the key string for that command.  And that's it.  You don't get the selection context and you don't get any information about what happened during the command.

It told you it was simple.   But don't worry, I can stretch this out to a full article.  Just because a feature is simple doesn't mean it's useless.

---

Here are a couple of uses to get things started...

Use #1:  Cache clearing

Sometimes I find myself building up a cache in my custom command.  For example, I'll need to read all the file Property Definitions.  I don't want to read these objects each time my command is invoked, so I save the data in memory.  But what if I want to keep my cache up-to-date?  I just need to check for the Refresh or Admin Settings command and clear the cache at that point.

Use #2:  Event combo

Just like in video games, you make use of combos to get the best results.
Web Service Command events are good at knowing what work is being done but only in isolation.  They don't know what overall command is being done.  Vault Explorer Command events are just the opposite.  If you combine the two, you have a fairly complete picture.

Here is the timeline of a Copy Design operation that creates 3 files.  The top blue lines are the Vault Explorer events, the bottom blue lines are the web service events, and the red lines are the web service function calls. 

We can make good use of all these events.  For example, you can send out an email report after a copy design is completed.  Here is how you would do it:

1. In the Vault Explorer pre event for Copy Design:  Create a new List.
2. In the DocumentService AddFile post event:  Add the File to your List.
3. In the Vault Explorer post event for Copy Design:  Use the entries in the List to send out the email report explaining which files were added via Copy Design.

Now you're playing with power!  

---

Cheat Code: 

You will probably want to know the key string values for the various UI commands.  This information isn't documented anywhere.  But here some code that you can use to build your own dev app that displays the key value each time you invoke a command in Vault explorer.

// A simple dialog with a label to display the commands public partial class TextDialog : Form {     public string LabelText     {         set { m_label.Text = value; }     }     public TextDialog()     {         InitializeComponent();     } } // In your IExtension class TextDialog m_commandBox; public void OnStartup(IApplication application) {     application.CommandBegin += new EventHandler<CommandBeginEventArgs>(application_CommandBegin); } void application_CommandBegin(object sender, CommandBeginEventArgs e) {     if (m_commandBox == null)     {         m_commandBox = new TextDialog();         m_commandBox.Show();     }     m_commandBox.LabelText = e.CommandId; }

' A simple dialog with a label to display the commands Public Partial Class TextDialog       Inherits Form       Public WriteOnly Property LabelText() As String             Set                   m_label.Text = value             End Set       End Property       Public Sub New()             InitializeComponent()       End Sub End Class ' In your IExtension class Dim m_commandBox As TextDialog Public Sub OnStartup(application As IApplication)     AddHandler application.CommandBegin, AddressOf application_CommandBegin End Sub Private Sub application_CommandBegin(sender As Object, e As CommandBeginEventArgs)       If m_commandBox Is Nothing Then             m_commandBox = New TextDialog()             m_commandBox.Show()       End If       m_commandBox.LabelText = e.CommandId End Sub

Coming soon:  Web Service Invoke Events (aka. God Mode)

Entities and Behaviors

Last year, I tried to explain the Entity concept in the Vault API, and I never felt that I did a good job.  Read the article at your own peril.  In true software developer form, here is the hotfix to my bug-filled earlier article.

---

There are 2 concepts in the Vault API:  Entities and Behaviors.  The two concepts are intertwined; you can't describe one without describing the other.

An Entity is an object that can have behaviors on it.
A Behavior is a feature that can be applied to entities.

The driver behind these concepts is something every programmer should already be familiar with: re-use.  By having features that can work with multiple object types, Vault has less code, a cleaner API, greater stability, and so on.

Files and Folders are examples of entities.  Properties and Categories are examples of behaviors.  Not every object in Vault is an entity, and not every feature is a behavior.  It's also important to know that a given entity type may not support every behavior. 

For example, here is a table explaining which entities have which behaviors in Vault Professional 2012.

	Property	Revision	Category	Security (ACL)	Lifecycle	Ownership (replication)
Files	*	*	*	*	*	*
Folders	*		*	*		*
Items	*	*	*	*		*
Change Orders	*					*
Forum Message	*
Reference Designator	*

Note:  Even though Items and Change Orders have lifecycles, the feature cannot be applied to other entity types.  The File lifecycle engine is the only one that is entity-based.

---

The web services in the API is structured according to the entity/behavior model as shown in the table below. 

Entity Services	Behavior Services	Other
Change Order Service Document Service Document Service Extensions Forum Service Item Service	Behavior Service Category Service Property Service Replication Service Revision Service Security Service	Admin Service Knowledge Vault Service Information Service Job Service Package Service Win Auth Service

The behavior services are easiest to spot because the functions have parameters like "entityId" and "entityClassId".  In the entity-based services, the functions usually take more specific IDs, such as "fileId".  Let's focus more on the terminology used in the behavior services.

EntityId - Each entity has an ID that uniquely identifies it.  Usually this is the "Id" property on the object.  For example:  File.Id

EntityMasterId - If the entity can be versioned, then there is a master ID, which is used to refer to the entire collection of versions.  Usually this is the "MasterId" property on the object.  For example:  File.MasterId
If a function is asking for an EntityMasterId, but the object doesn't have one, just pass in the ID value.  For example:  Folder.Id

EntityClassId - This is a string value containing the type name.  Call AdminService.GetServerConfiguration() to see the list of legal values.  For your convenience, I will list them out here.

Entity type	EntityClassId value
File	FILE
Folder	FLDR
Item	ITEM
Change Order	CO
Reference Designator	ITEMRDES
Forum Message	FRMMSG

What Makes a "Vault Extension"

The Vault 2012 API has a formalized concept of an Extension.  In the Vault 2011, the concept was there, but there was no clear set of rules or behaviors.  By defining things more clearly in 2012, the concept is easier to understand, and the groundwork is laid for future API enhancements.

The Definition:
A Vault Extension is a component that doesn't run on its own, but gets loaded by the Vault framework.
Currently, there are 3 types:  Vault Explorer extensions, Job Processor extensions, and Web Service Command extensions.

The Rules:
There is a common set of rules that all extensions must follow.

• They are all .NET assemblies.
• They must have values for 5 specific assembly attributes:  AssemblyCompany, AssemblyProduct, AssemblyDescription, ExtensionId, and APIVersion.
  The first three are put in by Visual Studio.  The last two are from the Vault API.
• They must be deployed with a .vcet.config file.
• They must be deployed to a folder under %programData%\Autodesk\Vault 2012\Extensions.  1 Extension per folder.
• They must have a single, public class that implements the interface for that extension type.

The interfaces:

The interface implementations are important because the Vault framework uses that class as the entry point into your customization.  The interface is how the Vault sees your code, and Vault is not concerned with anything underneath.

Vault Explorer Extensions:

Description:	Vault Explorer extensions are for extending the Vault Explorer client application.  Commonly used for things like adding commands and tab views.
Interface:	Autodesk.Connectivity.Explorer.Extensibility.IExtension
ExtensionType in the .vcet.config:	VaultClient
Loads in:	Connectivity.VaultWkg.exe Connectivity.VaultCollaboration.exe Connectivity.VaultPro.exe

Job Processor Extensions:

Description:	Job Processor extensions are for extending the Job Processor application.  Commonly used for creating job handlers for custom job types.
Interface:	Autodesk.Connectivity.JobProcessor.Extensibility.IJobHandler
ExtensionType in the .vcet.config:	JobProcessor
Loads in:	JobProcessor.exe

Web Service Command Extensions:

Description:	Web Service Command extensions are for responding to events from any Vault client running on a computer.
Interface:	Autodesk.Connectivity.WebServices.IWebServiceExtension
ExtensionType in the .vcet.config:	WebService
Loads in:	Any application using Autodesk.Connectivity.WebServices.dll on that computer.

Mixing and matching:
It's possible to have a DLL to implement more than 1 extension type.  In fact, this works really well with the Job Processor and Vault Client extension types.  Mixing the Web Service extension type with other types is trickier because you don't know the application context.  As a result, the DLLs from the other extension type might not be available to the running application.  
Job Processor and Vault Client work well together because they have the same working folder, and therefore, have access to the same DLLs.

Job Queue Priority

Some people have noticed that there is a new job queue column called Priority.  This is an API feature, at least for now.  So you have to use custom programming if you want to make use of this value.  From Vault Explorer, you can see the value, but you can't do anything with it.

Let me start by explaining how NOT to use the priority feature:

You have 3 tasks (A, B and C) which you want to complete in order.  So you queue up all three jobs at once, giving A a priority of 1, B a priority of 2 and C a priority of 3.  Now you are guaranteed that they will get executed in order, right? Wrong Because there may be multiple Job Processors running and because Job Processors can be specialized by type, you are not guaranteed the order.  It's technically possible for C to get executed first, with B second and A last.  Or any other permutation.

Now let's move on to the intended use:

You are doing a batch operation using the job queue.  This operation will take several days, involving thousands on jobs on the queue.  In the meantime, the vault is still in use by end users.  You want don't want the batch operations to interfere with user-driven operations.  So you queue the batch jobs with a low priority while user jobs get a high priority. Correct The priority feature lets you move jobs to the front of the line if needed.  Likewise, you can indicate jobs that should run in the background.

The way it works is pretty basic.  The priority value is an integer.  The lower the number, the higher priority, with 1 being the highest possible priority.  When the Job Processor reserves a job, it will reserve the job with the lowest priority for a type that the Job Processor supports.  If there are 2 jobs with the same priority on the queue, then the first one added is the first one processed.

Jobs with types that are not supported by a Job Processors are basically invisible to that process.  So the priority is based on only visible jobs.  For example, the Job queue consists of job A (priority 1) and job B (priority 7).  The Job Processor supports only type B.  The result is that job B is read off the queue next.  Job A will not get processed by this Job Processor since it is a unsupported type.

When deciding what priority your custom jobs should have, it helps to have some context.  Vault Explorer and the CAD plug-ins use 10 as the default priority value for jobs.  Autoloader uses priority 100 when it queues jobs.  Jobs triggered automatically via a lifecycle state change are also queued as priority 100.

Once a job is on the queue, it's priority cannot be changed.  The workaround is to remove it from the queue and re-add it with a different priority.  This can easily be done through the API, but there is currently no UI command to do this task.