How to develop MDG’s for Enterprise Architect, part 2

Introduction

In the first tutorial, we looked at how to develop the Profile containing the Web Service modeling elements for use by the TigerTeam Trimm Model Generator and how to save it as a Profile that can be imported into EA. In this second tutorial we will look into how we can make the Profile and its content more usable by combining it with a Toolbox and a Diagram into an MDG.

Why do we want to combine those and introduce the MDG when the profile already seem to do the trick? The simple answer is ease of use compared to using just the Profile. By adding a Toolbox and a Diagram, we can make our Profile act like any other built in feature and make it a lot easier to use.

This tutorial

In the first part, we created the Profile and tested it, so now we need to make its elements available in a Toolbox and a Diagram. In this part two of the tutorial we will still use the Web Service example and add the remaining elements to that. We still need to have the 5 following elements go together:

1. The Elements for modeling Web Services, aka. the Profile. Did that in Part 1
2. A Toolbox, that organizes the elements from the Profile
3. A Diagram for modeling Web Services, that defaults to our Toolbox and Profile elements
4. The MDG control file. Keeps all the elements together when generation the MDG
5. The generated TrimmWS 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, modeled inside EA.

Now that we have recapped, lets start defining the Toolbox.

Creating an EA Project for the MDG and organizing it

We will use the same EA project as we started in part one and it will still be organized as shown below:

Creating the Toolbox

The purpose of the Toolbox is to organize the elements in our Profile in neat sections and with nice names so it is easy for us to locate them and add them to our Diagram.

First step is to create the Toolbox Diagram and it is done like this. 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 TrimmWS Toolbox”
2. Say yes to creating a Diagram. I have chosen a “Package Diagram” with the same name as the Package, i.e. “Tigerteam TrimmWS Toolbox”

Now we have a Diagram where we can create the “real” Toolbox 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 Toolbox whatever name you like. I have chosen to give it the same name as my MDG, i.e. “TrimmWS”
4. Make sure that the “Automatically add new diagram” check mark is set and select a Class diagram.

More or less same procedure as when we created the Profile Diagram. Now you are ready to define your Toolbox. You should now have a diagram that looks something like this:

Designing our Toolbox

If you haven’t done so already, double-click on the “<<profile>> TrimmWS” Package to get to the Toolbox diagram. it is here we add the Toolbox Page and one or more Toolboxes. In our example we only need one Toolbox, but feel free to add more if you think the elements in the Profile needs splitting up. I usually separate the Elements from the Connectors in two Toolboxes to make it easier to locate the different elements.

1. First step is to create a Toolbox Page. This is done by adding a “Class” to the diagram, giving it the name “ToolboxPage” and the stereotype “metaclass”. We name it “ToolboxPage” because thats what Sparx Systems has decided the naming convention for Toolbox pages should be. If we call it something else, it will not work. That takes care of the Toolbox Page.
2. Now we can add our Toolbox. To do so, drag a Stereotype” element into the Diagrams, see below, and nam it using our chosen ID, “TrimmWS”.
3. Now we have to attach our “TrimmWS” Toolbox to our ToolboxPage by dragging an “Extends” arrow from the Toolbox to the ToolboxPage as shown bellow:

Before we can start adding our Profile elements to the Toolbox, we have to give the Toolbox an Alias and Notes. This is added to the “Notes:” field on the Toolbox Diagram Properties which you access by double-clicking on the diagram background. You should see something like this:

Alias	The name of the Toolbox you will see in the list of Technologies shown when pressing the “More tools..” button in the Toolbox pane
Notes	A small tooltip that is shown when hovering the mouse over an element in the Toolbox itself

Now we can move on to attaching Profile elements to the “TrimmWS” Toolbox. These are added as Attributes and follow a very specific syntax that is easier to explain by an example. Lets say we want to add the “WSPackage” element from our Profile to the Toolbox we will add an Attribute with the line below in the “Name:” field:

TrimmWS::WSPackage(UML::Package)

