1. Preface

One of the great things in Enterprise Architect is the possibility to extend standard UML modeling by usage of so-called MDG (Model Driven Generation) 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.

The EA version used to create this book was actually 12 (build 1215). However, most of the tools are also available in earlier versions of EA. The menu structures change from release to release and you will eventually need to poke around a bit to find the right one. If you really got stuck with the menus or other things just drop me a mail: thomas.kilian@me.com.

Starting with EA Version 15 Sparx introduced a couple of new things with profiles which look more promising than many of the “features” that came during the last years. So this book release catches up with the now recent version 15.2.

2. Copyright and Disclaimer

Also all of the information in this book has been tested by me in many circumstances I can not hold any liability for use of the here presented information¹. However, I’d be glad to receive any kind of feedback to correct future updates of this book which you will receive for free in turn. Having said this, all information presented here is subject to change without notice.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

3. 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 and which of them are important (need a special optical representation) what diagrams need to be created and in what context they are used.

The following chapters will tell you how to create the domain model and how to derive the MDG from that. Be prepared that those steps need a couple of iterations. That means you will introduce a MDG once you have a scaffold and then need to improve this to make it even more useful. Since changes to a MDG can be crucial I will explain how you can navigate around some of the worst pitfalls.

To avoid a pure hypothetical discussion I will stick to some artificial domain which hopefully can be understood by all readers. It shall be a custom bicycle manufacturer similar to what the guys at Orange County Choppers are doing.

I will describe the single steps one by one so you can create your own MDG at once. It is also possible to open the example model for reference in parallel. Just run a second instance of EA. However, you are encouraged to follow the steps in the next chapter directly. This will give you a quick run through all of the MDG creation process steps. Once you have that skill you can go ahead and learn about more advanced features in the following chapters.

While the first chapters just deal with the MDG surface I try to bring a bit light into what happens behind the scenes. It’s nothing you need to know for basic working with MDGs but it often helps understanding why certain things happen the way they do. If you need to know more about that you should have a look into my book Inside EA.

The example model which has been used to create this book can be dowloaded from here. This zip also contains resources which are used to create the samples used in this book. EA 12.0 (the most current build at time of creation) has been used when building the demos. However, it should work with most pre 12.0 builds as it does not contain too awkward constructs.

4. Bird’s View

Before you can start creating your MDG it is necessary to do some preparatory work. A MDG shall support development of your UML models and enhance communication with respect to the individual domain you are working in. To actually do that you need to know your domain. And the best way is to sketch a domain model. It’s as simple as drawing a class diagram – in theory. In practice it is one of the most difficult tasks since the domain knowledge is usually distributed and well hidden in papers piled in drawers of different staff. Or quite more often just in the brains of the latter.

To get a start with this create a new repository for the MDG design. The model/root node is best called after the domain itself. This can be the industry, company or branch name. I found it best to use Model Driven Architecture (MDA) from the beginning. So the Views beneath the model root shall be named CIM (computation-independent model), PIM (platform-independent model) and PSM² (platform-specific model). A Sandbox view comes in handy for several purposes.

4.1 Stakeholders

The business itself is important. But even more are people doing that business. Only if you know who is involved it will be possible to create something that will be accepted. Your project can only succeed if you get all relevant people aboard. Else prepare for ship wrecking.

Inside the CIM create a folder Stakeholders with a use case diagram of the same name. Start by putting actors for the most obvious roles onto the diagram. Make sure you write a short description in the notes of each actor. If there is a job description (on paper) just reference that. It is not much work but will help understanding the domain. Not just for you but also for people coming after you that need to get started.

You can augment the diagram by relating the single actors as to the company hierarchy. Use simply dependency relations for that.

The list of stakeholders must not be complete from beginning on. Often you discover new ones in the course of the following process. Just don’t forget to add them to the diagram!

4.2 Requirements

Gathering requirements can bring you a hard time. Without the right requirements it is impossible to find the goals you want to reach with modeling. But most times people think that requirements are “obvious” and do not need any effort to be extracted. For the same reason you will not find a budget for this. So to overcome that dilemma you must discipline yourself to write down anything that resembles a requirement. Of course, the best place is this repository where you want to design the MDG.

Place a Requirements folder inside CIM and create a Requirements diagram inside. Eventually you will need some structure for functional and non-functional requirements later. But for now if you happen to find a requirement from any stakeholder just drag the actor as link onto the diagram (you might as well use instances and name the concrete person) create a Requirement from the toolbox and <<trace>> it to the actor.

4.3 The Domain Model

Once you got the basic set of stakeholders and hopefully a set of requirements you can start analyzing the business domain. Create a folder Domain Model with a class diagram of the same name inside the CIM view just below the Stakeholders package.

Now start with adding classes for all business objects that come to mind. I sort of mix object and class here. What you actually do is to find the real objects and create a class for it. Each business object shall finally be represented by a class in the domain model.

Of course each domain has very different business objects to deal with. A bank will have accounts and stocks, machine building companies will deal with all sorts of tech paraphernalia, a chemical plant will use chemical material and so on. In a first step just name the single objects and place them on the class diagram. This can well be done as a brain-storming on a white-board.

Eventually the number of domain objects can get large so you need to package them. Papers are a good example to build an own package. Often you can simply identify dependencies between papers and you should draw those directly between the single objects.

The next step is to identify the properties of the single business objects. This is one of the more tricky steps. Finding the properties themselves will often cause you to ask different people and moderate their contradicting answers.

At the same time you need to make up your mind as to what granularity your domain model will go. For example an address can be formalized quite much. But only if your business is limited to a certain geographical area. Once you have more than one area you will find that formalizing address descriptions can easily become a nightmare. It is often easier to start with simple string properties and attach notes to where a later refinement might be useful.

The above model would be some start for our example domain. Definitely it is not complete but from here you will get an easy start and an idea how to continue.

It is important to involve all stakeholders in completing each single business object. But rather than bringing all together in a single work shop (which is often challenging due to time constraints) go and visit one after the other and note what they say. Such big meetings often end up in fruitless discussions and are a simple waste of time. Once you got the different opinions try to unify the diverse ideas and moderate that in smaller workshops. Once you made a picture go ahead and present and discuss this to get a sign-off. Eventually you have to go that round-about once or twice but that should be it.

5. MDG Structure

A MDG file is simply a container for several XML files. Most of them being UML profiles. It is possible to create a MDG with a text (or XML) editor and sometimes you really need to do that³. But now we will start the EA-way. And that is by first creating a profile.

5.1 A Profile

A profile is what contains the elements you define for your domain. A profile as such is meant to keep elements. There are profiles for diagrams, toolboxes and other things as well. In those cases the profile will be attributed with the objective.

Since this chapter is named “A Profile” and not “The Profile” you can guess that there may be multiple profiles. However, a single profile will do in most cases. You would use multiple profiles if you can identify multiple sub-domains which need different treatment. Using multiple profiles is not much more difficult than using a single one. So we start with the profile for our example domain.

Copy

The following is one way to achieve the desired results. But for me it’s the best way. It starts with creating a deep copy of the domain model. Just Ctrl-C with the focus on the Domain Model in the project browser⁴. Go to the PIM view, create a folder MDG, select that and press Ctrl-V. This will create a deep copy of the domain model. Now edit the properties of the copied Domain Model. You should rename it to some acronym for the domain since this name will be needed to reference elements which you need to type manually later. In my example it is CBM for Custom Bike Manufacturer. Further you must assign the stereotype <<EAUML::profile>>⁵. Don’t forget to rename the contained diagram as well (with no need to add a stereotype). It should look like this:

Now if you open the diagram and press the space bar you will see that the toolbar shows no longer those of a class diagram but that for a profile.

