Introduction

In the first tutorial, we looked at how to develop the Profile containing the Web Service modeling elements and how to save it as a Profile that can be imported into EA. In this second part of the 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:
- The Elements for modeling Web Services, aka. the Profile. Did that in Part 1
- 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, 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 WS Toolbox”
2. Say yes to creating a Diagram. I have chosen a “Package Diagram” with the same name as the Package, i.e. “Tigerteam WS 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 called this one In our case “TTWSSLDesign”
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 “TTWSDLDesign” 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 name it “Tigerteam WSDL”. This name is the actual name of the toolbox and the name that will be shown in EA. For example, the “Profile” toolbox has 3 elements, named “Profile”, “Profile Relationships” and “Common” as you can see on the figure above.
3. Now we have to attach our “Tigerteam WSDL” Toolbox to our ToolboxPage by dragging an “Extends” arrow from the Toolbox to the ToolboxPage.

Before we can start attaching 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 “Tigerteam WSDL” 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:

TigerMDDWS::WSPackage(UML::Package)

“TigerMDDWS” 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 TigerMDDWS::WSPackage is based on a Package Element from the UML Namespace. In more general terms, the syntax is:

OwnProflePackage::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:

A little 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 “TTWSDLDesign” 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 “TigerMDSDWS” and I have given the Toolbox 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, 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 WS Diagram”
2. Say yes to creating a Diagram. I have chosen a “Package Diagram” with the same name as the Package, i.e. “Tigerteam WS 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 “TigerMDDWS”
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 “TigerMDDWS” 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 “TTWSDL”.
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 “TTWSDLL” MDG Diagram to the diagram we want to extend, by dragging an “extends” arrow from the “TTWSDL” 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 “Tigerteam WSDL” for this MDG Diagram
“DiagramID”	The MDG Diagram type that will appear in the diagram frame label. Here I use “TTWSDL”
“Toolbox”	The important one, that 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 out Toolbox. In this case it is called”TTWSDLDesign”

We are not fully done with the stereotype class, the “TTWSDL”, yet. We can give it a more human readable name by using the “Alias:” field, and I have chosen to call this “Tigerteam WSDL”. 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 “TigerMDDWS” 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 “TigerMDSDWS” 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 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 WDS MDD Technology.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. 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 WS MDD.xml” ready for distribution!

Distributing the MDG Technology

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

The simplest way is to copy the XML file containing the MDG, in our case “TigerTeam WS MDD.xml”, to the folder “C:\Program Files\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. Remember to restart EA after you have copied the file.

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 is located and press “OK”. Mine is located on the “W:\” 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 many ways to do it easier or simpler, but what I have described here is what I have managed to get to work.

Next step

I have not yet planned the next tutorial in detail apart from perhaps adding datatypes to the MDG and also how to make Quick Linker definitions. If you have any ideas please let me know.

Download the MDG files

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