How to make EA (Enterprise Architect) documentation available to those without EA using EAPtoHTMLJan 28, 13
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:
- Extract the Diagrams from EA (These house the majority of the information people want to see)
- Provide some mechanism to search the Diagrams
How I actually implemented this solution was:
- Extract the diagrams to PNG files
- Extract some searchable metadata to excel
- Import metadata document to a new SharePoint list
- Upload the PNG files to some location on a SharePoint list
- Add a calculated column that has an URL to the corresponding diagram
- Modify the list to show all items
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:
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.
- 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.
- 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.
Hopefully this helps someone. 😀
For some EA stuff:
- 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)
- For some DateTime formatting stuff for messages:
- For my recursive calls:
- C# Operator References! (because I forget simple things sometimes 😁):
- Serialization stuff (needed for caching data during testing):
- Anonymous methods and functions:
- 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://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)