It's All Just Ones and Zeros

Q-Tools and Watch Folder 2013

For this post, I bring you two whole apps.  I’ve updated Q-Tools and Watch Folder for Vault 2013.  Technically the 2012 versions can still work with Vault 2013 server, but there were a few optimizations I wanted to do using the new API features.

---

Q-Tools 2013

For Q-Tools, the feature set is the same as before, but I make use of the new Job.IsOnSite parameter to determine if a job needs to be rerouted or not.

Here is the full feature list:

• Logging - Issues are logged to a text file.
• Stale Job Detection - Jobs on the queue too long can be considered an issue.
• Email Reports - Issues can be emailed to one or more recipients.
• Queue Cleanup - Jobs with issues can be automatically removed from the queue.
• Queue Forwarding - In multi-site and multi-workgroup environments, jobs can get routed to a single site.

Requirements:
- Vault Workgroup/Collaboration/Professional 2013
- Job Server feature enabled
Click here to download the application
Click here to download the source code

Click here for Q-Tools 2012

To setup:

• Designate a computer on the network that the Q-Tools service should run on.  Only 1 Q-Tools can be running for a given Vault deployment.
• Run the installer.
• Go to the installation folder and update the settings.xml.  The XML comments will explain this step.
• Run the Q-Tools service.

Migrating from Q-Tools 2012:

• Actually I don't recommend migrating.  The 2012 Q-Tools version should work fine with the Vault 2013 server. 
• If you still want to migrate, it should be fairly easy.  The Settings.xml has not changed.  I recommend making a copy of the XML file, uninstall Q-Tools 2012, then install Q-Tools 2013.

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

---

Watch Folder 2013

Although the feature set is the same, the setup is much easier.  No longer do you have to configure Windows tasks to add notification jobs to the queue.  Using the new features on IJobHander, the jobs are added from JobProcessor plug in.  Right before JobProcessor goes idle, Watch Folder puts a new notification job on the queue.  That way new files are checked every time JobProcessor cycles.

In case you aren't familiar with it, Watch Folder is an app that allows you to "watch" a set of Vault folders so that you receive email notifications when files get added or updated in those folders.

Requirements:

• Vault Workgroup/Collaboration/Professional 2013
• Job Server enabled
• An SMTP server somewhere on the network

NOTE:  This isn't something you can just download and run.  The Vault administrator needs to set up some server components before this feature can be used.

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

Click here for Watch Folder 2012

To use

For Vault users, download the application and run the installer.  Just make sure that the administrator has set up the Vault environment first.  Next, start up Vault Explorer and right-click on a folder that you want to watch.  Select the Watch Folder command and decide how frequently you want notifications.

For Vault administrators, download the application and run the installer.  Next follow the instructions in the readme file in the install folder (%ProgramData%\Autodesk\Vault 2013\Extensions\WatchFolder).

Notes:

• A watch on a folder will automatically apply to any sub-folders.
• Removing a watch will also remove watches on sub-folders.
• You can't have an immediate watch and a summary watch on the same folder.  Setting a folder to one type overwrites the existing setting.
• You need to be at least Document Editor (level 1) in order to set up a watch on a folder.
• You need to have a valid email address in your Vault user settings.
• The contents of the email can be customized by the Vault administrator.  See readme file.

Migrating from Watch Folder 2012:

• WatchSettings.xml now needs a Vault username and password.  Everything else is the same, so you can just add <Vault_Username> and <Vault_Password> tags to your existing config file.  The Vault user must be able to add and delete jobs from the queue.
• All the other settings files from R1 can still be used, just copy over WatchCollection.xml and WatchEmailBody over to the install folder.

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

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

New Blogs from ADN

The Autodesk Developer Network has put out a bunch of new blogs recently.  These blogs cover the APIs for all Autodesk products.  There you will find tips, tricks and all the sample code you can eat.  The Vault stuff can be found in the Manufacturing  DevBlog.  There are also DevBlogs for AEC, AutoCAD, and infrastructure.

The Manufacturing DevBlog already has several Vault articles you may want to read:

