Intro to Creating a MDG File

One of the great things in EA is the possibility to extend standard UML modeling by usage of so-called MDG (Model Driven Generator) files. With these you can - in short - add own diagram types offering your own sets of stereotype elements and connectors (with individual shapes) in customized tool boxes. Here is how you can approach the generation of such MDG files.

Overview

Having an individual MDG is a must for large projects. Most domains have a specific language that needs to be reflected as good as possible via UML. Whenever you start setting up a MDG you should at least have your domain analysis in a final state. This domain analysis needs to tell you

• which domain objects exist
• which of them are important (need a special optical representation) and
• what diagrams need to be created.

The latter will usually evolve during the usage of the MDG, thus you need to be prepared for iterations. Changes in the MDG are crucial and need to be thought over thoroughly.

Now here are the steps you need to follow to create your first MDG. The attached model is not a multi-part tutorial but keeps the initial and the final state. You should however be able to walk along in your own model in parallel using the sample as reference.

You might notice later that when I created the sample I actually did not have a specific domain in vision when I started - except: something with cars which can be understood by most people. So the real domain evolved during creation of the tutorial. It turned out that the domain is a custom car manufacturer.

This sample has been created with EA 8.0 (the most current build at time of creation). However, it should work with most pre 8.0 builds¹ as it does not contain too awkward constructs. As a precaution please note that starting with V9 or so EA has introduced a couple of "wizards" for MDG creation. I did not update this tutorial and honestly must say that I don't like most of those "wizards" since many are just the sorcerer's apprentice.

The Profile

The creation of a MDG will need a couple of iterations before it can be used in production. Below the third iteration is that where you can start going life.

Iteration 0

The most important part is the profile. This tells you which model elements are available for the modelers in EA. These model elements, once present, can be created by drag and drop or via the blank-context menu. So lets first start creating that.

I simply copied the whole diagram Model.PIM.Domain Model with a deep copy to Model.PSM.MDG.CProfile.Domain Model. You now have an unreferenced duplicate of your domain elements. I keep relations simply by name since the domain must not change. If so, something‘s rotten in the state of Denmark. Note that the name of the Profile package here is CProfile and should usually reflect the customer's domain name or brand. The stereotype must be set to «profile» so you can access the profile modeling tools inside.

Now you have all the domain elements as a copy. You might not need all of them for the profile and are free to delete unneeded stuff. Also the copied relations are actually not needed for the profile. They are however ignored for the profile itself and you also choose to leave them as they are.

First of all we need these special stereotyped elements. Edit the properties of an arbitrary element and change the stereotype to «stereotype» (you must not use the guillemets as they will be attached automatically). Now select the element on the diagram and drag/drop from the little arrow symbol. Choose Metamodel/Extend which will open a form that offers a lot of check boxes. Just select Class in the left window and press OK. That will create a «metaclass» class with an incoming «extend» relation. Change the stereotype for another element as above and select it on the diagram. Drag/drop from the arrow icon to the new «metaclass» class and select Extend. You now have two incoming «extend» relations for the «metaclass» class. Repeat until you have all elements connected.

Your profile is now ready for a first test.

A quick test/MDG structure

We now need to export the profile so it can be used later during modeling. We just want to do a quick check but it‘s wise to save the profile export in the right place. Create a folder MDG (or whatever name you like) and inside a sub-folder with the name of the Profile. More files will come later and this should be the place for the profile itself.

Right click the CProfile package and select Save Package as UML Profile. Navigate to the folder and save the profile under the name CProfile (which will get the extension .xml). Just Save with defaults.

For the quick test we import the profile temporarily via the Resources window (tricky to find like all View windows; it changed from 7.5 to 8.0² so I don‘t give the position here; or simply use Alt+6 but who can remember that shortcut?). Right click the UML Profile folder in the Resources window and select Import Profile. Choose your exported .xmi and notice the new entry CProfile. Open it and drag one of the element onto the currently open diagram. You should see a new stereotype which has has that tagged values you specified in the domain/profile. Also the tagged values should behave meaningfully. For example the Style takes the drop down entries directly from the CarStyle enumeration.

Now it is obvious what the profile is good for. Basically it provides accordingly stereotyped elements with tagged values. And much more of course but we cannot cover that here.

Your quick test is done and you can safely delete the profile from the Resources (Delete Current Profile from the context menu).

Iteration 0.5/Side note