TrimmWS is the name of our Profile Package and acts as a namespace for our WSPackage Element. This makes it possible to mix elements in a toolbox from different Profiles.

(UML::Package) tells us that the TrimmWS::WSPackage is based on a UML Package Element from the UML Namespace. In more general terms, the syntax is:

OwnProfilePackage::OwnProfileElement(BuiltInProfile::BuiltInElement)

In the “Initial Value:” field on the Attribute, we write the more readable name we would like to have shown in the Toolbox next to the element Icon. In this case it is WS Package.

Note: The elements will be shown in the same order as the Attributes have in the Toolbox.

Once we have added the elements from our Profile that we want to be visible in the Toolbox, we have a toolbox that looks like this:

Tip: Here we only have one toolbox, but you can have as many as you like and you can have the same profile element in more than one. To add more toolboxes, just add them to the diagram, give them a name, and have them extend the ToolboxPage metaclass.

Saving the Toolbox

Saving the Toolbox is almost the same as saving the Profile. EA generates an XML file that in this case is the be included in the MDG file we generate later. The biggest difference is that the Profile HAD to be saved from the Package, but the Toolbox must be saved from the Diagram. Thats the only way I can make it work.

So, save it by right-clicking on the “TrimmWS” Diagram background and select “Save as Profile..”. EA 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 “TigerTeam TrimmWS” and I have given the Toolbox XML file a name that contains the text “Toolbox” so it is easier to locate later when I am using it in my MDG. The check-marks in the “Include” section does not really change anything when saving a Toolbox.

Don’t change the text in the “Notes:” field

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

Creating the Diagram

Now we have a Profile and a Toolbox, so what we need now to complete the picture is a Diagram. A Diagram that has our newly created Toolbox added to it, so we can create Web Services using a Diagram made for just that purpose.

Creating a Diagram is a variation of the theme of creating both Profiles and Toolboxes. In order to make it easier to understand the following chapters, I have chosen to call the Diagram we are creating for the MDG Diagram there is less confusion between that and the diagrams we use for creating and designing the MDG Diagram.

First step is to create the Diagram for the MDG Diagram and it is done like this. Again we are using the TigerTeam Web Service MDG as an example:

1. Create the “nice-name” package that will contain the MDG Diagram itself. I have called it “TigerTeam TrimmWS Diagram”
2. Say yes to creating a Diagram. I have chosen a “Package Diagram” with the same name as the Package, i.e. “Tigerteam TrimmWS Diagram”

Now we have a Diagram where we can create the “real” MDG Diagram 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. Just as for the Profile, you have to give the MDG Diagram Package the same name as you have chosen as an ID for your MDG. In our case it is “TrimmWS”
4. Make sure that the “Automatically add new diagram” check mark is set and select a Class diagram.

More or less same procedure as when we created the Profile Diagram. Now you are ready to define your MDG Diagram. You should now have a diagram that looks something like this:

Designing the MDG Diagram

If you haven’t done so already, double-click on the “<<profile>> TrimmWS” package to get to the MDG Diagram diagram. It is here we add the elements that is needed to define our MDG Diagram.

1. First step is to create a Stereotype class that will be our MDG Diagram and give it a name that makes sense for our MDG. Drag the Stereotype class onto the diagram and name it “TrimmWS”.
2. Next step is to tell which built-in diagram we want our MDG DIagram to be based upon. To do so, we add a “Class” to the diagram, giving it the stereotype “metaclass”. Naming it is a bit more tricky. The must always be prefixed with “Diagram_” and then the name of the built-in diagram type you want to base your own MDG Diagram on. I have chosen to use a Component diagram, so the metaclass will be named “Diagram_Component”, as you can see o the figure below. The full list of diagram types can be found in the EA User Guide. Just search for “Create Custom Diagram Profiles”.
3. Now we have to attach our “TrimmWS” MDG Diagram to the Diagram type we want it to extend, by dragging an “extends” arrow from the “TrimmWS” class to the “Diagram_Component” metaclass.

