What Does This Addin Do?

 This Addin “listens” for Command Button events to be “fired” from data cards in PDMWorks Enterprise.  This could be File Cards (i.e. for existing files or folders) or Input Cards (i.e. for new files or folders).  If the command string of the Command Button matches our criteria, then the Addin will pull the next Serial Number from a Serial Number sequence in the vault.  The best thing about the Addin is that the Serial Number sequence name is specified as part of the command string.  This means that the Addin can be configured very easily by a non-programmer to run on any number of different Serial Number sequences.  In other words, our Addin is Extensible (sorry, I couldn’t resist). 

 Why Do I Need A Custom PDMWorks Enterprise Addin For Handling Document Numbers When PDMWorks Enterprise Already Has “Serial Numbers” Functionality That Handles This?

 PDMWorks Enterprise is a great tool and the Serial Numbers functionality is very useful.  However, as implemented in PDMWorks Enterprise, the Serial Numbers are kind of wired directly in to the system and don’t allow much flexibility in terms of when and how they are used.  You either set your part number to be populated from the Serial Number sequence or you don’t.  There is no “let’s do it this way for this case and another way for this other case.”  By writing a very simple Addin, we can set up our data cards to pull Serial Numbers when the user pushes a button of our choosing.  In other words, with a small amount of work, we allow the user to choose when to use a given number sequence.  I am tempted to say something here like “…and choice is good…” but I realize that not everyone will agree on that.  So I have decided to leave the freewill debates up to philosophers and priests while I tackle the PDMWorks Enterprise API.

I Don’t Want To Learn Anything, Can I Just Have The Finished Addin?

Yes.  You may download the compiled Addin from here.   However, you will still need to see the section below on deploying the Addin. 

Disclaimer:  No warranty is either expressed or implied for this Addin and the Addin is not in any way supported.  By downloading the Addin, you assume all responsibility for the Addin.How Hard Is This To Do?

Writing a PDMWorks Enterprise Addin is surprisingly easy although deploying them correctly can sometimes be a challenge.  This article does assume though that you understand the basics of  creating Addins with Visual Basic.NET.  If you haven’t yet mastered the basics of creating Addins with VB.NET then you can brush up with the fairly decent tutorial that is included in the PDMWorks Enterprise API guide. 

What Version of PDMWorks Enterprise Was This Addin Written For?This Addin was written for and compiled against PDMWorks Enterprise 2007.  However, you should be able to recompile it against PDMWorks Enterprise 2008 without much trouble.

 What Development Tools Do I Need To Write Such An Addin?

Visual Studio 2005 Standard is definitely sufficient for creating COM addins and you can usually pick it up in the US for $300.  Currently, that would be like 5 Euros for you guys across the ocean.    I haven’t tried it, but it may be possible to use the Visual Basic 2005 Express (aka “the free version”) to write this by manually adding the COMVisible<…> tags where appropriate in the Addin.  Although I am too lazy to install VB 2005 Express to test this out, I did go ahead an put the COMVisible<…> tags in their appropriate (at least by my reckoning) places.  If anyone tries this, I would be thankful if you could post your results for posterity.

Where Can I Find The Source Code For This Addin?

You can find the Project for this Addin, with all source code, in a zip file here.

 How Do You Do It (High-Level)?

1.  Follow the steps in the PDMWorks Enterprise API Guide to create a generic PDMWE Addin.  Note:  Yes I know this is cheating but it is getting late and I am starting to get pretty sleepy so I hope you will forgive the shortcut.  
2. Add a Serial Number sequence to your PDMWorks Enterprise vault.
3. Create a Windows Form in your application that will be used to provide the generated number back to the user.
4. Create or edit a datacard such that it has a Command Button to call the Addin.
5. Replace the generic OnCmd method in the generic Addin created at step 1 with an OnCmd method that accesses the next number in Serial Number sequence that is specified by the Command Button.
6. Debug endlessly until it “works” (on your machine)
7. Enlist a co-worker to test the Addin for you on their machine.  Note:  You can blame them later for inadequate testing coverage if the Addin doesn’t work properly : )

How Do You Do It (Detailed)?

1. Follow steps in API guide for creating a generic Addin.  (Sorry, you are on your own for this step) 
2. Add a Serial Number sequence (or two or three or four …) to your vault.  You will need to login as an administrator to do that. 
   • Note:  Just expand your PDMWorks Enterprise Vault node in the PDMWorks Enterprise Administration tool and then right-click on the “Serial Numbers” item in the tree.  You can then add as many serial numbers as you need.  I decided to create four in my example to handle the case where different departments number their documents differently.
3. Create a Windows Form in your application that will be used to provide the generated number back to the user.  In this example, the form is already created for you. 
4. Create or edit a datacard such that it has a Command Button to call the Addin.  You will need to set the Command type for the button equal to “Run Add-in.”  Also, notice the string in the “Name of add-in:” text box.  The string has the format of “Autonumber:<Serial Number sequence name>.  “Autonumber” is used to tell our Add-in which command buttons “belong” to it and the Serial Number sequence name tells our Add-in which Serial Number to pull the number from.  Make sure you save your changes.
5. Replace the generic OnCmd method in the generic Addin created at step 1 with an OnCmd method that accesses the next number in Serial Number sequence that is specified by the Command Button.  You will want to modify your error messages to be more user-friendly than mine before deploying your version of the Add-in.  In the interests of time, I opted to simply write out the exceptions to strings and return those, in their entirety, in messageboxes to the user.  This is okay for a blog article but probably not okay for production.
6. Debug endlessly until it “works” (on your machine)
   • There are detailed instructions in the PDMWE API Guide on how to debug an Add-in.  Oversimplifying, you just right-click the “Add-ins” item and then select “Debug Add-ins.”  You will then browse to your top-level assembly (.dll file).  When debugging, you do not need to specify the files referenced by your assembly (.dll file). 
7. Deploy the Addin
   • Right-click the “Add-ins” item and then select “Open.”  You will then browse to your top-level assembly (.dll file) AND its dependencies.  When running in Open mode, you DO NEED to specify the files referenced by your assembly (.dll file).  In this case, your top-level assembly (NumberGenerator.dll) references only Interop.EdmLib.dll.  This is the .NET wrapper for the PDMWorks Enterprise COM Library.
   • You will see a message telling you that you will have to Restart your machine any time you add a new version of your Add-in to the vault.  Note:  This is a real requirement and can cause much grief when you start developing applications that utilize numerous assemblies.
8. Test it “one more time” just to be sure.  By pressing the “Engineering Doc#” button on the File Card in the example below, I am able to receive a message from the Add-in telling me that a new number has been generated and that I can copy the number to the clipboard by selecting the “Copy” button on the form.  Note:  You could write to the file variable instead of the copy/paste method but it would not work for Input Cards as there is not yet a file on which to access variables.
9. 

Good luck.  Let me know if this article was helpful.

If you enjoyed this post, make sure you subscribe to my RSS feed!