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

How to develop MDG’s for Enterprise Architect 9.x, 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:

AliasThe name of the Toolbox you will see in the list of Technologies shown when pressing the “More tools..” button in the Toolbox pane
NotesA 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:

aliasThe 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
diagramIDThe MDG Diagram type that will appear in the diagram frame label. Here I use “TrimmWS”
toolboxThe 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.

Controlling the name shown in the Add Diagram … dialog

When you add a digram in EA you are presented with a dialog, like the one shown below, where you first select the MDG Technology, the “Select from:” list and then the actual Diagram contained on the MDG, from the “Diagram Types:” list:

New-diagram-with-nice-name

We have selected the “Trim WebService” MDG, but where does that nice name come from? As with the Toolbox profile, it comes from Alias information added to the “Notes:” field of the Diagram’s diagram properties. Double-click on the diagram background and you will get this dialog:

Diagram-diagram-profile

AliasThe Alias, i.e. the displayed name of the MDG as it will be shown in the “Select from:” list on the “New Diagram” dialog, in this case “Trimm WebService”. If Alias is not used, EA will use the Technology ID, in our case “TrimmWS”. I some cases it is sufficient, but I like the name to be more descriptive
NotesA small tooltip that is shown under the “”Diagram Types:” list on the “New Diagram” dialog. If not specifie, no notes will be shown

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:


    TechnologyA human readable name for our MDG technology
    FilenameThe name of the XML file that will contain the generated MDG
    IDREALLY 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, “namespace” and “faultMessages”, 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?

Note: If you have developed an MDG that contains either Diagram Wizards or have used EMF images to change the appearance of your elements, they have to be installed/copied manually you have installed the MDG file. As a general rule, Wizards and EMA files must be copied to the same folder as the MDG. EA does not have any import facilities for that, so if you would like to have an easily installable MDG, you have to build install scripts for them or package them as an EA Add-in. Seems to me to be a prime candidate for an enhancement request.

Always remember to restart all instances of EA after having installed the MDG files.

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 version. Remember to restart EA after you have copied the file.

If your MDG contains EMF files, they must be copied to the same folder. Wizards can also be copied to the MDG folder, but it is more correct to place them in the “C:\Program Files (x86)\Sparx Systems\EA\ModelPatterns” folder.

To uninstall the MDG files, they have to be manually deleted from the respective folders.

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

If your MDG contains EMF files or Diagram Wizards, they must be manually copied to the same folder. To uninstall the MDG you will have to manually delete its files.

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:

If your MDG contains EMF files or Diagram Wizards, they must be copied to the same folder as well. To uninstall the MDG you will have to manually delete its files.

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.

 
Comments

Really valuable tutorial.

But a “Page not found” error appears when trying to download the MDG file.

When clicking the link on the Downloads section.

Can you correct it?

Thanks

Thank you for informing us about the download error. Fixed, so please try to download again.

This tutorial is perfect. It helped me a lot.

You could write about how to assign an icon to a toolbox item. It’s not hard, but will save us some time.

Thanks

Henrik Wivel

Thank you for your feedback. Yes, I will include a description on how to add icons to a toolbox item too.

Henrik

Nice tutorial!

But I’m wondering… How can I open an existing MDG file (eg. BPMN 1.1 Technology.xml) to add some tagged values? –> Now I have changed the XML itself, but it seems easier if I could open the MDG in enterprise architect…

And second question: how can I update existing elements after changing the xml?

Thanks!

Thanks. Always nice to know that what you have made is useful.

The short answer is that you can’t. The MDG files provided by EA and Sparx are to be regarded as compiled MDG and since you do not have the the source, i.e. the EA Model for the MDG, you cannot open it. The only way to change them is to update the generated XML files directly.

I am not quite sure what you mean by your second question. Do you mean how you update the models where you have already used the elements that you have changed?

Henrik

Hi again

Just a follow up on your question about using elements from already existing MDG’s. I said that it was not possible but I was lying as it turns out 🙂 You can use elements and it is fairly easy.