Cut

The copied domain model still contains all business objects. But often we do not need to model all of them. E.g. the Tool is just an abstract classification to have tools inherit the vendor. So it is not an element you would later include in your modeling process.

Cutting away those elements will save you some work ahead. Still, if you find a need for those deleted elements later you can create a new copy from the domain model. Instead of cutting elements away you can simply stow them in a package named Not used or Future use.

Edit

Next create a folder metaclasses inside the profile folder. From the new toolbar choose Metaclass and inside select Class:

This creates a stereotyped class. In the project view drag it into the metaclasses folder⁶ so it does not clutter the domain objects on top level.

The following steps might be tedious. Start with one of the classes and add a stereotype <<stereotype>>⁷ manually (without typing the guillemets!). This will add a stereotype icon to the class and the quick-linker will offer an Extend relation. Just create that as link to the Class metaclass:

Assuming that all of the domain objects will result in classes continue changing their stereotype and linking them to Class. So you end up in some garbled diagram like this

Finally remove the metaclass from the diagram with Delete (not Ctrl-Del since that will delete the element completely from the model). You can show the relations in a new diagram named Class inside the metaclasses package. Drag Class onto that diagram and from the context choose Insert Related Elements. Now you need to hide all relations except the Extend. This is best done opening Diagram/Visible Relations and uncheck those to hide:

A simple auto-layout (and optional manual work) will then result in something like this:

A First Test

At this stage we are ready for a quick test of the new profile. Therefore the profile needs to be exported to a XML file. Select the profile package in the browser and from the ribbon Specialize/Technologies/Publish-Tech/Publish Package as UML Profile. Choose an arbitrary file location⁸.

Also you need to give the profile a name which will be CBM in our case.

The next step is to import the profile so it can be used. Open View/Resources, from the context of UML Profiles choose Import Profile

and select the previously exported XML file. Now you can see all the elements that had been defined.

If you have not done so create a view Sandbox with a class diagram and open the latter. Then drag one of the elements from the UML Profiles onto the diagram. It will create a new class stereotyped with the name of the chosen element. Additionally the tagged values (TV) are populated with the attributes defined in the profile:

In the above example the Bike comes with the style as TV with a drop down containing the bikeStyle enumeration values. So far, so nice.

Now we try the same with the Tool:

The TV size resulted in a simple input field which is also nice. But the vendor shows up as empty group. Here we ran in one of the bugged features in EA. The stereotype Vendor has been generalized from Person and thus should have an address property. But EA silently ignores them here. One needs to copy inherited attributes from the general class. YAEAB.

You can go on verifying that all profile elements work as expected. Then you can delete the profile from the Resources (use the context menu). Once deleted the TVs in groups are no longer grouped/available but that’s ok since this was just a test and the elements in the sandbox can be thrown away as well. Note that the stereotypes from Project/Settings/UML Types will also be gone.

Extending/Completing the Profile

At this stage you will get a good feeling for what your profile is good for. The more complete your profile is, the less you have to fight with fixing an incomplete profile later. However, in order to get an overview of the whole picture we will carry on with the other two most important parts of a MDG: diagrams and toolboxes. We will care about details of a profile in chapter Advanced MDG Techniques.

5.2 Custom Diagram

While the profile holds the Lego stones for your model the custom diagrams are like frames for the presentation. There is no special rule as to which diagram will be needed. But usually you connect it with a certain design process. You probably have some sort of element sets that belong to each other. In our example domain you will eventually have different sets for technicians, designers or sales persons. As you can see they are all actors we defined previously and so you can create actor-centric diagrams. Often processes and actors are related so actor-centric will also mean process-centric.

You should already have in mind that the limitation of elements per diagram will be controlled via toolboxes (which will be detailed in the next chapter). Another use for custom diagrams is to replace the standard UML diagram with a set of a reduced number of elements. So you would have your own class diagram but with your own reduced and/or augmented set of elements.

Let’s assume that we need two extra diagrams for the commission and the design process. Start by creating a new package named CBMDiagrams inside PIM/MDG, assigning it a stereotype <<profile>> and creating a class diagram inside. Having that diagram open hit the space bar and create two Stereotypes Commission and Design

that will represent our custom diagrams. Next you need to make them extend diagram metaclasses. Create a new metaclass for Actor:

Now you need to rename the new metaclass to something like Diagram_<base> where <base> must match one of the basic UML diagram types. According to the EA help these are

• Activity
• Analysis
• Collaboration
• Component
• CompositeStructure
• Custom
• Deployment
• InteractionOverview
• Logical (for Class diagrams)
• Object
• Package
• Sequence
• Statechart
• Timing
• Use Case (note the space between the two words)

So we name the first one Diagram_Use Case and add two attributes. The first is alias⁹ with a default value of Commission. This value will appear in the diagram creation dialog later. The second is diagramID which needs a unique string. I assign the company initials followed by an underline and an acronym of three chars or so which describes the diagram. Here it will be CBM_CUC (for Commission Use Case). You are free to use any other scheme you like, though.

Now an Extends relation needs to be drawn from Commission:

Repeat that with Diagram_Logical, Design and CBM_DL (for Design Logical) so we are ready for the next test.

Prepare for a quick test

Testing the newly created diagrams is not that easy as testing the above profile. We need to create a basic MDG right now. Before we can create it there needs to be some folder structure on disk. Locate some place where you want to create that folder so you can find it back easily. I named it mdgProf but you are free to find another suitable name. A number of files will go into that folder. I also place the final MDG inside. Later you might find another location for it, be it a shared folder or some place on a version control system. But I usually stow it here for testing and eventually copy the result when needed to the final location.

The folder will later hold a so-called MTS file which EA uses to store file locations needed to create the MDG. I create three folders named profiles, diagrams and toolboxes inside which are used to store the exported profiles.

As a first step export the profile to the profiles folder. Since in our example domain there is just one single profile it is named CBM.xml. In case of multiple sub-domains the single profiles will be named according to them.

Now the diagrams profile needs to be exported similarly. From the CBMDiagrams folder choose Advanced/Save Package as UML Profile and store it as CBM.xml in the diagrams folder.

The toolboxes stays untouched for now and we can start creating the MDG. Select Tools/Generate MDG... from the menu and click Next. Since this is the first time we choose to create a new MTS file and click Next.

The following dialog requests a couple of information:

Technology might simply be named after the company. If you have the need for multiple MDGs in a company you will likely be experienced enough to find meaningful names.

Filename will be that of the created MDG. As said I simply put that into the mdgProf folder named CBM.xml.

ID can simply be the company acronym (or the name of the MDG repository root node). And Version is some n.m scheme. Be warned that changing that number might become necessary and will easily bring you into trouble. We will be talking about that in chapter Versioning Profiles. For now just put a 1 into it.

All other fields except Notes can be left blank for now. The Notes will appear in the MDG activation dialog and is meant as a short description. So put in some meaningful text here and click Next.

This will ask you for the location where to save the MTS file. As said, just place it at top level inside the mdgProf folder.

Next we need to tell which profiles we want to add to the MDG. Since we have profiles and diagrams these options need to be ticked. And Next.

For each of the ticked options EA will ask for the related XML files. So in the first dialog locate the mdgProf/profiles/CBM.xml and in the following mdgProf/diagrams/CBM.xml. Then move them from Available to Selected Files.