As I am developing this sample I eventually find my domain model incomplete (as stated above). Now I have to copy paste the completed domain diagram once again needing to repeat above steps from Iteration 0. This is tedious and EA basically provides a method to do this much easier: namely by Transformation. Instead of copy/paste of the diagram I could have chosen Transform package (with the not existing 1:1 transformation, aka. duplication). In that case EA would have kept internal references and only changes would have been forwarded in the next transformation. That would have been cool: add the attribute in the domain model, transform, ready. Unfortunately I have lost my own 1:1 transformation and EA does not come with a build-in. It is not too difficult to write such a transformation, but it is once again Monty Python: A completely different story. Or: A proprietary script language.

Iteration 1

Now that the profile works basically you will likely see some more enhancements. Go back to the CProfile diagram. Select the Car stereotype and edit the attributes. Add an attribute named _image and click the ellipsis. Get the text from the final model by also clicking the ellipsis of the _image attribute and copy/pasting the source. Do the same for Motor.

Once again repeat the quick test above. Now you will notice that all Motor elements appear in red color. Cars have a decoration pattern which will change to be hollow after clicking Abstract in the element properties.

Your profile is initially done. You will definitely need to rework after a couple of days using it. Probably you will find out that you get a lot of «metaclass» elements so these should be moved to separate packages inside the profile. Also it is advisable to move the enumerations out of sight.

Iteration 2

Eventually you will have detected that for cars you will not only need stereotyped classes but also packages for grouping them. Simply add an extends relation to a «metaclass» Package and your done. Repeat the quick test and notice that a Car package now shows the icon like the Car class. I leave it to the reader to move the icon away from the awkward position it has now.

Iteration 3

You want to express that certain motors and gears fit each other. Simply you could use a stereotyped relation called "fits", based on an association. So let's create that. Add a new «metaclass» Association (to be found in the right part window now) and drag/drop a Metamodel/Tagged Value named "fits" (without quotes, of course). You might do fancy things with shape script and this relation later if you need to. Left open for your own study.

As alternative you can also express the relation via a tagged value appearing in Motor which lets you select elements of stereotype Gear. Press the space bar to select Tagged Value. Now click and draw from Motor to Gear and name the target role of the relation "fits" (see above). No idea why the quick linker does not provide the right relations. Well. I also do not grasp why the multi-select does not work here when you set the multiplicity to 0..*. The whole matter is complicated and the reader might give me feedback what's wrong here.

Quickly test it and you will see the new "fits" stereotype as well as a tagged value of the same name for a Motor class. Create a Gear element and drag the fits relation from the Resource onto the Gear. A pop-up will allow to select the Motor class and the new relation is stereotyped «fits». Note that this clumsy behavior will not occur later in the MDG. It is just for the test. Check the alternate way with the "fits" tagged value in the Motor class. The ellipsis allows navigation to just «Gear» stereotyped classes. Once again: no idea why the multiple select does not work here. Probably a brain lock in front of the keyboard.

Iteration x

You will definitely have to go through more than these few iterations. Be prepared as substantial changes to stereotypes might not always be done with a synchronization. More on that later.

Custom Diagrams

Having a custom diagram allows you to offer parts of the domain elements in different contexts. Imagine that salesmen and technicians need only those model elements they need. The salesman is not interested in screws needed for a motor and vice versa. So your primary domain analysis should also reflect the different stakeholders along with their relevant domain elements. The salesman wants to see just Cars and add basic information. So his diagram is basically a Commission view. The welding would need information about the design of the car with more technical input. This might be a Design view. The electrician would need a Cabling view. I will not go and create all of these diagram types. Only Design and Commission, but you will get the idea.

Iteration 0

Create a «profile» package CDiagram with a simple class diagram inside. Add a «metaclass» Boundary (this creates an empty metaclass element; the contents is going to change completely). Name it Diagram_Class and add two attributes: alias of type string with initial value Design and diagramID of type string with initial value DED. The alias will appear in dialogues and the ID in the upper left corner of the diagram itself.

Add a stereotype Design and draw an Extend relation from that to the metaclass.

Set up a similar tuple for the Commission diagram. You need a new «metaclass» because the attributes are different. So now you should have two tuples.

A primitive MDG file

Now it is time for creating the first MDG. Still at this stage you will not get the complete picture, so just follow the steps.

Right click the CDiagrams package and choose Save as Profile. Change the filename from CProfile to CDiagram. When you save you will have two different .xml files in the Profiles folder.