So far so good. Now we have the basics in place, but we still need to tell the MDG Diagram which Toolbox it has to use, what to call the MDG Diagram and so on. This is done by adding attributes to the “Diagram_xxx” class and the absolute minimum attributes are these:

alias	The MDG Diagram name that will appear on the diagram title bar in front of the word “Diagram”. I have chosen “Trimm WS” for this MDG Diagram
diagramID	The MDG Diagram type that will appear in the diagram frame label. Here I use “TrimmWS”
toolbox	The important one!!!. Tells the MDG Diagram which toolbox to automatically open when creating a diagram of this type. Here we have to type in the name of the stereotype Package where we have defined our Toolbox. In this case “TrimmWS”

We are not fully done with the stereotype class, the “TrimmWS”, yet. We can give it a more human readable name by using the “Alias:” field, and I have chosen to call this “Trimm WS”. We can also add a description in the “Notes:” that tells what the diagram is used for. This description will be show in the bottom right-hand corner of the “New Diagram” dialog when we use the MDG in the future, as shown below:

You should now have an MDG Diagram definition that looks like this:

There are lots more options to put on the “Diagram_Component” class, but they are not necessary for this example.

Hint: You can have as many MDG Diagrams in the same diagram as you like. Lets say you design and MDG that has elements that is to be used on a class diagram and elements used on an activity diagram. Then you create a Toolbox page per MDG diagram type and define 2 MDG diagrams and let each of them point to their own Toolbox.

Saving the MDG Diagram

Saving the MDG Diagram is the same as saving the Toolbox. EA generates an XML file that in this case is the be included in the MDG file we generate later. As with the Toolbox, the MDG Diagram is saved from the diagram to get it to work.

So, save it by right-clicking on the “TrimmWS” Diagram background and select “Save as Profile..”. EA 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 “TigerTeam TrimmWS” and I have given the MDG Diagram a name that contains the text “Diagram” so it is easier to locate later when I am using it in my MDG. The check-marks in the “Include” section does not really change anything when saving a Diagram.

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

Putting it all together in an MDG File

So far we have designed our Profile, our Toolbox and our MDG Diagram and saved them as 3 separate XML files. Now we have to make them all come together in one common XML file that contains the full MDG. In order to do so, EA has a built-in MDG generator that will generate 2 more files for you. One with “.MDG” suffix that contains information about what to include in the generated MDG and one with “.xml” suffix, that is the actual generated MDG file.

The MDG generator is a wizard where the steps are defined by what elements you want to include in the resulting MDG XML file. To make it all more clear I will bring you through all the steps necessary to generate the Tigerteam Web Service MDG.

1. First you start the MDG generator by selecting “Tools” -> “Generate MDG Technology file..”. You will be presented with this dialog where you just press “Next>”.
   
   
2. Now you have to decide if you want to continue without saving the MDG control file, create a new one or use an existing. I always create one so I don’t have to type in all my selections everytime I am generating a new version. Just to be nice to you, I choose to create a new MDG file, that I, of course, will reuse the next time I generate. I select “Create a new MTS file” and press “Next>”. The dialog looks like this:
   
   
3. We give our MDG control file a name and I have chosen to call this one “TigerTeam TrimmWS MDG.mts”. Press “Next>”:
   
   
4. Now it starts to get interesting. On this next dialog, there are a number of interesting fields:
   
   
   

   Technology	A human readable name for our MDG technology
   Filename	The name of the XML file that will contain the generated MDG
   ID	REALLY IMPORTANT!!!! The ID MUST MATCH the ID we have been using for our Profile and for our MDG Diagram, in this case TrimmWS If not, nothing will work

   
   The rest of the fields are optional and fairly self explanatory. Fill in the information you want to and press “Next>”
