How to make EA (Enterprise Architect) documentation available to those without EA using EAPtoHTML

Recently I have been using a software product from Sparx Systems called Enterprise Architect. I (and I believe most people) call it EA for short. You can read about it here.

I have enjoyed working with it for the most part. It seems to do a great job for what it is. I have the benefit of coming into an environment where we have a lot of documentation in EA already. Unfortunately none of it is really getting updated due to licensing but my team (and Enterprise Architecture group) is still utilizing it and updating it. The issue we have had is how to continue to work and update EA (at least for the existing solutions documented within it) and still provide that documentation to folks without EA. EA licenses are run in the hundreds.

My solution for this was to:

1. Extract the Diagrams from EA (These house the majority of the information people want to see)
2. Provide some mechanism to search the Diagrams

How I actually implemented this solution was:

1. Extract the diagrams to PNG files
2. Extract some searchable metadata to excel
3. Import metadata document to a new SharePoint list
4. Upload the PNG files to some location on a SharePoint list
5. Add a calculated column that has an URL to the corresponding diagram
6. Modify the list to show all items
7. Implement JavaScript to search the SharePoint list page as I documented here.

During this process I wrote a little app and uploaded it to CodePlex. I called it EAPtoHTML as it takes an EAP file (this is an EA project file) and outputs a collection of PNG files and an index.html file with a bunch of keywords to search. I compressed a lot of words to make the keywords list shorter for a basic text search. So count, encounter, countered, and encountered would all be squished down to encountered. This isn’t ideal for everyone, but in the code you can simply remove the part of the code that ‘collapses’ the keywords and do something else with it if you want to actually put it into a real table with all of the words. You could also modify the extraction routine to get ‘more’ text. I just pulled the name and the notes from all of the objects in question as that seemed to have most of the keywords people would search for. You do lose unique combinations of words, but that trade-off seemed to work for my purposes/consumers. Ideally, if I get some time, I would like to go back and just hide the keywords column, keep the raw text, and allow searching. but this was pretty quick and dirty and worked fine.

Here is the project summary from CodePlex:

Project Description
EAPtoHTML serves a very simple purpose: Extract the diagrams from an Enterprise Architect Project file and save them as PNG files in a folder with an index.html that you can use to search for data.
Some Notes:

• There is currently no EXE download. You will have to download the solution and build it yourself to run it as it will require access to the EA Interop DLL which I am not providing as well as the LINQpad exe which I'm not providing.
  • LINQpad is free and awesome. I am only using it for formatting the results. You could use anything you wanted I just didn't want to write anything fancy and I already use LINQpad all the time.
  • EA is not free, but it's still pretty awesome for what it does. In my case (and I think many folks case) a group wants to adopt EA but then no one can see the data unless they have an EA license and since that costs money during a pilot it just puts a burden on the folks trying to adopt it as they have to continually extract data to show to people that do not have it.
• This project is really meant to show you how to do this. To use this extracted data, I personally have just extracted it to excel and then saved it to a SharePoint with a simple JavaScript search. But I wanted to put something up that would dump out some kind of results.
• When I have more time I'd like to tune the output, but I figured I would rather get it out there in case someone else just wanted to see how to get EA diagram data out.
• You can simply rename the .html index file to .xls and import into SharePoint if you want to expose it that way. I did this and then used a calculated column to build the URL to point to an uploaded copy of all of the PNG files also on SharePoint and put some JavaScript on the page to search within the list after modifying it to show all records. I had over 3000 diagrams and this worked well.

Hopefully this helps someone. 😀

Sources

For some EA stuff:

• http://stackoverflow.com/questions/1441479/automated-method-to-export-enterprise-architect-diagrams
• http://www.sparxsystems.com/uml_tool_guide/sdk_for_enterprise_architect/theautomationinterface.htm
• https://github.com/GeertBellekens/Enterprise-Architect-Toolpack/blob/master/EANavigator/NavigatorControl.cs
• https://ea-sqlapi.googlecode.com/svn-history/r4/trunk/EASQLApi/SQLApi/SQLApi/HelperMethods.cs (this one in particular helped me figure out how to track back to get the model name of a package and helped me see how some of the nesting worked in EA for the different types of objects)

C# Stuff:

• For some DateTime formatting stuff for messages:
• http://www.codeproject.com/Articles/14743/Easy-String-to-DateTime-DateTime-to-String-and-For
• For my recursive calls:

• http://stackoverflow.com/questions/61143/recursive-lambda-expression-to-traverse-a-tree-in-c-sharp
• http://blogs.msdn.com/b/wesdyer/archive/2007/02/02/anonymous-recursion-in-c.aspx
• http://blogs.msdn.com/b/ericlippert/archive/2005/08/08/recursion-part-four-continuation-passing-style.aspx

• C# Operator References! (because I forget simple things sometimes 😁):
• http://msdn.microsoft.com/en-us/library/6a71f45d(v=vs.71).aspx
• Serialization stuff (needed for caching data during testing):
• http://prashantbrall.wordpress.com/2010/08/16/linqpad/
• http://www.danrigsby.com/blog/index.php/2008/03/07/xmlserializer-vs-datacontractserializer-serialization-in-wcf/
• http://stackoverflow.com/questions/3356976/how-to-serialize-deserialize-simple-classes-to-xml-and-back
• Anonymous methods and functions:
• http://www.codeproject.com/Articles/27713/Local-Recursion-with-Anonymous-Methods-and-Simple

Keywords:

• http://codereview.stackexchange.com/questions/11254/find-most-occurring-word-in-a-txt-file
• There were actually a *lot* of other articles I read regarding doing word search and matching. But the one above actually helped. I left this section here because deciding how to collapse words like count, counter, countered, encounter and encountered all into just ‘encountered’ for compressed searchability was a big pain. I’m not sure my way I is the ‘best’ but I liked it and it reduced the size of my data a ton and still made the items searchable pretty easily.

Outputting to LINQpad

• http://stackoverflow.com/questions/10213411/how-to-export-linq-result-to-excel-just-like-linqpad
• http://stackoverflow.com/questions/10121899/linqpad-outputting-into-anchor-to-use-title
• http://mark-dot-net.blogspot.com/2012/09/screen-scraping-in-c-using-linqpad-and.html (I used this when I experimented with modifying the default dump from LINQpad)
• http://mbraak.github.com/simple-data-grid/#api-columns (How I wanted to tweak the output plus adding a search)

For doing searching on SharePoint (which is where I ultimately put *my* data)

• http://blog.pathtosharepoint.com/2008/09/01/using-calculated-columns-to-write-html/