If you want to use them directly without modification, you add them to your toolbox in the same way as you would add elements from your own profile, i.e. you enter:

TechnologyID::ElementName(UML::ElementName)

For example for BNMN 1.1 you could enter:

BPMN1.1::BusinessProcess(UML::Activity)

If you would like to Inherit from an element and add your own properties to it, the EA online help describes how to Create Stereotypes Extending non-UML Objects, as they call it. You can find it here in the online documentation:

Extending UML Models -> Using UML Profiles -> MDG Technology SDK ->Developing Profiles -> Create Stereotype Profiles -> Create Stereotypes Extending non-UML Objects

Hope that helps.

Henrik

Hi, thanks for the guide. I build a toolbar for a custom diagram with tens of elements.
The elements I use have each an attribute ‘metafile’ pointing to an emf picture in the same directory as the profile xml will be exported. When I use this profile by import in Resources of a project, the elements are shown with their emf picture.

This does not work if I add the elements from the toolbar without importing the profile in the resources….. how?
I have also added all pictures to the Picture Manager and included them in the MDG wizard (Other->images). Still it does not work (and I also tried reimporting the newest MDG and restaring EA)…

Do you have a tip? thanks
Atam

Hi Atam

First of all, thank your for using our tutorials. I hope you find them useful.

Let me se if I understand you correctly. Are you adding custom icons to the elements in the toolbox or is it metafiles that changes the appearance of the elements once they are dragged into a diagram?

As far as I understand, all icons, bitmaps and the like is being “compiled” into the MDG’s XML file as Base64 encoded elements, so it should work without you having to add the Profile part to Resources. I have never tried it myself, so let me try it out and get back to you.

Henrik

Hi Henrik, thanks for your reaction and time.

It is the second option “metafiles that changes the appearance of the elements once they are dragged into a diagram”

In the profile where I define the elements, each element has a ‘metafile’ attribute with initial value pointing to an EMF picture (which is in the same directory of the Profile xml….) e.g. ElementName.EMF.

If I use this profile directly in another project bij importing under Resources, and from there I drag such an element in a diagram, the element is rendered using the EMF picture. Bear in mind that I imported the profile xml directly.

If I build an MDG containing the mentioned profile and diagram + toolbar profile, and use this MDG in another project (instead of using the profile xml directly under resources) and drag the SAME element to the diagram BUT this time from the toolbar…. the EMF is not shown and standard rendering is done.

I hope that I have made the problem clear to you 🙂

Thanks,
Atam

Perfectly clear, Atam. I will get back to you as soon as I have made some tests myself.

Would it be possible for you to send me a copy of your MDG files? Just send them directly to me. You can find my mail address in my contact information in the “About us” menu.

Henrik

just send you an email 🙂

Think I have found the problem. The documentation states that all metafiles must be in the same folder as the MDG for them to work, and they are NOT generated into the MDG file. So you have to copy them to the MDG install directory yourself or write an install program for them.

I have the same issue when it comes to deploying Diagram Wizards as part of my MDG’s.

Hi Henrik. I have send the solution to sparx support team. They will take a look at it and provide feedback. When they do, i will post the solution here for everyone.

Bye, Atam

ok, with help from Sparx support team i got this working. Their reply:

“Unfortunately it’s not currently possible to apply an image in an MDG
Technology using the metafile attribute as you described. Our developers
have confirmed that this is a bug and it is logged to be fixed. We cannot
yet say when (in which build) the fix will be implemented.

Currently you should be able to get the result you are after by using a
shape script instead. For example…

shape main
{
image(0,0,100,100,”mypicture.emf”);
}

Where “mypicture.emf” is the name of the image file, which must also be
included in the MDG Technology.”

Thanks!
Atam

Thanks a lot for your feedback, Atam. It is really helpful and glad that there is a workaround.

Henrik

Trackbacks for this post

Leave a Reply