Introduction

Those of you that have tried to develop MDG’s for Enterprise Architect (EA) will know that the documentation is not the most intuitive and that most successes are a result of trial and error. At least it has been so for me. So, to make it easier for you to develop MDG’s I have tried to write down what I have done to make things work. There might be other ways to develop an MDG and some of the things I describe might be done smarter or more “right”, but this is what I have found out works.

I assume that you are familiar with EA so I will not go into details with the basic functionality of the tool. The MDG started its life in EA version 8.0 and is now being maintained in EA version 9.0, so the tutorial here should work for both versions.

This is part one of a series of tutorial for building EA MDG’s and will cover the basics of how to get a simple MGD with a Profile, a Toolbox and Diagram up and running. The goal is that each tutorial produces something that can be used right away, so the size and contents can vary. This first part covers how to develop the Profile, i.e. the Modeling element of your MDG. The tutorial is made using a real life MDG for modeling Web Services, that we use internally at Tigerteam.

Stepping back a little

Enterprise Architect is a general purpose UML modeling tool from Sparx Systems in Australia. It has a lot of functionality built into it, but sometimes you want to extend that functionality, perhaps introduce modeling elements that fits better to your reality, to limit functionality or just customize the tool to make you work more effectively. Thats where the MDG technology comes in. MDG is what Sparx calls its enhancement and profile toolset and with that you can define everything from new modeling element to a full fledged new technology with generators and the like.

This tutorial

This tutorial is based our need to develop an extension to EA for modeling Web Services. It is already possible to do so in EA, but we think that EA’s way is too close to the “iron” to make much sense, so we decided to write our own. The MDG consists of 5 parts:
- The Elements for modeling Web Services, aka. the Profile
- The MDG control file. Keeps all the elements together when generation the MDG
- A Toolbox, that organizes the elements from the Profile
- A Diagram for modeling Web Services, that defaults to our Toolbox and Profile elements
- The generated Web Service MDG file itself

This picture shows how things are connected:

Everything is, apart from the MDG Control file and the generated Web Service MDG file, is modeled inside EA.

Now that the big picture is in place, lets get started.

Creating an EA Project for the MDG

It is up to you if you want to keep the MDG elements in a separate EA project, but I find it a lot easier to work with it if it is.

Creating an EA project for an MDG is the same as for creating any other EA project, so it will not be described here. I created a new EA Project called “TigerTeam WS MDD Model.Eap”.

Now would be a good idea to think about an ID for the MDG we are about to develop. The ID is, as it says, the Identifier for the MDG and must be unique across all MDG’s in order not to confuse EA when loading and using different MDG’s. We also need it internally when e.g. adding elements to our toolbox. I have chosen to give this MDG the ID “TigerMDDWS”.

Organizing the MDG Project

Each part, Profile, Toolbox and Diagram, must be kept in separate Packages but I think its easier to maintain if a Package level more is added where I can control the names myself, especially for larger MDG’s. You can see the layout of the Tigerteam WSDL profile here:

 

 

Here you can see an expanded view, where the content of the Toolbox and Diagram is shown. Here you can see the “real” profile packages contained in the more readable ones you saw earlier:

Creating the Profile

The Profile is where we define our MDG Modeling elements. All the Elements we define are build upon already existing EA elements that are extended using EA’s modeling facilities itself. E.g. we can define a “Car” elements that extends a UML Class and has “Wheels” and a “Color” Tagged Value attached to it.

First step is to create the Profile Diagram which is done as follows. The Profile Diagram is the diagram where we design the Profile and not where we define the Diagrams we want to include in our MDG. Designing Diagrams is covered in the second part of the tutorial. Again we are using the Tigerteam Web Service MDG as an example:
1. Create the “nice-name” package that will contain the Profile itself. I have called it “Tigerteam WS Profile”
2. Say yes to creating a Diagram. I have chosen a “Package Diagram” with the same name as the Package, i.e. “Tigerteam WS Profile”