From here click Next until the dialog is done. The MDG is now stored to where you told (in above case it’s located at mdgProf/CBM.xml. To utilize this MDG we can stick to the resources view (see First Test) but rather than UML Profiles we would use MDG Technologies to where we import the new MDG.

When done you should see the MDG in the list of available MDGs where you just need to enable it.

A quick test (finally)

Select the Sandbox view and click the New Diagram icon. Now you should see the technology listed containing the two diagram types we had defined.

As you can notice the visible diagram names are those from the alias attributes defined above. Also you can see that the Commission diagram is an use case diagram and the Design is a class diagram. Go ahead and create both diagram types in the Sandbox folder. You will see that the toolboxes are as one would expect for either class or use case diagrams.

Now export one of those diagram via Diagram/Save Image to File... and you will see (for the Commission diagram)

The diagramID we had defined as attribute is prefixed to the name of the diagram in the frame.

And where are the elements from the profile? Well, currently they are a bit hidden. You need to navigate through the Other sub-menu from the toolbar to find them. Here you might activate the profile so it can be found more easily.

Remember that until now we have not connected the diagram with any toolbar. But we are close to that step.

Updates

At this stage the testing of the MDG will become a bit more tricky – simply because a number of different files are involved which need to be saved separately. Still these are just two but when you save any of the profiles you will see this:

In order to reload a newly generated MDG you can simply load it again via the resources view. Any previously loaded MDG will silently be replaced by the new one as long as it has the same ID.

5.3 Toolboxes

Connecting custom diagrams with toolboxes will unleash most of the power which MDGs offer. Of course there’s even more to come, but having a grip on this will give you the most power for the least effort. So lets get it.

Like for the diagrams we first create a CBMtoolboxes package. But then we need to create a separate diagram for each toolbox and name that diagram accordingly. What we want to achieve is that each of the custom diagrams has a related toolset with just those elements which are relevant in the according context. So first we create toolboxes and fill them with the right tools.

Let us start with the Commission diagram. The commission process shall deal with use cases and the Bike itself. Initially we have to place a new metaclass derived from Actor (same reasons as above for diagrams). This is to be renamed to ToolboxPage and will be used to create all the different toolboxes. Now we can place two new Stereotypes named Commission and Commission Connectors which both extend the ToolboxPage. The first will stand for the compartment to hold the relevant elements and the latter for the according connectors.

Filling the toolbox

The contents of the toolbox is defined by attributes representing the specific element and their default value which is used in displaying the textual description in the menu.

The Commission toolbox shall hold an Actor, a Use Case and the Bike from our profile. In the Commission Connectors we will just place an association. So we add an attribute UML::UseCase with default Use Case, UML::Actor with default Actor and CBM::Bike with default Bike to the Commission stereotype.

As you can see the standard UML elements are prefixed with UML and have an infix ::. The type of the attributes is a don’t care. int might look confusing. You are free to delete the type at all or to set it to string.

To access our Bike you need to prefix it with the profile name which we had chosen to be CBM¹¹. In the Commission Connectors add UML::Association / Association.

The creation for the Design diagram is analogously. We can reuse the ToolboxPage metaclass from the last step by dragging it onto our new Design diagram (drop as Link!). Then add new stereotypes Design and Design Connector both to be linked to ToolboxPage with extends. Add Bike, Motor, Gear and Class to the first and an Association and a Dependency to the latter.

Another quick test

Before linking the toolboxes to the diagram let us test the toolboxes. In order to do that we need to save the profiles (yes, plural) in yet another way. Open the first of the two new diagrams and from there the context menu (the one from the drawing pane, not from the project browser — orthogonality?). Here choose Advanced/Save as Profile... and put the file in mdgProf/diagrams with the same name as the diagram.

Repeat that for the second diagram. When we run the MDG creation “wizard” it is necessary to change the available profiles and tick Toolboxes.

Now you will, additionally to profile and diagram, be asked to supply the toolboxes. Select the folder where they were saved and move them to the right side to the Selected Files.

You need to reload the newly created MDG and your toolboxes should be visible like this

and that

Ordering menus

As can be seen, the attributes in a single correspond to the order in the menu itself. But how is the order of the sub-menus determined? Well, this is EA. It’s the z-order of the menus on the diagram. Drag the two menu compartment stereotypes so they overlap:

As you can see the Commission Connectors overlaps Commission which means that it will appear below the latter. Try altering the z-order with the tool icons. Once re-saved the single toolbox compartments will appear in the new order.

Connecting diagram and toolbox

So we are almost done. The last part is easy but error-prone. All we need to do is to add a new attribute toolbox to each of our custom diagrams and set the default to the name of the toolbox profile. You need to be careful typing the names correctly. Since if you misspell one of them your profile will not work as expected. EA will not warn you in any way (just as we are used to that) but in the moment of deployment it will just fail. So for the <<metaclass>> of the Commission diagram stereotype add toolbox / Commission and for <<metaclass>> of the Design add toolbox / Design¹².

We Are Ready!

The last thing to do before having a well served beer is

A final test

Save the CBMDiagrams package as profile (the package, not the diagram) and make sure the file goes to the right location. Now re-create the MDG and re-import as explained earlier. Open the Sandbox view and create both diagram types. When you hit the space bar on the Commission diagram you should see the toolbox below.

The Design should have one more element and one more connector.

5.4 Wrap Up

At this stage your mind should be clear about the connections between domain model, MDG profile, diagram types and toolboxes. Although we have just used the very basic elements it clearly comes to mind that such MDG extensions will improve modeling in different domains tremendously.

Just from a personal experience I would recommend to work with this basic toolset for a moment before trying more advanced stuff. It won’t hurt if you read a bit in chapter Versioning Profiles since that has a couple of pitfalls ready.

Enjoy your beer!

6. Deploying a MDG

A MDG is always loaded temporarily during runtime in some memory which is not directly accessible from an API. That means the stereotypes you had defined in the profiles are not stored in the t_stereotype table. Once the MDG is loaded it will however influence the behavior of stereotyped elements.

6.1 Accessing the MDG

Basically there are two recommended and one system reserved variants how to deploy a MDG:

• imported to a single repository and
• shared on a disk or
• in the EA program folder.

Resource view

In the first case a MDG will be read from disk and stored in EA’s t_document table per MDG ID. You load the file via the View/Resources/MDG Technologies. It will then occur in this view as well as under Extensions/MDG Technologies where you find that it shows Location: Model. You can enable and disable the MDG here as any other MDG. If you remove it from here it will be removed from the Resources (and t_document) as well.

To load a new MDG for testing it is sufficient to re-import the file from the Resources view.

Shared file

The second way to load a MDG is to tell EA where user MDGs are located. This can be shared folders or URLs. Open Extensions/MDG Technologies and click Advanced. Here you can add/delete paths and URLs. EA will look into these locations to offer additional MDGs in the Extensions dialog. This way you can update the MDG on the fly so users have always the most recent version when starting EA. Vice versa if the file has been erased EA will just disable the MDG and not warn you in any way.

To load a new MDG in this dialog it is necessary to disable it and close the Extensions dialog. Now when you re-enable the MDG it will be read from its file location/URL. It is not sufficient to uncheck/tick the MDG without closing.

EA program folder

All of the MDGs listed in the Extensions dialog¹³ stem from EA’s program folder, namely the MDGTechnologies sub-folder. You could place your own MDG here, but that is not really recommended. However, it is often a good idea to remove the MDGs you will not use in the course of a configuration management. It might save you some trouble if you get unwanted stereotypes out of the way.

Reloading happens as described above for a shared file.

6.2 Using MDG Elements

Loading the MDG is one thing. But using the elements from the MDG is another story. Here I will talk about what happens when you actually use elements from your MDG.

Locating the right elements

Unless you assign elements to according toolboxes of custom diagrams the single stereotypes can be retrieved manually. To do that you can either use the properties window of elements and click the ellipsis button following the Stereotype property. Alternatively you can use the Stereotype field in the View/Properties window and choose browse other stereotypes... at the end of the drop down.

Your profile can be selected from the Profile drop down. Now you can see all the stereotypes where extensions to the metaclass of the currently selected element were defined. Here you can tick the appropriate one.

Tagged values

If you assign an element the matching stereotype (that is it has been defined for the same metaclass) EA will create the tagged values from the profile even if the stereotype has been defined in UML Types. Further if you change the stereotype from one existing profile element to another one EA will remove the TVs of the old stereotype and create those for the new one. It does not touch user defined TVs, though¹⁵.

Shape scripts

If you have defined a stereotype with the same name of one of your profile elements (e.g. Bike) in Project/Settings/UML Types and assigned a shape script¹⁶ then the latter will be used when rendering the element.

7. Versioning Profiles

Any MDG will vary over time. It’s definitely nothing build from concrete which will last over ages. There are two major reasons for change:

• The domain model changes along with the company itself or because some parts were modeled incorrectly for various reasons.
• The supported process will undergo some optimization not at last because the profile is being used.

So you need to face CRUD scenarios for anything inside a MDG: elements, diagrams and toolboxes.

Let us view the latter: toolboxes. Changes in this area are almost uncritical. It’s just the users that might get confused if the toolbox does no longer look like they used to be. There’s a simple solution and it’s called communication. So if you plan to change toolboxes just be sure to involved all people that may be affected and you are done.

As easy as this was, any other change offers the spectrum from minor trouble to catastrophe. Happily the worst case got more unlikely as it seems that the Sparxians really fixed wrong behavior from previous versions where TV creation from MDGs had changed dramatically. However, the manipulations described below come with absolutely no warranty and are on your own risk! Have a backup! Make a test run in a sandbox! Know what you are doing! A set of bleeding ears is guaranteed anyway.

7.1 Removing Stereotypes

If you happen to remove a stereotype from your profile you need to be sure to do it the right way. First the stereotype might be used in various toolboxes. So make sure to run the Extended Search. This will list also attributes which had been named after the stereotype in question. If in our example domain the Bike has to be deleted (just hypothetically) the search would list quite a number of elements. Eventually you could limit the search to <profile>::<stereo> (i.e. CBM::Bike in our domain) or simply ::<stereo>. Any ghost element in a stereotype would show up as (i.e. with the stereotype icon) in the toolbox.

If you have any elements using the deleted stereotype they will live on as zombies. That means they have an entry in t_xref¹⁷ telling they are from your MDG. But for EA your MDG does not have that stereotype and it will not remove the t_xref entry. So they appear in the tagged values still under the technology group. To get rid of those zombies you need the SQL¹⁸ pump gun

1 DELETE FROM t_xref WHERE description like "%FQName=<profile>::<deleted>;%"

where <profile> is the name of your profile and <deleted> the name of the deleted stereotype (i.e. in our example CBM::Bike).

7.2 Adding an Attribute

This can also be regarded as minor critical. The only thing to do is to synchronize the changed stereotype once the updated MDG is reloaded. You can run the synchronization from the stereotype in Diagram/Toolbox from the context menu.

This will add the new TV to where it is needed. The synch will list all elements that have been affected along with the TV that had been added. So far so good. But unfortunately you can not use the list for anything — no copy, not navigation. If you need to rework those updated elements you have to find ways to locate them afterwards.

7.3 Renaming an Attribute

Let’s assume you need to rename one of the attributes in a stereotype, be it to correct a typo or for orthogonality reasons. In that case you end up with already created stereotypes still using the old name. Only newly created stereotypes will receive the renamed attribute as TV.

Like above you can run the profile synch for the changed element. This will add the renamed tagged value as new entry but leave the old one as zombie.

Here you have two or three options. The first is to manually correct the TVs after running an Extended search. Probably the only alternative you have once you shot your patient. Eventually (as option 1a) you can run a SQL to clean the zombies from t_xref (see SQL above) and leave them as manually added TVs. Probably not the worst choice.

The second (or third if you count 1a) alternative is to take precaution and run a SQL to rename the TVs in the repository in advance to reloading the MDG. You would need to look into t_objectproperties.property and t_xref.description (and here the FQNAME-part). It might turn out that finding the right rows can be tricky if the old name is not uniquely to be found by its string value. You definitely need to run a SELECT to cross check the result set before running an UPDATE. Finally the SQLs could look like the following:

1 UPDATE t_objectproperties SET property="new" WHERE property="old"

This will work if the old name is unique. Else you need to JOIN t_object and t_xref with your search¹⁹.

1 UPDATE t_xref 
2   SET description = 
3     Replace('FQName=<profile>::<old>;', 'FQName=<profile>::<new>;')
4   WHERE description like "%FQName=<profile>::<old>;%"

7.4 Renaming a Stereotype

If you rename a stereotype in your MDG this will make all elements created from that stereotype be custom stereotypes. You will see that the TVs are no longer grouped under the profile but appear as ordinary TVs. Turning them back to the right position by unchecking the (now custom) former stereotype and re-assigning the new one from the MDG seems to help. But not really. The entry in t_xref still references the old and gone name. Just another set of zombies lurking around.

Unless you want to create new stereotypes, clone and re-link them before deleting the old ones you will for sure want a SQL that can help. The first of two needed updates goes to t_object:

1 UPDATE t_object SET stereotype="<new stereo>" WHERE stereotype="<old stereo>"

You need to be sure that there is no stereotype from another MDG used with the same name. Running a cross-check with SELECTing the right rows is crucial.

The second UPDATE goes to t_xref. In principle it is the same as described above for renaming an attribute. Only that here the Name-part is to be changes instead of the FQName

1 UPDATE t_xref 
2   SET description = Replace('Name=<old>;', 'Name=<new>;')
3   WHERE description like "%Name=<old>;%"

8. The Quick Linker

Here comes another nice gimmick. The quick linker (QL) is a special toolbox which allows context sensitive creation of links and eventually elements created at the other side of the link. This is very powerful for certain model parts. E.g. when creating a line of actions in an activity diagram.

In short the QL is defined by an Artifact element in your profile named QuickLink. This has a linked document with a CSV formatted text to define the (augmented) behavior of the QL whenever your MDG is active. That far things are easy and you can go ahead creating such an Artifact.

Use the Linked Document from the context menu and paste the following lines to it

1 Class,Bike,,,,Component,,Dependency,,to,,Depending from,TRUE,
2 TRUE,,,Component,,,,,,
3 Class,Bike,,,,Component,,Dependency,,from,,Prerequisite for,
4 TRUE,TRUE,,,Component,,,,,,

Don’t forget to save the changes (Ctrl-S), export the profile, re-generate the MDG and re-import it for testing: just drag the QL from a Bike element you created in the sandbox.

You now have the Component/Dependency from / Prerequisite for menu entries for a Bike element. Other or not stereotyped elements will not offer this menu. Choosing Prerequisite for will create a new Component

which has a dependency from the Bike.

8.1 Editing the Definitions

Before going into the details I like to explain how to edit the definitions for the QL a bit more efficiently²⁰. So useful the QL is in practice so painful (even more) is it to create a custom one for your MDG. Here are a few tips.

As a first step you should change the document format of the linked document to landscape. At least it will help spotting wrong line breaks.

Next add a line before the first you placed in the above example and reuse that for your own QL definitions:

1 //Source Element Type,Source ST filter,Target Element Type,Target ST Filter,
2 Diagram Filter,New Element Type,New Element ST,New Link Type,New Link ST,
3 New Link Direction,New Link Caption,New Link + Element Caption,Create Link,
4 Create Element,Disallow Self connector,Exclusive to ST Filter + No inherit 
5 from metatype,Menu Group,Complexity Level,Target Must Be Parent,Embed element,
6 Precedes Separator LEAF,Precedes Separator GROUP,DUMMY

To actually edit the definitions it is best to move them to a spreadsheet unless you like to count commas. The RFC for CSV is obviously ignored by anyone (I have not seen a single implementation which worked according to it). So the way to export as CSV and import CSV from file in the spreadsheet is not recommended. Vice versa the CSV export will also likely be scrambled and render to be unusable. I do it in three steps:

• Copy from linked document and paste into Notepad++²¹.
• Globally change comma to tab chars (using \t as replacement).
• Copy the whole text and paste to spreadsheet.

Now you have the data in a more handy format²².

As you can see the first comment line results in useful headers so you can modify the definitions a little bit easier.

Once you are done you need to move the results back:

• Select all cells from A1 to W* where * is the last row. It is important to include exactly the W column which is called DUMMY!
• Paste the cells to Notepad++.
• Globally change the tab char (again using \t) to comma.
• Copy the whole text and paste it to the linked document.
• Save the changes!
• Export the changed profile.
• Re-generate the MDG.
• Test the changes.

The above steps are error prone since you might forget one of them and loose your edits. But it’s proofed for me to be the least evil.

8.2 Testing the Quick Linker

Before going into details a short warning:

Now the Resources road is no longer that efficient. Instead the Advanced path from Extensions/MDG Technologies... is the preferred way. Since for testing we do need to restart EA it’s easier to set the path in the latter way which makes EA load the latest saved MDG automatically.

Further you should create a mini-model with a stripped MDG that mainly contains the QuickLink artifact and maybe a copy of your rest MDG. The QuickLink itself should contain only a single definition you are going to test. Only if this entry has been tested to work as expected it can go to the real profile. Also here you need to test again as the orchestration with many definitions can cause dissonances.

8.3 Operating Principle

One could probably write a whole book about the QL. So I can’t go into all bits and pieces. Anyhow, I’ll try to approach the QL with a couple of use cases.

UML already has constraints that certain connectors are only allowed between certain elements. The QL (as delivered by Sparx) not only respects these constraints but reduces the number of connectors it offers by the elements that are going to be connected to a most commonly used set. Also you will note that depending on the diagram where the QL is called the set of offered connectors differs. Though for the standard UML diagrams this is done by some internal magic you have the choice to introduce your own constraints.

Roughly spoken the QL is defined by a number of records that have filter constraints which influence the creation of its menu entries. Each record also has columns which flag the creation of links and eventually elements if the QL is dragged to an empty space on the diagram. While the pure filter entries work pretty much straight forward, the other columns may interconnect in a more complex way.

Link certain elements

Let us start with the most trivial example which is going to offer certain connectors between elements from the MDG. To stay in the example domain we would like to say Motor will <<drive>> the Gear where the connector is of type Dependency. So we are going to offer a link named drives in the QL.

The first 4 columns describe the source and target elements to be (meta)type and stereotype. That would be Class²³, Motor, Class and Gear. In columns H and I we place Dependency and drive for the connector type and stereotype. Column J becomes to²⁴ so the dependency will point from Motor to Gear. The label in the QL menu is placed in K and we simply name it drives (to imply when linking that Motor drives Gear). Now we need to flag that a connector is to be created by placing TRUE in M. All other columns are left blank.

1 Class,Motor,Class,Gear,,,,Dependency,drive,to,drives,,TRUE,,,,,,,,,,

Once you re-generated the MDG and drag the QL from Motor to Gear you should see the drives entry somewhere at the end of the menu.

Vice versa when dragging from Gear to Motor you will not see the entry. But often it makes sense to offer the entry in that case too and have the dependency created as if it were done from Motor to Gear. To achieve that we add a modified second entry to the QL definition. B and D will be swapped (A and C are already the same). J must be change to from and K to driven by.

1 Class,Gear,Class,Motor,,,,Dependency,drive,from,driven by,,TRUE,,,,,,,,,,

So no matter whether you use drives or driven by the result will be a <<drive>> dependency from Motor to Gear.

You probably have already guessed that columns A to D work as simple filter. E.g. if you leave column B blank and add add such a definition line with <<support>> and supports then you will have a supports entry if you drag the QL from any class to a Gear. In case of the source being a Motor you will see both the supports and the drives menu entry.

If you leave all of A to D empty the connector is offered for any QL menu²⁵.

Creating elements along with a connector

The initial example already introduced the creation of elements along with a connector. Now let us have a look at the details.

The columns A to D primarily act as filter. But additionally to the examples in the previous section the column N is set to TRUE which will instruct EA to offer an element creation menu if you drag the QL to an empty space. Now columns F/G additionally provide the information which element to create. Further column Q needs to define the name of the menu group (here Component).

Combining the previous two methods

If you want to both create an element when dragging the QL to an empty space and offering of link creation when dragged to an according element you can put that in a single directive.

So assuming that you want the Prerequisite/Dependency to be offered also when you drag from Bike to an existing Component you need to supply columns C/D (in this example with Component in C and D left blank) and K with an appropriate menu label (e.g. needs and supports or whatever you might think that fits here to create the dependency in either direction).

Filtering by diagram

As mentioned previously you can also apply a diagram filter. You do that if the QL entry shall be shown only in certain diagrams — or if you want to hide it in selected diagrams. For this purpose column E needs to be supplied with a semicolon separated list of diagram types. The following examples will be very (!) artificial but anyway, you will get the idea.

We just take the two connectors which create a component from the last section. Now we say that we want the Depending on only to appear in our Design and any Component diagrams while the Prerequesite for should be visible in all but class diagrams. To set the first filter column E must contain CBMDiagrams::Design;Component. The diagram from our MDG needs to be fully qualified. Since we did put the diagrams in the CBMDiagrams package this will be the prefix, the infix is :: and the suffix is the name of the diagram stereotype. Standard diagrams are that from the default list in section Custom Diagram. For the second connector we take the Logical (for class diagrams) and prefix it with an exclamation mark. This tells EA to match all but that one.

To test that the definition works you create/open a Design diagram first and place a Bike on it. When you drag the QL on an empty space you see just the Component/Depending from (since we explicitly told to show this connector on a Design diagram). And because it’s also a Logical (class) diagram the second connector is not shown.

The next test with a Commission diagram shows only the Component/Prerequisite for connector. This is because the diagram type is none of the first filter types and because it’s not a Logical the second one will show up.

The last test will be with a Component diagram and that will fit both criteria so you will see both connectors in the Component menu.

Summary of fields in the QL definition

As mention I will not describe all details of the QL but up to here it should cover at least 90% of all cases. Here is a summary of the columns used so far as well as some other (prefixed with a +) columns that might be of greater use.

A/B

These columns filter the starting element/stereotype. Only non blank entries are filtered.

C/D

In case you drag onto another element these columns define an additional filter analogous to A/B.

E

The diagram filter applies according to the diagram from where the QL is activated. A number of different FQN diagrams can be defined by separating them with a semicolon. Alternatively you can define a negative list by prefixing the FQNs with !.

F/G

These columns are only interpreted if you have set N to TRUE and you were dragging the QL to an empty space. In that case they define the element to be created.

H/I/J

These columns are only interpreted if M has been set to TRUE. In that case the QL will create a link as defined in these columns.

J

We already had to and from. But you can specify a number of different values here:

• directed: association from source to target
• from: association from target to source
• undirected: association with unspecified direction
• bidirectional: bi-directional association
• to: either a directed or undirected association, depending on the value of the Association Direction field in the options

K

The value in this column is shown in the menu in the case one a new link is being created (drag QL from element to element).

L

Like K but when dragging the QL to an empty space.

M

If TRUE the entry will be used in creating links (QL dragged from element to element).

N

If TRUE the entry will be used in creating elements (QL dragged from element to empty space).

+O

Set this to TRUE if you have left blank either A/B or C/D and want to forbid the creation of a connector to self.

Q

The name of a menu group which is to be shown only when creating a new element.

+V

Sets a separator above the entry in the menu. However, I never noticed any influence on the menu with this set to TRUE. YAEAB?

W

The do-not-forget-me column you always forget and hence rendering your QL definition invalid.

For all other fields I kindly ask you to consult the help. Good luck.

8.4 Sub-Menus

If you need to group multiple stereotypes you can do that with sub-menus. E.g. we want to put the two tools SprayGun and Wrench in a sub-menu named Tools in the Design toolbox. In the according diagram we need to create a new stereotype named after the sub-menu (i.e. Tools). Here we place the two stereotypes CBM::SprayGun(UML::Class) and analogously Wrench. We need the extension since Tool extends Class and Package. Also we must add the attribute isHidden with an Initial Value of true.

The sub-menu itself must be added to the main menu with an attribute ToolMenu.

Once you regenerate the MDG the Design toolbox will show the new Tools entry and selecting that will open a popup with the the two tools showing up.

8.5 Debugging

Creating a QL definition will make you gnaw your keyboard more than once. When I meant that EA is not forgiving and you cross-check three times before finding the missing export/comma/entry the next day you will know what I’m talking of. So I can not offer much help, except some starting points when something does not behave as you would expect it.

1. Did you save the linked document / export the profile (to the correct place) / re-generate the MDG? A quick peek in the MDG file itself (search for QuickLink) might help. But only if you followed my advise to work with only a single record in tests. If it does not contain what you would expect repeat the save/export/generate steps.
2. Have you supplied all columns (including the dreaded W-dummy) correctly? Cross check with a 2nd export from spreadsheet to Notepad++.
3. Are the filters correct? Try with a test record that has less filter criteria.
4. In case of empty menu entries: cross check the according K/L columns.
5. In all other cases: start with a (similar) working record and modify it step by step.

I encountered the following message when loading a newly generated MDG:

It appeared for various reasons as duplicate lines, missing or too many commas and I don’t know what. The only way to trace it down was by un-/commenting lines until one line was identified to be the culprit. That’s quite annoying thinking of the possibility to see a message like “Error in Line x of the QL”. Sigh.

In any case: if it won’t work sleep over it. The next day often solves the issue by itself.

9. Advanced MDG Techniques

In this chapter I will cover some of the more advanced things you can do with a MDG. Probably most users can live fine with the possibilities that have been explained so far. Alas, you often get appetite while you eat.

9.1 Creating a Shape Script

One really nice thing is that you can adorn the stereotypes from your MDG with an icon. For elements this can be displayed either as shape or iconic in some compass position of the element rectangle. Connectors can also be assigned different shapes. In the first case you should remember that the resulting diagram should not become a bling-bling PowerPoint. So don’t overdo this. Create a new shape only for a few important stereotypes and use icons (if at all) for the rest.

To make an example, we create a (simple) shape for the Bike. Open the attributes of its stereotype and add a new one called _image. Now click the ellipsis button in the Initial Value which will open the shape script²⁶ editor where you paste the following script²⁷:

 1 shape main{
 2   fixedAspectRatio = true; // can't set this conditional
 3   if(HasProperty('rectanglenotation','0')) {
 4     drawnativeshape();
 5   } else {
 6     MoveTo(10,10);
 7     PrintWrapped("#name# #tag:style#");
 8     ellipse(0,60,30,100); // front wheel
 9     ellipse(50,60,80,100); // rear wheel
10     if (HasTag("style", "Barebone")) {
11       ellipse(5,65,25,95); // front wheel
12       ellipse(55,65,75,95); // rear wheel
13     }
14     if (HasTag("style", "Dragster")) {
15       ellipse(3,63,27,97); // front wheel
16       ellipse(57,67,73,93); // rear wheel
17     }
18     MoveTo(25,60); // frame
19     LineTo(50,60);
20     LineTo(65,80);
21     LineTo(25,60);
22     MoveTo(15,80); // fork
23     LineTo(30,50);
24   }
25 }

Once you re-generated and applied the MDG you will see a bike symbol rather than the rectangle element. Further you will notice that the wheel shape will change with certain settings of the style TV.

As a second example we will add some cogwheel²⁸ to symbolize the Gear just as decoration in the top right area of the element. Just do as above but use the following script:

 1 decoration gear {
 2   orientation = "NE";
 3   setfillcolor(50, 100, 200);
 4   StartPath();
 5   MoveTo(0,50); LineTo(15,60); LineTo(8,80); LineTo(26,78); LineTo(31,100);
 6   LineTo(44,84); LineTo(58,96); LineTo(60,74); LineTo(78,71); LineTo(67,53);
 7   LineTo(80,37); LineTo(62,31); LineTo(63,9); LineTo(47,18); LineTo(37,0);
 8   LineTo(29,20); LineTo(12,16); LineTo(16,37); LineTo(0,50);
 9   EndPath();
10   FillAndStrokePath();
11 }

9.2 Multiple Metaclasses

In the previous example we just had stereotypes that extended a single Class metatype. But of course you can extend others and more than one metaclass. You will do that by drawing an Extends relation to more than one metaclass.

Deprecated is one versatile stereotype that I use to flag elements. The package metaclasses should contain all the metaclasses which have been deployed in the current MDG. So once the Deprecated stereotype is created just draw Extends relations to all the metaclasses. Optionally add a string attribute name Deprecation reason and one _image attribute containing

1 shape main{
2   SetFillColor(250, 250, 0);
3   DrawNativeShape();
4 }

When you apply this stereotype to any of your MDG elements (using the ellipsis button and the profile drop down) you will instantly see the element in diagrams in a yellow color. Since the Deprecated stereotype will be a secondary one its shape script is applied after the primary and replace it (sic!)²⁹.

Multiple metaclasses in toolboxes

If your stereotype is used in a toolbox and it extends more than one metaclass you need to tell EA which of the extensions you actually mean with the menu entry. This is done by suffixing the name with (<baseMDG>::<baseMeta>). Let us assume that in the sample domain we also need a general Tool class plus a Tool package to keep the tools one needs to build a bike from. The first is already present since Tool extends Class. We add a new metaclass for Package and draw an extension from Tool. Time to save the profile — at the right location.

Now we put two additional entries in the Design toolbox. One CBM::Tool(UML::Class) for the tool itself and CBM::Tool(UML::Package) for the package.

Saving the toolbox diagram — mind the right location once again — the re-generated MDG will now show two new entries for Tool and Toolbox.

While the first will create a Tool class the second will create a Tool stereotyped package for which you have to supply just the name.

9.3 Reference Elements by Tagged Values

In our sample we had a couple of associations where I said they will be ignored in the profile. Sometimes you want those relations to show up somehow in your model. This is the place where the so-called RefGUIDs come into play. These are simply TVs like we already defined via attributes in the stereotype. But they can be assigned from a selection which offers just a certain set of elements.

In our example we do have an association from Requirements Spec to Customer. You can just stereotype this association with <<taggedValue>> (available from the ellipsis button) and, once re-generated, your MDG will offer a TV for Requirements Spec that can be filled with Customer elements. To test that, you need to create elements for both stereotypes in the sandbox. Since we have not added them to any toolbox it is necessary to create plain class elements and set their stereotype manually from the ellipsis/profile dropdown for the MDG. To assign the Customer TV in the Requirements Spec you need to click the ellipsis button in the TV value field. The selection window that pops up will allow you to select one of the Customer stereotyped elements.

9.4 Creating a Composite Diagram

Another common use is to create a composite diagram along with an element. Usually if you create a composite diagram for an element EA will create one that is related to the metaclass (e.g. for a Class it creates a Composite diagram). In order to create one of the MDG-defined diagrams there needs to be a new metaclass in the profile. Assuming we want to have our Bike going along with a Design diagram we need to add a Class metaclass, add an attribute _defaultDiagramType, assign an Initial Value of CBMDiagrams::Design and move the Extension from the currently related Class metaclass to the newly created.

When you apply these changes and create a new composite diagram for a Bike element it will now be a Design diagram rather than a Composite.

Taking this one step further. Sometimes you want elements to be created as composite at once. This is simply done by adding the attribute _makeComposite with the Initial Value set to true in the new metaclass.

Now when you create a new Bike element it will be composite with a Design diagram inside.

9.5 Patterns

You probably know UML patterns from various books like Design Patterns. Patterns from the latter can already be created in EA if you enable the Gang of Four Patterns MDG. Like these standard patterns you can include your own patterns in your MDG.

In order to add a pattern you first need to create one. This is done by drawing a class diagram. E.g. in our example domain we want to create a basic bike that comes with motor, gear and an empty toolbox.

This is best placed in a Patterns package inside the MDG package. The diagram itself should be named after the pattern. In this case we simply call it Bike (as it contains the basic bike parts). As you notice the diagram uses elements from the MDG itself. This can easily be done by deploying the MDG in the MDG design repository itself.

Once the diagram is finished it needs to be saved as UML pattern. The menu for that is found in the main menu Diagram/Advanced/Save Diagram as UML Pattern... (and not the diagram pane context where you only can save it as profile, which is something completely different, and not in the context in the browser where you find none of the save options — EAUI).

The file should be placed inside the folder where all the other MDG stuff is already located. I chose a pattern sub-directory and saved the pattern with the same file name as the pattern itself.

In the dialog I ticked the Merge option for Class2 and Class3. This will allow to use existing classes to take place the according pattern position rather than creating new classes.

After the pattern itself has been created we need to create a toolbox entry in order to get access to the pattern. This is rather straight forward. We will just add it to the Design toolbox.

The format of the entry is <profileID>::<patternName>(UMLPattern). This will be shown with a icon. In the chapter Toolbox menus I will show how to change that to a more pleasing icon.

When re-creating the MDG you need to check the Patterns mark in the generation dialog. So you will be asked to locate the exported pattern in the following dialog session.

The pattern is now ready to use. When you select the pattern EA will pop up the pattern creation dialog. Since we made Class2 and Class3 miscible you can choose the Merge instead of the Create and locate the existing classes to be used.

Of course there is more about patterns. But using just these basic steps will give you a powerful tool to improve your MDG already.

9.6 Extending Other MDGs

A quite common use case is to extend some existing MDG (e.g. Archimate or BPMN). Luckily this got more convenient with the new EA releases. For example we want to add a Sales Channel that extends the BPMN2.0::Pool to our profile.

First you need to enable the BPMN2.0 MDG. Now we temporarily create a BPMN2.0::Pool in order to find out which metaclass it extends. Once created delete the stereotype from the dummy pool element and you can see its base metaclass

which in this case is ActivityPartition. Now you can safely throw that dummy element away.

The next step is to create that metaclass from the Metaclass toolbox by ticking the appropriate entry. Do not click OK but switch to the Stereotypes tabs. Select BPMN2.0 from the drop down and tick the Pool (you might want to sort the entries first — EAUI). Now when you click OK EA will create a stereotype (from BPMN2.0) and an ActivityPartition metaclass. Extend the first with the latter.

Finally we create a new stereotype Sales Channel, eventually add a priority attribute and draw a generalization to the Pool.

To test this, create a Other/UML/Activity/Partition (since we have not put it in any toolbox) and there from its stereotype choose Sales Channel from our MDG. You will now see all the TVs from BPMN2.0 along with the own priority TV.

9.7 Icons

As already mentioned it is possible to change the icon which appears with a stereotype in either the toolbox or for instantiated elements in the project browser. There are two ways to create such icons. One for stereotypes in general and another for just toolboxes.

Stereotypes

In order to improve readability of the toolboxes it is possible to replace the standard icons which are derived from the metatype. Instead you can create icons from your (shape scripted) stereotypes and supply them to be shown in menus and the project browser.

First you need to create a 16x16 pixel BMP icon for the stereotype³⁰. Since we already have a folder for MDG stuff it is best to add an icons folder therein.

Next the stereotype in question must be adapted. For the CBM::Bike EA will currently show a simple class icon. To replace that with something more unique you need to add two attributes to the stereotype. One is Icon with an Initial Value containing the file path to the BMP³¹.

The other one is _metatype which must contain a unique string. In this case we can simply choose it to be Bike³².

Once you re-created the MDG the CBM::Bike will appear with the new icon in the toolbox and in the project browser.

In case you used my template BMP: I know, I’m not an artist.

Toolbox menus

If you want to show an icon only in the menu (or if you have just-menu entries like patterns and sub-menus) the icon needs to be defined in a different way. So the according toolbox diagram needs some additions. We will add an icon for the Bike pattern.

In the Design toolbox icon we need to create two elements. One metaclass named ToolboxItemImage and a stereotype which must be named CBM::Bike(UMLPattern). Additionally this stereotype needs an attribute named Icon with an Initial Value containing the file name of the icon (here we will be using the bikeRaw icon from the resources).

Finally when the MDG is regenerated the Design toolbox looks like this:

9.8 Adding Searches

If you have created custom searches³³ that you want to distribute with your MDG you can simply do that during the MDG generation. You just need to tick the Searches option

and in the course of the generation process you will be prompted which of your custom searches to include. With the new MDG the Find dropdown will have an entry for your MDG where the included searches are present.

There are a couple of further entries besides the searches. Here’s a short walk-through:

Tagged Value Types

With this option you can define TVs you may add to arbitrary elements. Usually you will define drop down lists or RefGUIDs that link to your stereotypes. But there is another use yet. When you look at the Paper stereotype you find that once you create such an element the TV date will be a plain string. This can be made a calendar drop down by adding a Default TV Type named date and setting the Detail to Type=Date;.

When you include that in the newly generated MDG you will find that the TV date in a Paper now has turned into a calendar drop down.

Well, EA will now turn all TVs in your MDG that are named date into calendar drop downs. Probably not the most elegant way but if you know that it works this way it’s somehow viable.

And more

The remaining options during MDG generation will in parts be too broad to be covered in detail. So I will just list the options with a short explanation of their use.

Images

From the images imported via Project/Settings/Images you can select those to be part of the MDG. They will then be shown in the latter dialog as originating from the MDG. And of course you can use them for the Appearance/Select Alternate Image... option of elements.

Scripts

Any script you created locally can be included. These scripts will then appear under a group named after the MDG.

Workspace Layouts

If you need to supply some common workspace layouts with your MDG you can setup individual sets in your MDG repository. Once exported these working sets will appear under View/Perspectives/Workspaces³⁴. Here the entry has the Type Technology and as name <profileID>::<workspaceName>.

Code Modules

Here you can include either modified code templates for a language and/or that of a language defined especially four your needs.

MDA Transforms

This is used to export transformations defined in Package/Model Transformation (MDA)/MDA Transformation Templates...

RTF Templates

Your RTF templates defined with Documentation/Generate Documentation (F8)/Templates can be included in the MDG.

Linked Document Templates

In the View/Resources/Linked Document Templates/Model you can create templates from the context menu. These can then be included in the MDG.

Model Views

Model views which have been defined with View/Model Views can be included here.

9.9 Tag Grouping

Once you got the idea of adding TVs to your stereotypes you eventually see the need to add more and more and all of a sudden you have so many that you loose track. A good way to overcome that situation is by grouping TVs. These groups can be defined individually per stereotype but also in a way that influences multiple stereotypes.

As an example we start introducing groups for the Bike which we name Base Element, Purchase and Other. This is done by adding an attribute _tagGroups to the metaclass which is extended by Bike and assigning it the Initial Value

Base Element,Purchase,Other

which is simply a comma separated list. The next step is to define which TVs belong to which group. The names in this relation list can come from more than one stereotype. E.g. we will define a TV _tagGroupings with an Initial Value of

priority=Base Element;state=Base Element;delay=Purchase;vip=Other;

That means that a TV named priority in any stereotype extending this metaclass will appear in the group Base Element, etc.

Next we need to tell which of the groups shall appear expanded or collapsed. This is done with the attribute _tagGroupStates where we assign

Base Element=open;Purchase=open;Other=closed

So the first two groups will appear expanded while the last is collapsed. Finally we will put two (sic!) TVs into Bike, namely priority and vip.

Once you saved the profile and re-generated the MDG a newly created Bike will appear as this:

The TV vip will be unhidden once you click the plus-symbol near Other. The group Purchase is empty as the Bike does not have any TVs defined in this group.

I leave it to you to extend this metaclass by another stereotype. E.g. you can use Frame and move it’s extension around to this metaclass. Then you can add a delay TV (from the _tagGroupings above). In that case a newly created Frame would show the delay TV in the group Purchase.

10. Testing

First off: there is no debugging assistance. That is: all you see is that your MDG does not work. You even don’t get any hint something is rotten. So in any case you want to deliver an updated MDG you need to make sure your changes are ok. Plus it does not have influence on the existing structure.

The most common issue you will find is when seeing a menu like this:

The first you should do is to open the stereotype properties with the ellipsis button and see whether your MDG does appear in the drop down. If it doesn’t

• save all profile data and
• re-generate the MDG.

Also one of your toolbox might no longer appear. The most common cause is that the last saved profile went to the wrong location. Try exporting that once again and cross check the filename. Certainly it points to the wrong position. Then just

• save it at the right position,
• re-generate the profile that had been overridden and
• re-generate the MDG.

If it still does not work:

• Check the MTS parameters during the generation so the include all and the correct profiles.

Still no luck? Sleep over it. Throw the whole export away (or stow it somewhere) and create everything from scratch. You should be back in business.

Final remark

Congratulations! If you tried out all the steps you should be a pro and even if you skipped various steps you should be able to work on your own and improve your MDG. Personally, I have tried to put all of the information in this book that will be needed from the very beginning to a quite advanced area. The examples provided have been tested to quite some extend but since all this is just from the sandbox it is not comparable to any real life MDG. If you have any issues when trying to follow the steps above or whenever you spot errata please do not hesitate to contact me: thomas.kilian@me.com.

11. Glossary

Actor

An Actor is a person or system which interacts with a system in an → Use Case.

Attribute

An Attribute is an UML element which describes an aspect of a Class.

Architecture

A logical structure which describes a system such that from requirements over design to deployment each aspect is covered. Each reader (system users, software engineers, requirements mangers, etc.) of an architecture shall be able to easily extract the part that is relevant for him.

Business Object

An → Object that is specifically targeted to some sort of business. A good example is a Customer Business Object.

Class

A Class is an UML that represents an abstraction of real-world things that are related to each other. A Class is build from a classification process. A Class usually has different → Attributes and → Operations.

Connector

A visible → Relation between two elements.

Diagram

A visual presentation of part of an UML model. It helps the model reader to understand a certain aspect of the model.

Diagram Toolbox

A context menu for an UML diagram. It contains a relevant subset of UML elements for the individual diagram.

EA

Acronym of → Enterprise Architect.

EAUI

Acronym of → Enterprise Architect Unique Interface. A long time ago the Unique Interface was coined by forum member Paolo. I just build the acronym.

Enterprise Architect

Acronym EA. A tool that supports modeling of UML. Developed by Sparx Systems, Australia.

Folder

Is another word for → Package.

FQN

Acronym for Fully Qualified Name. In this book it refers to the notation <profileID>::<name>.

GUID

Acronym for Global Unique IDentifier. A string with hex-chars and dashes which is created in a way such that it is very, very unlikely (but not impossible) to see the same GUID for different elements.

Instance

Is another word for → Object.

MDA

Acronym for Model Driven Architecture. See http://www.omg.org/mda/ and https://en.wikipedia.org/wiki/Model-driven_architecture.

MDG

Acronym for Model Driven Generation. A container format to bundle profiles that can be enabled in EA dynamically.

Method

A piece of code performing some action. In a → Class the Method usually performs the operation on → Attributes of the Class. A Method can have parameters and a return value.

Object

An Object is a placeholder for a real-world thing. Objects are instantiated from → Classes. Vice versa a Class is an abstraction of Objects.

Object Oriented

A paradigm that sees the world as → Objects abstracted by → Classes with → Attributes and → Methods communicating via → Messages.

OO

→ Object oriented.

Operation

A synonym for → Method.

Profile

An arbitrary element set based on UML elements. In this book we use the single term profile as element set. Additionally the term will be prefixed with diagram or toolbox for those special subsets.

Package

A Package is an element to structure UML models.

Project Browser

An EA window which shows the elements of a repository in a tree structure.

Quick Linker

A tool to connect elements in → EA. Selected elements show a little arrow top right which can be dragged to another element or onto a blank space of a → Diagram in order to create a new element along with a → Connector.

Relation

An UML concept to tie two elements together. This is expressed through specific → Connectors.

RM

Acronym for Requirements Management.

Stereotype

A grouping characteristic which in → UML is shown as a string enclosed in guillemets (e.g. ≪device≫).

Tagged Value

A means to augment UML elements with extra information. Tagged values come in key/value pairs. In → EA the value can be a string, a drop down value or a references to another element.

Toolbox

An icon/name tuple used in menus. Toolboxes can be related to diagrams.

Use Case

A Use Case is a sequence of Actions triggered by an Actor and return some measurable value to that Actor.

View

A View in EA is a special form of a → Package.

UML

An acronym for Unified Modeling Language. UML is a language standard published by the Object Modeling Group (OMG). See http://www.omg.org

XMI

Acronym for XML Metadata Interchange. Allows to store UML models in XML format for data interchange. Like UML it is a standard published by the Object Modeling Group (OMG). See http://www.omg.org

XML

Acronym for eXtensible Markup Language. It is defined in the XML 1.0 Specification.

YAEAB

Acronym for Yet Another EA Bug. One tends to get sarcastic after many years living with the same set of bugs not being fixed.

12. Bibliography

Gamma, Erich et al.: Design Patterns. Addison-Wesley, 1994.

Kilian, Thomas: Inside Enterprise Architect. Leanpub, 2012. https://leanpub.com/InsideEA

Kilian, Thomas: Scripting Enterprise Architect. Leanpub, 2012. https://leanpub.com/ScriptingEA

Kilian, Thomas: Shape Script made easy. Leanpub, 2014. https://leanpub.com/shapescript

Object Management Group (eds.): Superstructures 2.5. Internet, 2015. http://www.omg.org/spec/UML/2.5/

Object Management Group (eds.): UML PROFILE SPECIFICATIONS. Internet, 2015. http://www.omg.org/spec/#Profile

Object Management Group (eds.): XMI 2.5.1 Specification. Internet, 2015. http://www.omg.org/spec/XMI/

Object Management Group (eds.): XML 1.1 Specification. Internet, 2003. http://www.omg.org/XML/

Notes