Now we start to actually create the MDG file. Choose Alt+T followed by T (I do that so often that I use this simple shortcut rather than Tools/Generate MDG Technology File...

Click Next. Simple.

Create a new MTS file. And Next.

Place the file under the MDG folder above the Profile folder. Name it something like CTech. It will receive a .mts extension and saves the settings for the MDG. Next.

Technology: Custom Cars (or whatever represents the modeling technology). Filename: Navigate to program folder and further to Sparx Systems\EA\MDGTechnologies. Save it here as CTech.xml. EA will read this folder on startup and offer your MDG along with others. ID: Any arbitrary string will do. E.g. CTech in our sample. Version: 0.1 which is a good starting point. Remember to increment version and release number during subsequent changes. EA chooses the one with the highest number which is good during testing. So you can have a local MDG which is drawn before the common one for the rest users. Very handy. More on that later. Enter some blurb in the Notes. The rest can be left empty. Add more later when you are a more advanced MDG editor. And Next.

Just add Diagram Types to the selection list. And Next.

Navigate to our Profile folder. Move the CProfile.xml to the right side. And Next.

Again navigate to our Profile folder. Move the CDiagram.xml to the right side. And Next.

Finish. EA responds that it has created the MDG in EA's program folder. You might take a look inside. Or maybe later. Just ensure it is there.

Now you have to test it. Simply start a new instance of EA and navigate to Settings/MDG Technologies... which should show your new technology along with the existing ones. EA has already enabled it. Click on it and see version and notes you entered. Now open an arbitrary EAP file (e.g. the one where you are creating the MDG). Go to a reasonable place and try adding a diagram. You will find the CDiagrams on the left hand side and the Design and Commission types on the right hand side. Very nicely, but currently not too helpful. You have not yet related diagram elements to diagram types. The toolbox is missing. So we silently close the instance and continue with the next large step.

Note: the editor is once again confused. The diagram now does not show up with the tab containing the name and the ID. Neither at print nor at Save As Image... I'll edit this later when the confusion is gone or a kind reader tells me what is wrong here.

Iteration x

Finding out which diagram types are needed and which elements should appear is another crucial phase. You will likely need to redo large areas during MDG design. When design is already ongoing, which is likely, you need to think twice about the current model and its relation to the MDG.

Custom Toolboxes

Toolboxes appear in a separate window or - which I prefer since it makes the toolbars window superfluous - via the blank-context menu. You want to relate a toolbox with a diagram so you get only that set of elements which is meaningful in the current modeling context. And that's what we are going to do now.

Create a new «profile» Package and name it CToolbox. Inside create a new Class element ToolboxPage and stereotype it with «metaclass». We will use that metaclass for our toolboxes.

Now create a class diagram named Design. Drag the ToolboxPage as link onto it. Drag/draw from the quicklinker and select MetaModel/Extend. Name the new stereotype Design. Now we need to add the elements to appear in the toolbox for the Design diagrams. Let us simply choose two: Motor and Gear. For that add an attribute called CProfile::Motor with Initial Value Motor. This will select the Motor stereotype from our profile and let it be displayed as Motor (the initial value). Repeat with CProfile::Gear/Gear and have a look in the help file what else can be placed here like default UML elements.

Now we need to save this diagram (not the package!) as profile. You may have noticed that EA is doing relation-by-name. For what reason ever, but you need to be very careful with typing the correct names. I needed several iterations during creation of this tutorial in order to get it correct due to typos. A look in the created MDG file helps tracing that. So, right click the diagram and choose Save as Profile.... The filename contains the "Last Saved File" from Windows. Nice? No! The name itself is at the end of the path and usually not visible. So you need extreme care to get the right file. That goes for saving of diagram and package profiles.

Okay. We will need more than one toolbox. Either you place them in our Profile folder and prefix them with e.g. TB_ or you place them in a separate folder Toolbox nearby the Profile folder which I usually do. Save it with the appropriate name.

Create a new class diagram Commission with a stereotype «Commission». Just put Car and Chassis in as toolbox elements³. Again save the Diagram and take care of the correct location.

We are not done yet. So far we have created two toolboxes, but the diagrams do not know that there is a relation. So let us add that.

Switch to the CDiagrams diagram. In the metaclass for Commission add a new attribute named toolbox with Initial Value Commission. Same with Design/Design. Finally save the CDiagram package (must I mention the right location?).

DONE! Almost. We only need to re-create the MDG and test it: Alt+T T⁴

Next.

Open an existing... Choose the .mts you saved in the beginning. This will give you back all options from the last time. The drop down should hold it still. And Next.

Next.

You can leave the version at 0.1 for now. Only once you have a production version else you need to increase the release or version so EA takes your new test version. And Next.

Now you need to add Toolboxes once. And Next.

Next. Next.

Navigate to where you saved your toolbox profiles and all of them to the right side. And Next.

Finish.

Your profile is done and in the right place. We can now do the final step.

MDG Testing/CM

Simply restart EA. If you open the provided sample you already have two diagrams in the Sandbox view. Go to Design, click inside and watch Motor and Gear appear in the menu.

Now go to Commission and try the same. Car and Chassis appear but with empty guillemets as symbol for Car. That means EA did not find the stereotype in the profile. You will need to debug what is wrong and correct the MDG. Thanks to Walter Fahmer pointing out the quite simple solution: Go to the Toolbox definition for Commission and change CProfile::Car to CProfile::Car(UML::Class). The reason is that Car extends both Class and Package and thus is not unique. So we have to tell EA via the naming convention which of them we mean. I will not correct the model itself as I think it is a good exercise to go through.

I cannot say much more here. That would go too deep. There are two common issues you will likely encounter. One is the just mentioned empty guillemets. Another is that the toolbox is not connected to the diagram. You will likely have a typo in that case. The last I recall is a not appearing toolbox (so in no context at all). In that case you did something wrong when saving the profiles. The best is to save all profiles and regenerate the MDG⁵.

Your profile is still local to your EA program folder. In a team work you will need to place the MDG on a network share (or maybe a version controlled folder). Use Settings/MDG/Advanced to locate the share. Make sure your MDG has an increased version/release number before you start testing. EA will then automatically prefer the new version over the old one on the share. So you can test locally without problems. When you are done copy your new version to the share. This is safe as EA only loads the MDG during startup. Any open instance will go on with the old version. New instances will use the new version.

Final Remark

I created this tutorial on the fly in parallel to modeling it with EA. I tried to note each step. Though it might be possible I forgot one or two or I made some other stupid mistakes. I appreciate any feedback to improve this document and hope you find it useful.

Improved MDG Creation

Convention

First of all it is a good idea to stick to some convention in naming each of the profiles, how to arrange them in EA and where to store them on the file system. The proposed convention is one I adopted over a couple of years. You might use your own, but here I describe how I do it.

EA

Currently I work with just three different profile types:

• the main profile with all the elements,
• the diagrams and
• the toolboxes.

For my MDG, I use a simple EAP repository where I create a single view. The name of the view is what will become the identifer and its alias the user readable name of the profile. Inside that view I create <<profile>> packages for each of the above mentioned types. The packages can have arbitrary names which will be used as namespaces. The only and simple convention is that the diagram and the toolbox package have the strings diagram or toolbox inside so they can be identifed as such. Inside the toolbox profile package single diagrams are placed for each toolbox. Here the name of the diagram is that of the toolbox. The MDG that is going to be created is located via the Filename property of view package. Note that this property is found in the Element Properties window (shortcut Alt-1) and not in the Files tab of the properties when double-clicking the package!

That's all for what goes into EA. Of course you need to fill the single profiles with some life data. You might read my article MDG Intro to find out how to do that.

File System

The MDG repository is stored somewhere on disk. In the same folder, the final MDG will be placed (which name is placed in the Filename attribute of the above mentioned view package). Further it contains a sub-folder called Profile Data which takes - you guess it - the single profiles. Just one sub-sub-folder named Profile Data/Toolboxes where all the toolbox profiles are placed.

Naming 

Each <<profile>> must be saved individually from either the package or a diagram via the Save As Profile context menu. The convention is easy: the EA package name is identical to the file name. The toolbox profiles are stored under their name in the Toolbox sub-sub-folder.

Creating Profiles

If you still would use the MTS creation procedure you would not have such a great advantage now. But here a little perl script comes in which you find attached to this article. Once you have saved your single profiles just call the scipt from the command line (you will need to place the GUID of the MDG view package inside once; see line 9). This will access the running EA session, check the profiles against your repository and create a new MDG. Thereby it will increase the release number automatically. If anything has found to be wrong it will croak. This happens when you saved one of the profiles wrong overwriting another one.

If you are using my Perl framework (Extending EA with Perl) you can use the script as an add-in. Of course you can code it in any other language, but I choose Perl for its mighty string operations.

Caveat

Of course this procedure will not help if you saved one of the profiles in the the completely wrong place, which can also happen as the Save As Profile dialogue always uses the last recent file location, which is only in rare cases that of your desired profile. But from experience I know that most times you simply overwrite the wrong profile, which makes you simply wonder why your MDG does not work. This little script has definitely saved me many hours.

Extending EA with PERL

Package Contents

This package contains the following files:

• A.pl - a sample perl script
• EaControl.dll - a ready to use extension package
• EaControl.pm - the according perl module
• EaControlReposWrapper.pm - a handy extension module
• EaControl.reg - some registry keys needed for EA Addins

Installation

All you need to do is to follow these steps:

1. Place the files in a reasonable location.
2. Register the dll with REGSVR32 EaControl.dll. This will make the addins available for EA.
3. Edit and adjust the paths in the EaControl.reg file and add it to your registry by double-clicking the file.
4. Start EA

Now you should see an Addin context menu entry. If not, watch out for the message in the Addins/Manage Addins window. Likely you have an invalid path somewhere.

Configuration

The context menu in EA is build according to your entries in the registry (see EaControl.reg). Start with simple perl files (like the A.pl) contained in the package. For each entry you add in the registry you will find an according entry in the context menu. When clicked, the related perl file will be invoked. You can modify the perl file on the fly so the next invocation will run with your changes. See below on how to work with perl files on your EA repository.

Instead of pointing entries to simple perl files you can also point to perl modules (.pm). In contrast to simple perl files these modules are loaded permanently. That means an instance is created on startup of EA and then re-used. That way context information can be stored and re-used over several clicks. Further it is possible to create sub-menus from modules.

Working with .pl files

Upon invocation the .pl receive 3 parameters in %ENV:

• REP holds the repository object. You can assign it to a local variable (e.g. $rep) for easy use.
• LOC holds the values TreeView or Diagram depending on where the context menu is invoked. Note that a call from the menu will appear as TreeView.
• OPT contains an optional parameter provided after a comma following the file name in the registry.

The following code snippet demonstrates the principle:

my $elem = $rep->GetTreeSelectedObject(); # point to the selected element
$elem->{Name} = '(' . $elem->Name . ')'; # surround with brackets
$elem->Update(); # save changes

The first line retrieves the object that had been selected from the context. In the second line the object’s attribute Name will be changed. Note that on the left hand side of the assignment you have to surround the attribute with braces. Note also that attributes and methods are case insensitive. However, it is convenient to write them in camel case. Finally on the third line the element changes are written back to the database.

It is quite easy to continue that way. The analogy between methods and attributes described in the SDK/EA Object Model/Reference is obvious (I think). I will eventually add some more snippets to demonstrate the ease of use. Meanwhile I have a collection of several thousand lines of EA Perl code and the only problem is: how to filter the interesting/general stuff.

Working with .pm files

Any .pm file will be loaded permanently. Further you have to implement the methods described below. 

sub new ($self, $rep)

Passes on the pointer to the repository so it can be used in the package.

sub menu ()

Must return the menu entries as array. If only one entry is returned then this is taken as menu entry. If more than one entry is returned then these entries are placed under a sub-menu for the according menu entry of the package.

sub exec ($self, $cmd, $loc)

The sub-menu name which has been chosen is supplied in $cmd. $loc holds either TreeView or Diagram (see above). The package can execute the command with the previously stored context and the repository from the new method.

Updates

As of 27-07-2010 I have uploaded a revised EaControl and Wrapper. The controller has removed the fixed references to Perl libs and now detects them dynamically. This should work for most installations.  To update from a previous version first backup the old DLL. Then just replace the old DLL with the new one. If EA starts as usual and you find the addins, everything is okay. Else restore the old DLL and drop me a line so I can look into it.

On 16-05-2011 I added a DLL to work with new versions of ActivePerl. The old version did work up to build 1005 of ActivePerl (and probably a few later). But with new builds the DLL raises an error (EA_MenuClick: Exception Occurred Invoking Method). So I add a second DLL which is supposed to run with later builds. Just rename the EaControl 5.10.dll to EAControl.dll (replacing the original one).

On 30-04-2012 a new DLL release (5.14 suffix) has been added to work with ActivePerl build 1402. Obviously the Perl releases (the original one was created with 5.8 while the new one utilizes 5.14) have quite a few incompatibilities. I had not thought of these when initially creating the DLL. Maybe I’ll start thinking about a release concept when the next incompatibility shows up next year.

Final remarks

Although the sources are in use and have been improved over several years they may contain errors. The DLL is created from the EaControl.pm using ActiveState’s tools. You can also use WSH with the perl module. I did this in the past, but now I’m using the DLL. You can google for “ActiveState WSH” if you like to use EaControl.pm directly (with own modifications). Let me know how you like the package, where you did find errors, where you would like improvements or if you have added some for your own.

There’s also an EaControlReposWrapper.pm to extend the number of methods provided by EA’s automation. For a basic use you do not need this instrument. However you might want to use it if you have more experience. The wrapper has now been pimped with more functions like getting the (correct) children of elements and packages. That is, only the direct elements will be delivered and not their sub-elements.

Finally a word to debugging. I use ActiveState’s Komodo where I have a simple method to attach the debugger. This allows for interactive debugging of EA addins.

Have fun.

Align ports and interfaces with a Perl script

Port/Interface Layout Assistant

Alignment of ports on a SysML block or a class can be difficult. Especially if your eyes are aged like mine. So I wrote this little script which of course works with my Perl EA Extension. The attached script helps a bit in the layout process by automatically spacing ports evenly in horizontal or vertical order. I developed this script once for interfaces and now improved it for ports. It shall work for any those embedded elements but is currently used by me mainly with ports.

Use cases

Distribute a number of ports evenly on one side of their parent

Once you added embedded ports from the context menu those are placed on the top left side of the parent element with no space. It’s quite fiddly to grab the little ports, especially if the labels are in the way and get selected first. Now select the ports and the parent element by dragging the mouse over the top left of the element so all get selected and invoke the addin. I use Alt-A (opens the addins menu), cursor right (selects my Addins list), enter (execute the entry which is the first because I named it “Arrange Ports”). Voilá - all ports are spaced evenly across the top of the element. It’s now much easier to move them to the correct order and side.

The above works for all sides. Spacing in horizontal direction is: same space between all selected ports and half the space to left and right of the outer most. For the vertical spacing I check for the stereotype “Block” in which case the spacing is done similarly to the horizontal. For all other elements a fixed spacing for the name compartment is added to the upper space. This is not always optimal, but better than nothing.

Space a number of selected ports evenly

Sometimes you need a group of ports which should have even spacing but not over the whole side of a component. Just move the ports raw to where you want and select them (either ctrl-click or dragging the mouse). The addin will then space all ports inside the two outer ones evenly. Align “opposite” port

In many cases you have two components placed near to each other with a number of ports connected to the opposite component. Unlike parent elements, the embedded elements cannot be aligned with standard EA drawing tools. So it’s always a fiddly piece of work to get these aligned. With this script you simply need to select one of the ports and invoke it. The opposite port will automatically be aligned horizontally or vertically. These are the preconditions: The selected port must have only one connection (visible or invisible) to another port on the diagram. Both ports need to be on either the horizontal or vertical side of their parents.

Align a group of ports with their opponents

First layout the ports of one element by spacing ports over the whole side or as group (see above use cases). Now select one outer most port of this group and perform the Align “opposite” port. Do the same with the other outermost port. Drag the inside ports on the other side roughly to their position so no crossings occur. Select all opposite ports and perform use case: Space a number of selected ports evenly. Capabilities

There is obviously a large number of “unplanned” usage like multiple elements with multiple embedding on mixed sides and so on. The addin tries to guess which of the selected elements is the “main” parent by the number of selected embedded elements and if necessary the diagram size of those. It will issue complaints on the system output window if needed. But due to the fact that there is a wide range of misuse I cannot promise that all cases are being checked. In the unlikely case that ports/interface get placed “somewhere” on the diagram, just drag them a little bit and EA will drop them back to their parent. I had this during testing but should not occur any more.

Update

As of 30-07-2010 I have uploaded a new release with some error corrections and the capability to align “opposite” ports.

Advanced Searching

This article once built the base for my well known book Inside Enterprise Architect.

Accessing the Database

The lowest layer in EA is that of its database. When you first start with EA you will most likely deal with EAP files. A simple though not official fact is: EAP is MS Access. So if you want to play around just open one of those EAP files and see what MS Access is telling you. If you are using a Corporate license you will most likely use a more advanced SQL server. Be it MS SQL Server, Oracle, MySQL or whatever. In that case you need some client software to perform manipulations. Before doing so you should get familiar with the database in a more simple way.

Inspecting EA’s Tables

The most simple way is to open the respective EA repository with EA itself. Use the EAExample.EAP which comes with your EA installation. Now press Ctrl-F to open the search window. Click the Builder button and select the SQL tab. Type the text

SELECT * FROM t_

and press Ctrl-Blank. You should now be presented with the following: 

As you can see you are presented with a list of tables which reside in EA’s database. For a start let’s choose one of the important tables: t_object. After pressing the Run button or the little triangle top left you will get a list of all elements present in the repository.  Obviously the column Object_Type is the type of an element and Name its name. Simple! You might go on with t_package to see details of all packages in the repository.

Ways to Query Tables

The clean way to query the tables is the API. This is recommended for most cases.  However, there’s also a demand to be able to access these data where the API is simply too slow or where it does not offer certan details. EA is kind of object oriented in how it queries its database. That means for a global change (like changing the status) it will issue single UPDATEs instead of a compound. Of course you can query the database much faster with an intelligent query than any iterative API calls.

Anticipating a simple structure element of the table containing the elements (t_object) the best way to retrieve an element is by 

elem = Repository.GetElementByID(4711);

which yields the ‘same’ element as

SELECT * FROM t_object WHERE Object_ID = 4711

where just the API object data are cooked while those of the SQL are raw. So that’s no wizardry.  But imagine you need all elements with a certain stereotype. While in the API this would need quite some programming effort, the SQL is simple:  

SELECT * FROM t_object WHERE stereotype = “stereo”

  Now it’s upon your imagination what you can do by joining different tables in SQL.

Most Important Tables

Only a few tables will be highlighted here so you can get an impression of what would be possible. Also only a few columns will be described here. If you need more details you might want to look into my e-book which goes into much more details.

t_object

As you already know this table holds all elements stored in the repository. That is any element you can see in the project browser plus those not shown like notes, boundaries and a couple of other elements. Please note that the Package element is a pendant to the Package itself. Part of the information in both is redundant and both link to each other.

• Object_ID: Primary, unique key for the element in the current repository
• Object_Type: String value denoting the type like ‘Class’, ‘UseCase’, and so on
• Name, Alias, Author,…: you guess it
• Package_ID: Identifier of the package where this element is located
• ea_guid: A global unique identifier which is unique amongst (theoretically) any repository
• Parent_ID: Identifier of the element to which this element is a child (if > 0)
• and many more not to be covered here

t_package

This table holds property information for packages. As packages hold some extra properties different to those in the t_object this extra table is needed. 

• Package_ID: Primary, unique key of the package
• Name: you guess it
• ParentID: PackageID of the parent package
• ea_guid: A global unique identifier which is unique amongst (theoretically) any repository
• and many more not to be covered here

t_diagram

This table contains the properties for all diagrams. The objects you see in the diagram itself are stored in t_diagramobjects. 

• Diagram_ID: Primary, unique key of the diagram
• Name, Author, …: you guess it
• Package_ID: Identifier of the package where the diagram is located
• ParentID: ObjectID of the element where this diagram is located (if > 0)
• ea_guid: A global unique identifier which is unique amongst (theoretically) any repository
• and many more not to be covered here

t_diagramobjects

Each rendering in a diagram is that of a respective Element. This table refers those elements and store their position and style in the respective diagram. 

• Diagram_ID: Identifier of the diagram where the object is placed in
• Object_ID: Identifier of the object which is rendered
• Rect…: The coordinate of the rendered object. Top left if 0|0, others are -x|+y
• and a few more not to be covered here

t_connector

Any relation between different elements is stored in this table. A connector refers to two separate Elements being source/start and destination/end. 

• Connector_ID: Primary, unique key of the connector
• Name: you guess it
• Direction: String equivalent of the direction property
• ConnectorType: See the tconnectortypes table for valid values appearing here
• StartObjectID: Identifier of the source element
• EndObjectID: Identifier of the target element
• and many more not to be covered here

Further Reading

If you need to know more about above tables and other tables of EA’s repository structure in general you might want to check out my e-book Inside Enterprise Architect.

Create a “hyperlink” for EA elements

Background

When working in teams I often found the lack of a hyperlink to reference EA objects a real drawback. So I thought of ways to create a text link that can be used to retrieve model elements directle.

Pre-requisite

The Copy menu in the very first EA releases was quite bare. But then they added a very useful line: Copy EA GUID. All EA elements have a GUID which is unique amongst all repositories (at least theoretically). This GUID can be copied and used in text messages as it is plain text (though a bit cryptic).

The GUID is referenced in different element classes in EA. Namely these are Packages, Elements, Diagrams and a few more. The GUID does not carry any context information (with rare exceptions that can be ignored) which tells about the element’s type.

Procedure

When you work on a shared model and like to inform others to look into a certain artifact you can copy the GUID of the element with the Copy Reference command and paste it in your mail like 

Please look into {00FED3AD-799A-48a7-A2E8-3A5EB131A7FA} ….

and send this text. The receiver can now copy the GUID (actually the whole text can be clipped). Then the reader will switch to the model, invoke the addin and - voila - has the model element highlighted in the Project View.

As a further improvement the script has the possibility to locate multiple elements at once. If there is more than one GUID in the clipped text, the script will try to find a diagram containing all referenced elements. An (arbitrary) diagram will be opened that contains more than one (and the most) of the clipped element GUIDS. The first GUID element is also selected in the project view.

It is also possible to create external bookmarks in a text file this way.

About the script

The script itself is assumed to run under the Perl addin framework as published here. It will first extract the GUID string from the clipboard text. Then it will look for the equivalent GUID element. Note that it first looks for the package and then for the element. For a package the element (contained in the package) would be found under the same GUID and the ShowInProjectView would not work.

Although this script was written in Perl you should be able to re-implement it in your favorite language.

Updates

As of 2010-08-12 additional support for multiple GUID selection has been added. This code snippet is making use of direct SQL calls to find a diagram.

Have fun.

Creating marvelous EA documentation using LaTeX

I know that I’m here in the position of one of those few Gauls fighting the Roman Text Forces. But knowing that there’s a free alternative is nice. And producing documentation the smart way just feels better. You’re invited to visit Latix ;-) A wild boar is wating for you.

