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 and is now being maintained in EA version 9.3, so the tutorial here should work for both 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 “namespace” 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

Is there a way to create tab in the toolbox ? Like in the Class toolbox, there is the tab “Class” then “Class Relatinships”…
I haven’t find any solution for that until now

Yes you can. In part 2 of the tutorial I describe how to design toolboxes. I the example given there I only add one Toolbox, the “Trimm WS” toolbox, to the “ToolboxPage” metaclass and that creates one tab, as you call it. If you want more tabs, all you have to do is to add more toolboxes and have them extend the same “ToolboxPage” metaclass, and viola, you have more tabs. In our example we could add a toolbox called “Trimm WS Relationships” and add relationships to that.

Hope this helps.

Thanks for an excellent guide. To anyone else troubling with getting the toolbox working, remember that you have to re-save the individual profile, toolbox and diagram files if you find an error. I just wasted a few hours debugging my MDG model until i realized I had been generating the MDG file without updating the individual files 😀

Henrik Wivel

Thanks a lot for your positive feedback, Rune. You are right. I have been there myself 🙂

Another error I have made is to forget to change the filenames or select the right ones when I regenerate the individual files. That too can mess up the MDG completely.

Thanks for posting such a great series of tutorials — they are much easier to follow than the EA documentation!

Another “gotcha” I found with picking the Profile ID is it is limited to 12 characters (at least in the version of EA I’m stuck with at the moment).

Unfortunately I only found this out at the point of trying to build the MDG xml file, at which point I had to go back and refactor quite a number of packages, elements attributes and profile files… so it would have been a good limitation to know about before I started.

Thank you so much for your nice feedback. The EA documentation for version 9 is exactly the reason for the tutorials I wrote. Also for my own sake.

Thank you for mentioning the 12 characters limit. I will work it into the tutorials so others do not hit the same problem.

I would like to join my previous writers and thank you for this great tutorial. It saved a lot of my lifetime, compared to the work through the EA documentation. I got the whole thing to work for EA 12 with some fine adjustments, and therefore I’m quite happy.

I’ve two questions remaining:
– The first one is about the Tagged Values section in this tutorial. You talk about “WSNamespace”, “Namespace” and in the picture “namespace”. Do they all mean the same thing and are just typos or is there any difference? And is it right to write the name of the tagged value type into the name and the type of the attribute?
– The second one is more advanced. Is there a possibility to define more complex element patterns and add them into the toolbox? For example a class which has already some ports, or a class which has already an init() method, or something similar?

Henrik Wivel

Hi Markus.

Thank you for your kind words and thank you for your questions.

The Namespace thing is typos, that I will change to avoid confusion in the future. I am not quite sure what you mean by the second part of the Tagged value question. It has been a while since I wrote the tutorial, so I need a little more info here 🙂

As for the question about the more complex elements, there is no easy way. I spend quite an about of time on a similar problem and even asked Sparx Systems for help on that matter. The only way to add more complex elements is to add them as Patterns, which in my case was a bit overkill so I decided not to. If you have downloaded and added the Design Patterns from Sparx, you can get an idea of how it works.

Hope this answers your questions.

Hi Henrik,

in my first question, I made reference to the following sentence: >> “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.” << But with your response, everything is clear now. Name and Type of the attribute have to be the same, in this case "namespace".

Thanks for the hint to Design Patterns. I have looked at it briefly and it looks very promising. I think, I will check if they fit for me and if I can go on with that in the next few days. Another approach of mine was to extend my own implemented EA add-in with the EA_OnPostNewElement(…) add-in event. This works so far, but I've still some layout problems and it feels like a grubby workaround.

Thank you very much for your helpful response.

So, I looked through the patterns this week and want to share my findings for other people who came over here. First of all, the patterns worked perfectly for what I needed and surprisingly it is much easier to develop some patterns than the other individual mdg things. So if you need something like patterns, do not hesitate to use them.

Here is a small description how to use them:
– Create a profile package for the patterns like you did it for the profile/toolbox/diagram in this tutorial. (e.g named: TigerTeam TrimmWS Patterns)
– Create a class diagram inside the profile package and give it the name you want for the pattern.
– Draw your pattern inside the diagram. (e.g. some classes with methods/ports which are connected with each other, be creative)
– To save the pattern: go to the menu bar: Diagram –> Advanced –> Save Diagram as UML Pattern…
– To import the pattern to the toolbox use step 6 in this link (it’s similar to the other mdgs): http://www.sparxsystems.com/enterprise_architect_user_guide/10/extending_uml_models/toolbox_profiles.html
– You can create more diagrams in the profile package to create more patterns (or use new profile packages)
– To Generate the MDG Technology, just follow the instructions in this tutorial and add the patterns additionally in the wizard.

That’s all. Hope this helps 🙂

Henrik Wivel

Thanks a lot for testing out the patterns and reporting back here. It seems that I have to add another tutorial on Patterns and MDG’s to my series 🙂

Henrik

I’m having trouble importing the attributes once I create them. I’ve created a profile inside of a separate architecture and overall have followed the tutorial. However, when I import my profile into my full architecture, there are none of the pre-loaded attributes that I created in my profile. Am I missing something obvious?

Henrik Wivel

Hi Will

I am not quite sure what it is you are trying to achieve here. Can you perhaps mail me your project/EA File so I can take a look at it?

Henrik

Trackbacks for this post

Leave a Reply