How to develop MDG’s for Enterprise Architect 9.x, part 1

How to develop MDG’s for Enterprise Architect 9.x, part 1

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, was maintained and updated in EA Version 9.3 and is now being maintained in EA version 10.x. In other words, The tutorial here works for all of these versions.

Update: Sparx Systems has recently announced EA 10, where the design and development of MDG’s has been given a major overhaul. These changes will be covered in a later blog post.

What is an MDG?

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. This is 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

A fully fledged EA MDG consists of at least three parts:

  1. A Profile containing your Modeling elements
  2. A Toolbox, where the Modeling elements are organized for easy access
  3. A Diagram, where the Toolbox is attached, for modeling the elements defined in the Profile

In this tutorial, I will cover the basics of how to develop the Profile, since the Profile can be used “as-is” without being linked to a Toolbox or a Diagram. How to develop a Toolbox and a Diagram is covered in part 2 of this series of tutorials. The goal is that each tutorial produces something that can be used right away, so the size and contents will vary.

These tutorials are based our need to develop an extension to EA for modeling WebServices for use by our Model Generator, TigerTeam Trimm. 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:

  1. The Elements for modeling Web Services, aka. the Profile
  2. A Toolbox, that organizes the elements from the Profile. Will do so in Part 2
  3. A Diagram for modeling Web Services, that defaults to our Toolbox and Profile elements. Will do so in Part 2
  4. The MDG control file. Keeps all the elements together when generation the MDG. Will do so in Part 2
  5. The generated TrimmWS Web Service MDG file itself. Will do so in Part 2

This picture shows how things are connected:

Everything is, apart from the MDG Control file and the generated Web Service MDG file, is modeled using 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 TrimmWS.eap”.

Organizing the MDG Project

Each part, Profile, Toolbox and Diagram, must be kept in separate Packages. Since they will all have the same name, I think its easier to maintain the MDG  if an extra Package level  is added where I can control the names myself. This is especially helpful for large MDG’s. You can see the layout of the TigerTeam TrimmWS Profile here:

As you can see in the figure above, add a Model View of type “Class” by:

  1. Right-clicking on the “TigerTeam WSDL MDD Package”
  2. Selecting “Add” -> “Add View…”
  3. Give the view the name “TigerTeam WSDL MDD” and select “Class view”
  4. Press “OK” and the Model View is created

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

Choosing a Profile ID

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 e.g our toolbox. I have chosen to give this MDG the ID “TrimmWS” since it is for use with the Trimm Model Generator and for modeling WebServices.

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, the Diagram where we define the WebService Design elements to go into our Profile. This is done as follows:

  1. Create the “nice-name” package that will contain the Profile itself. I have called it “TigerTeam TrimmWS Profile”
  2. Say Yes to creating a Diagram. I have chosen a “Package Diagram” with the same name as the Package, i.e. “TigerTeam TrimmWS 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 selecting “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 “TrimmWS”
  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 “<<profile>>TrimmWS” 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!

We have now created a “WebService” element that inherits from the built-in element Interface. The Profile will look like this once 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.

Question? 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

We have now 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. Tagged Values is the UML way to enhance e.g. Fields/Attributes on elements. Adding information to our elements are done on the Stereotype, i.e. our own model elements.

Adding Tagged Values is done by adding Attributes to the element. The “Name:” defines the Name of the Tagged Value and the “Type:” determines its type, e.g. a String will be translated into a string, an int to an integer and a boolean to a “true”, “false” select. Using the “Initial Value: ” you can control the Initial Value of a Tag. If you specify false on a boolean, it will be set to false when adding the element it is defined in to a diagram. 9 on an int will set it to 9 and so on.

This 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.

Enumerations

You might have noticed a new element on the diagram above called Enumeration. Enumerations are special modeling elements used for, you guessed it, Enumerated Tagged Vaues. “WhitespaceConstraints” is an enumeration and it is used on both WSAttribute and the WSElement. When the profile is generated, WSElement will get a Tagged Value enumeration called “whiteSpace” where 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 an Enumeration on an Attribute it is important that you do not just type the name of the enum in the “Type:” field. You HAVE to select the Enumeration using the “…” button next to the “Field:”. If you do not, it will not be generated correctly.

Tagged Values

What happens if you want to have more intelligent Tagged Values generated on your elements? For instance what if you need a list of links to to another element inside EA? 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. To do so I 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. To do so add an Attribute with the same name as the Tagged Value, and type the name of the Tagged Value type in the “Type:” field. In our case an Attribute named “Namespace” with the Type “Namespace”.

Note: If the Attribute do not have the same name as the the Tagged Value type, it will not work and will be treated as if it was a defined as a string.

This is how our Profile looks now:

Question? You might have noticed that you can define e.g. Enumerations as both Tagged Value types and as an Enumeration element 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 which 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 “<<profile>> TrimmWS” 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 “TrimmWS” and I have given the saved Profile XML file a name that contains the text “Profile”. This makes it is easier to locate it 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 the Profile from the Model 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.

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.

 
Comments

Hello,

I like this page, it is really usefull for creating a profile in Enterprise Architect.
But one thing I didn’t understand.
How is it possible to create a “Global Tagged Value” to my profile called “SYSMOD”?
I opened my SYSMOD-profile.eap File and go to – Settings – UML Type – Tagged Value Types and insert there my Tagged Value “Confidence”. I generate my MDG File and select the tagged Value and restart EA. If I open an element and go to tagged values, I can only see 1::Confidence, but not SYSMOD::Confidence. In your example is written TigerMDDWS::Fault Messages/ TigerMDDWS::WSNamespace. But I cannot see the different.

It would be great, if somebody of you can write me what I’m doing wrong.
Best regards, Caro

I found the answer! But if somebody has the same question, here the solution:
If you create the MDG File, there is some field called “ID”, this name is later on written to the tagged value, in my case. ID was 1, cause I thought it should be a number, I changed it to SYSMOD and it worked.

Thank you so much for your feedback and for the answer to your own question 🙂 We will make it more clear in the tutorial what the ID is used. I also made the mistake of using a number the first time I had to make my own MDG.

Please let us know if anything else needs clarification or if you have any ideas or needs for further Enterprise Architect/MDG tutorials

Trackbacks for this post