Prerequisites

There are two prerequisites you need for the LaTeX document creation:

1. The EA Automation with a suitable language. I prefer PERL since it has a ton of built-in string operations. Python is also nice but you can also stick with your own favorite language.
2. The TeX processor itself can be found in various packages. If you google for MiKTeX you can find a self-extracting archive that has everything out-of-the-box. Just unpack it to e.g. C:\Program Files\MiKTex and you’re done. You will need just the miktex\bin\pdflatex.exe for the document creation.

A rough overview

TeX is a typesetting language that was developed by Donald E. Knuth a century ago (almost). Rather than WYSIWIG editors you have to place meta-tags in your text which will be processed before an output document can be viewed. TeX files are basically ASCII and thus portable. You can process them under *NIX, Windows and Apple computers. The output will look the same - always! TeX is programmable and you can do so if you have a certain peculiarity of masochism. Luckily there are quite a few which already have done extensive programming and released nice packages which normal people can use. The best known is LaTeX which offers a reasonable set of commands for text processing. There’s much more you can do with TeX like presentations (the better Powerpoint :-) which should be mentioned but can not be covered here. Here is a small document stub:

1   \documentclass[12pt]{article}
2   \usepackage{geometry}
3   \geometry{a4paper,left=20mm,right=20mm, top=2cm, bottom=2cm}
4   \begin{document}
5   \section{section title}
6   section contents
7   \subsection{section title}
8   subsection contents
9   \end{document}