Now we have a Diagram where we can create the “real” Profile package:
1. First we have to select the “Profile” toolbox. it is done by clicking on “More tools..” on the Toolbox window and select “Profile”
2. Drag the “Profile” package from the Profile toolbox onto the diagram
3. Give the Profile the same name as the ID for you MDG. In our case “TigerMDDWS”
4. Make sure that the “Automatically add new diagram” check mark is set and select a Class diagram.

TADA!!! Now you are ready to add elements to your Profile. You should now have a diagram that looks something like this:

Adding Elements to the Profile

Now comes the fun part. Adding elements to the profile. All elements are derived from already existing elements in EA and the way of modeling it is fairly simple. If you haven’t done so already, double-click on the “TigerMDDWS” package to get to the Profile diagram.

The built-in elements hidden behind the “Metaclass” icon and the elements we define ourself is hidden behind “Stereotype”, so to add a new Element:

1. Add the Metaclass you want to extend. Select the element(s) from the list, e.g. “Interface”, as shown below:

2. Add the Stereotype class and give it the name you want it to have. Its your MDG so you decide. We want an element called “WebService” that Extends “Interface”. Here you can see all the elements in the Profile toolbox, including the Metaclass and Stereotype elements:

3. Draw an “Extends” from the “WebService” Stereotype to the “Interface” Metaclass and you are done!

Now we have created a “Web Service” that inherits from the built-in Interface! It will look like this when the “WebService” has invited some of its friends:

Note: If you give your element a color, it will have the same color when used from your Profile. Here all WebServices will be blue.

When to use “Extends” and when to use “Redefines”? Good question. I have not found the definite answer to that, but I use Extends when I create custom modeling elements and Redefines when I want to include a standard UML Modeling element in my MDG. For instance if I want to include an UML Package in my Profile, I add the Package Metaclass and a Stereotype called “Package” that redefines the Metaclass Package.

Adding information to our Elements

Now we have created some Web Service elements but to make them more useful, we must add more information to each element. The information we add will be generated into Tagged Values for the element, which is the UML way to enhance the Fields/Attributes on elements. Adding information to our elements are done on the Stereotype, i.e. our own elements.

Adding information is done by adding Attributes to the element and since it is standard EA behavior, it will not be described further here, apart from this screenshot of the “length” attribute on the “WSAttribute” element:

After having added information to the elements shown above, our little model looks like this:

Not to leave you completely in the dark when it comes to adding attributes, here are a few comments. All attributes prefixed with an underscore are used for controlling the behavior of the element and will not be visible in the Profile. I always use “_metatype” on all elements, because it tells EA how to generate the default name of the element when added to a Diagram. If I had not used it on WSAttribute or WSElement, they would just have been called “attributexx” by EA when adding them to a diagram. Now they are called “WSAttributexx” and “WSElementxx” respectively. _SizeX and _SizeY is a percentage that species the hight and width of the element when it is added to a diagram.

I always place the “_abcxyz” attributes at the top of my elements. It makes it easier to read. For a complete list, look for “Supported Attributes” in the index of the EA User Guide.

A little tip. If you want any of your attributes to have a default value, you can add it in the “initial Value:” field on the attribute.

Enumerations

You might have noticed a new element on the diagram above called. Enumerations are special modeling elements used for, you guessed it, enumerations on elements. “WhitespaceConstraints” is an enumeration and it is used in both WSAttribute and the WSElement. When the profile is generated, WSElement will get a Tagged Value enumeration called “whiteSpace” here you can select the values “preserve, “replace” and “collapse”. Enumerations are added to the Diagram by dragging the “Enumeration” from the Profile toolbox onto the Diagram and add each of the Enum values as Attributes without any Type information.

When using theelement on an attribute it is important that you do not just write the name of the enum in the “Type:” field, but that you select the element using the “…” button next to the it. If you do not, it will not be generated correctly.

A little tip. You can define a default value for your enumeration by putting the name of one of the enum values in the attributes “Initial Value:” field.

Tagged Values