5. This next dialog is where we select what elements we want to include in our MDG. The remaining number of steps in the wizard is based on the selections we make here:
   
   
   Our MDG consists of a Profile, a Toolbox and an MDG Diagram, so we check “Profiles”, “Diagram Types”, and “Toolboxes. We also have 2 Tagged Value types, “WSNamespace” and “Fault Messages”, so we also check “Tagged Value Types”. Now we can press “Next>”.
6. In this step we select the Profile we want to include. It is here our naming convention comes in handy as you can see below:
   
   
   Select the file containing our Profile and press “Next>”.
7. We do the same for both the Diagram and for the Toolbox as shown here for the MDG Diagram:
   
   
8. And for the Toolbox:
   
   
9. Next we select the Tagged Value types we want to include in the MDG. I always remove the 3 default ones, that for some reason always are present, from the model so I don’t risk selecting them by mistake.
   
   
   I have selected all and then I press “Next>”.
   
10. Now EA will present you with an “are you sure you want to continue?” dialog, and if you are, like I am now, press “Finish”.
    
    

SUCCESS!!!!: We have now generated a complete MDG technology and it is saved in the file “TigerTeam TrimmWS.xml” ready for distribution!

Deploying the MDG Technology

Now we have a fine new MDG Technology, but how do we make it available to the rest of the world?

Simple file copy

The simplest way is to copy the XML file containing the MDG, in our case “TigerTeam TrimmWS.xml”, to the folder “C:\Program Files (x86)\Sparx Systems\EA\MDGTechnologies”, but that has its limitations. It will work fine if you are the only one using the MDG but if you are to distribute it to a larger number of users, it can become a hassle to make sure that everybody has the same version. Also you will mix your custom made MDG’s with the ones provided with EA and risk loosing it when you upgrade to a newer versionRemember to restart EA after you have copied the file.

Import locally via EA

Another way to import an MDG is by using the “MDG Technology Import” functionality of EA. Using that, EA will place the imported MDG under your Roaming User account making it accessible to you if you log-in on another machine on the same network under Active Directory control. The MDG will still be local to you, but available to you from other machines.

To use the MDG importer you have to:

1. Select “Tools” -> “MDG Technology Import”. You will be presented with this dialog:
   
   

   I have cheated a bit and already selected the “TigetTeam TrimmWS.xml” file containing the MDG.

2. Press “OK” and EA will ask you to restart . This is important because the MDG will not be loaded until all instances of EA has been shut down before you start Ea again. The dialog looks like this:
   
   

   The “TrimmWS” MDG is now imported and ready for use.

Note: EA will place the MDG’s imported using this method on “C:\Users\<your user>\AppData\Roaming\Sparx Systems\EA\MDGTechnologies”. To uninstall the MDG you will have to physically delete it from that location.

Using a shared directory

A more elegant solution is to use EA’s built-in MDG Technology organizer to include the MDG. By doing so you can place the MDG file anywhere you like, even on a shared folder, which makes distribution a lot easier. To do so you need to:

1. Select “Settings” -> “MDG Technologies..”. You will be presented with this dialog:
   
   
   As you can see, all the available MDG’s are listed here, but ours is missing. To add our MDG:
2. Press “Advanced..” and on the next dialog press “Add” and “Add Path..”. Select the directory where your MDG file(s) are located and press “OK”. Mine are located on the “Z:\” drive as you can see here:
   
   
   Note: You will only see the paths and not the files, so don’t worry. Just press “OK”. EA will tell you to restart and you have to in order to make the MDG appear on the list, as shown below:

   

The MDG is now ready to use.

Closing remarks

I hope you have found the tutorials on how to build an MDG for EA useful and helpful enough to start developing your own MDG’s. I am sure that there are other ways to do it easier or simpler, but what I have described here is what I have managed to get to work.

Next step

In Part 3 I will explain how to add Datatypes to our TrimmWS MDG and how make sure the TrimmWS elements make us of them in the most user friendly way possible

Download the MDG files

You can download the complete “TigerTeam TrimmWS” MDG model and files from our Downloads page.