When you typeset this source you will receive one page of output. The first three lines define the output format. You see that the meta-tags all start with a backslash. Parameters are enclosed in braces “{}” and options in square brackets “[]”. The main document is enclosed in the tags on line 4 and 9. Headings are introduced by the tags in lines 5 and 7 (there are lower levels \subsection, \paragraph and \subparagraph). Text following these tags are typeset as normal text. All the \section information will be available in a nice TOC if you so wish.

Of course it is not possible to give a complete LaTeX tutorial at this place. You might google for “LaTeX tutorial” to find more complete tutorials.

One “real” example

Attached you will find a more real example I created from an EA package (using one of my own PERL scripts). The package holds the following files:

• Sample.eap - the source from which the output was created
• Sample.tex - the TeX file which was created from an adding script
• <strange guid>.png - A diagram export out of EA using its internal GUID
• Sample.pdf - the output which the TeX processor creates from the above  

When you look into the TeX file you will (hopefully easily) find out how to structure the TeX file creation. I do have a variety of different creation procedures. One for example is a thread listing: starting from a specific element the related elements will be thread listed so you have a nice context documentation. If you would like to learn more about TeX file creation, please let me know.

A word about PDF creation

One major disadvantage in creating DOC files from an EA model is the fact that you can not control the document contents from the moment it is created. The document is open to any uncontrolled changes and people will start doing so. After a while you have a couple of documents that have been augmented and/or changed by readers/editors. The contents will definitely vary from your model and nobody will be able to tell which is the truth: model or document. You will not have this problem if you create only PDFs from your model. Just place a timestamp (and optionally some baseline information) in your document and you’re done. Unfortunately Mac computers are not that wide spread so most people can’t take advantage of PDF annotation. Windows users need additional Adobe software for this purpose. However, it is cheaper in the end as the PDFs will reduce confusion about the “truth”.