What happens if you want to have more intelligent Tagged Values generated on your elements? For instance you need a range constraint of a link to another element inside EA so what to do? In EA you can add rather intelligent Tagged Values to a model if you go to “Settings” -> “UML Types…” and select the “Tagged Value Types”. Here you can add more complex and intelligent Tagged Value types that you can use from your Profile elements.

In our case we needed an URL NameSpace tag on our WSPackage, so we added a Tagged Value type called “WSNamespace” and in the “Detail:” field we added the text “Type=URL;”. Now we have defined the Tagged Value type and it is ready to be used in our element. Just add an attribute and put the name of the Tagged Value type in the “Type:” field and you are good to go as you can see here:

You might have noticed that you can define e.g. Enumerations as both Tagged Value types and aselements and both will result in the same. The same goes for String, Double and many of the simple types. so which one to choose? Again a good question and I have no good answer. When you define them as Tagged Value types, they are generated into your MDG as globally reusable Tagged Value types, i.e. you can add them as tagged values to any element in your model. When you add them directly to the element, they belong to the element only, and cannot be reused. You can argue its flexibility over control and you have to decide based on the type of MDG and technology you want to implement.

Saving the Profile

Saving the profile means generating an XML file that can be used either as “just” a profile or as part of an MDG. No matter what we choose, saving it is done in the same way. Here is where it gets a little tricky. you can save a Profile by either saving it from the diagram itself, or by selecting the Package containing all the elements in the Profile and saving it from there. I have never been able to make it work if I save from the diagram, so when you save the profile, do it from the Package. It will save you a lot of late night trial and errors.

So, save it by right-clicking on the “TigerMDDWS” Package and selecting “Save Package as UML Profile”. It will present you with this dialog:

I will recommend placing all the MDG files in a separate directory to make it easier to maintain. I have a directory called “TigerMDSDWS” and I have given the saved ProfileXML file a name that contains the text “Profile” so it is easier to locate later when I am using it in my MDG. I will be doing the same for the Toolbox and Diagram, but more on that later. When you save you can decide which properties you want to include in the Profile. I have neither alternate images nor code templates, so I could uncheck them. I need the Color and Appearance though since I have colored some of my elements.

Its always a good idea to give the profile a little comment in the “Notes:” field.

Press Save and EA will generate an XML file containing the Profile.

Using the Profile

Ultimately we will be including the profile in an MDG, but until then we can use it as-is by importing it as a profile. I always do so myself in the early stages of developing an MDG so I can test if the Profile is working before going on defining toolboxes and diagrams.

Importing the profile is done using the “Project Resources” window. If you don’t have it activated you can do so by pressing “Alt+6″.

1. Right-click on “UML Profiles” and select “Import Profiles”
2. Select the Profile XML file we have just generated and press “Import”

Our Profile is now imported and you can use the Elements by dragging them from the Profile onto any Diagram you like:

Once you have done testing the Profile, just delete it by right-clicking on it and selecting “Delete Current Profile”. It only deletes the profile from the Model. Not the XML file containing the Profile.

A little hint. If you update your profile with new tagged values and want to apply these to already modeled elements, you have to right-click on the element in the “UML Profiles” tree and select “Synch Tagged Values and Constraints…”. If you do not, only elements added after the change will have the new/updated Tagged Values. The same is the case if you apply a stereotype from your Profile to an already existing element. Lets say you create an UML Interface in a diagram and give it the stereotype “WebService”, the Tagged Values from the WebService element in our Profile will not be applied until you synchronize the Tagged Values. Not a bug, but as designed, according to Sparx.

Another hint. You cannot delete Tagged Values when synching the element. If you remove a Tagged Value it will only be active on elements created after you deleted it. You have to manually delete i from already created elements. According to Sparx, its not a bug but as designed.

Next step

The next step from here is to add a Toolbox and a Diagram to our model to be able to generate our full MDG. Since the Toolbox and Diagram is closely related, they, and generating the MDG, will be covered in the same tutorial.

Download the MDG files

You can download the complete MDG model and files from our Downloads page.