• Using Vault API to Upload Document Hierarchy
• Create Command for the Custom Entity in Vault
• How to use the Vault API from C++ or VB 6?
• How to handle "Error 300 - BadAuthenticationToken"?
• Can I use Vault API to edit a file?

---

This is also a good time to remind everyone of the ADN DevCamps which are starting up in a few weeks.  Registration is still available for the AEC DevCamp and Manufacturing DevCamp.  I’ll be teaching Vault API classes at both events, so hopefully I’ll see you there.

Thumbnail Optimization

One of the optimizations in Vault 2013 is the use of JPEG as the format for storing thumbnails.  Previously, the format used by the CAD file was stored in the database.  For example, Inventor uses the metafile format, which is usually much bigger than a JPEG when at thumbnail size.  Regardless of what format the file’s thumbnail is, the Vault 2013 Server converts it to JPEG when storing it in the database.

What this means for the Vault developer is that you have to handle 2 possible image formats if you want to render thumbnail data.  You need to handle the metafile format for files added in Vault 2012 and earlier and you need to handle the JPEG format for files added in Vault 2013.

So here is the updated code for you to use. 

RenderThumbnailToImage.cs
RenderThumbnailToImage.vb

Note:  This code is more optimal than the code in one of my older posts.  The old code worked by trying one algorithm then trying the second algorithm if the first one failed.  The new code detects ahead of time what the image format it.

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.

Lifecycle Event Job Parameters

File this post under: “Things that Doug should have put in the SDK documentation.”
I’m not sure how this information was omitted, but I apologize.

Anyway, when jobs are created from a lifecycle state change, the job will have a specific set of parameters depending on the entity type.  Here is the list of parameters.

---

Vault 2012

• Files
  • FileId - The ID of the updated file.
  • LifeCyleTransitionId (sic) - The ID of the lifecycle transition that the file just went through.
• Items
  • ItemId - The ID of the updated item.
  • FromStateId - The state that the item started in.
  • ToStateId - The state that the item ended in.
• Change Orders
  • ChangeOrderId - The ID of the updated change order.
  • FromStateId - The state that the change order started in.
  • ToStateId - The state that the change order ended in.
  • ActivityId - The activity defining the transition.

---

Vault 2013

The main change here is that the file lifecycle engine in 2012 has been expanded to other entity types.  So file-specific parameters have been changed to the more generic entity concept.

• Files, Folders and Custom Entities
  • EntityId - The ID of the updated file, folder or custom entity.
  • EntityClassId - They type of entity that was updated.
  • LifeCycleTransitionId - The ID of the lifecycle transition that the file just went through.
  • LifeCyleTransitionId [deprecated] - Use LifeCycleTransitionId instead.
  • FileId [deprecated] - Use EntityId instead.
• Items
  • ItemId - The ID of the updated item.
  • FromStateId - The state that the item started in.
  • ToStateId - The state that the item ended in.
• Change Orders
  • ChangeOrderId - The ID of the updated change order.
  • FromStateId - The state that the change order started in.
  • ToStateId - The state that the change order ended in.
  • ActivityId - The activity defining the transition.

Discussion Thread app

Change Orders have a feature where you can have a discussion threads on each object.  I thought it would be neat if you could do the same thing with files and items.  I also promised a sample app using Custom Entities, so here it is.

---

Features:

• Add discussion threads to existing items and files.
• Files and items can have multiple threads on a single object.
• Respond to postings and see the whole discussion history.
• Works even if the items and files are released.
• App will configure Vault when the admin first runs it.  No need to manually create the custom object definition, UDP, etc.

---

Requirements:

• Vault Professional 2013

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

---

To Use:

Run the install and start Vault Explorer as an administrator.  You should be prompted to run a configuration.  After the configuration is complete, restart Vault Explorer.  You should now have the Discussion Thread custom object.

All users who want to make use of this app, should have the Custom Object Editor (Level 1) and Custom Object Manager (Level 1) roles.

When you want to add a discussion to a file or item, select the object and right click.  Select the New Discussion Thread command to create the new discussion.

 
To respond to the thread, use the Discussion tab.  Select the posting you want to respond to, and hit the Respond button in the tab.

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

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.