One of the great things in EA is the possibility to extend standard UML modeling by usage of so-called MDG (Model Driven Generator) files. With these you can - in short - add own diagram types offering your own sets of stereotype elements and connectors (with individual shapes) in customized tool boxes. Here is how you can approach the generation of such MDG files.
Having an individual MDG is a must for large projects. Most domains have a specific language that needs to be reflected as good as possible via UML. Whenever you start setting up a MDG you should at least have your domain analysis in a final state. This domain analysis needs to tell you
- which domain objects exist
- which of them are important (need a special optical representation)
- what diagrams need to be created.
The latter will usually evolve during the usage of the MDG, thus you need to be prepared for iterations (changes in the MDG are crucial and need to thought over thoroughly).
Now here are the steps you need to follow to create your first MDG. The attached model is not a multi-part tutorial but keeps the initial and the final state. You should however be able to walk along in your own model in parallel using the sample as reference.
You might notice later that when I created the sample I actually did not have a specific domain in vision when I started - except: something with cars which can be understood by most people. So the real domain evolved during creation of the tutorial. It turned out that the domain is a custom car manufacturer.
This sample has been created with EA 8.0 (the most current build at time of creation). However, it should work with most pre 8.0 builds as it does not contain to awkward constructs.
The most important part is the profile. This tells you which model elements are available for the modelers in EA. These model elements, once present, can be created by drag and drop or via the blank-context menu. So lets first start creating that.
I simply copied the whole diagram Model.PIM.Domain Model with a deep copy to Model.PSM.MDG.CProfile.Domain Model. You now have an unreferenced duplicate of your domain elements. I keep relations simply by name since the domain must not change. If so, something‘s wrong in the state of Denmark. Note that the name of the Profile package here is CProfile and should usually reflect the customer domain name or brand. The stereotype must be set to «profile» so you can access the profile modeling tools inside.
Now you have all the domain elements as a copy. You might not need all of them for the profile and are free to delete unneeded stuff. Also the copied relations are actually not needed for the profile. They are however ignored for the profile itself and you also choose to leave them as they are.
First of all we need these special stereotyped elements. Edit the properties of an arbitrary element and change the stereotype to «stereotype» (you must not copy the guillemets). Now select the element on the diagram and drag/drop from the little arrow symbol. Choose Metamodel/Extend which will open a form that offers a lot of check boxes. Just select Class in the left window and press OK. That will create a «metaclass» Class with an incoming «extend» relation. Change the stereotype for another element as above and select it on the diagram. Drag/drop from the arrow icon to the new «metaclass» Class and select Extend. You now have two incoming «extend» relations for «metaclass» Class. Repeat until you have all elements connected.
A quick test/MDG structure
We now need to export the profile so it can be used later during modeling. We just want to do a quick check but it‘s wise to save the profile export in the right place. Create a folder MDG (or whatever name you like) and inside a sub-folder with the name of the Profile. More files will come later and this should be the place for the profile itself.
Right click the CProfile package and select Save Package as UML Profile. Navigate to the folder and save the profile under the name CProfile (which will get the extension .xml). Just Save with defaults.
For the quick test we import the profile temporarily via the Resources window (tricky to find like all View windows; it changed from 7.5 to 8.0 so I don‘t give the position here; or simply use Alt+6 but who can remember that shortcut?). Right click the UML Profile folder in the Resources window and select Import Profile. Choose your exported .xmi and notice the new entry CProfile. Open it and drag one of the element onto the currently open diagram. You should see a new stereotype which has has that tagged values you specified in the domain/profile. Also the tagged values should behave meaningfully. For example the Style takes the drop down entries directly from the CarStyle enumeration.
Now it is obvious what the profile is good for. Basically it provides accordingly stereotyped elements with tagged values. And much more of course but we cannot cover that here.
Your quick test is done and you can safely delete the profile from the Resources (Delete Current Profile from the context menu).
Iteration 0.5/Side note
As I am developing this sample I eventually find my domain model incomplete (as stated above). Now I have to copy paste the completed domain diagram once again needing to repeat above steps from Iteration 0. This is tedious and EA basically provides a method to do this much easier: namely by Transformation. Instead of copy/paste of the diagram I could have chosen Transform package (with the not existing 1:1 transformation, aka. duplication). In that case EA would have kept internal references and only changes would have been forwarded in the next transformation. That would have been cool: add the attribute in the domain model, transform, ready. Unfortunately I have lost my own 1:1 transformation and EA does not come with a build-in. It is not too difficult to write such a transformation, but it is once again Monthy Python: A completely different story. A proprietary script language.
Now that the profile works basically you will likely see some more enhancements. Go back to the CProfile diagram. Select the Car stereotype and edit the attributes. Add an attribute named _image and click the ellipsis. Get the text from the final model by also clicking the ellipsis of the _image attribute and copy/pasting the source. Do the same for Motor.
Once again repeat the quick test above. Now you will notice that all Motor elements appear in red color. Cars have a decoration pattern which will change to be hollow after clicking Abstract in the element properties.
Your profile is initially done. You will definitely need to rework after a couple of days using it. Probably you will find out that you get a lot of «metaclass» elements so these should be moved to separate packages inside the profile. Also it is advisable to move the enumerations out of sight.
Eventually you will have detected that for cars you will not only need stereotyped classes but also packages for grouping them. Simply add an extends relation to a «metaclass» Package and your done. Repeat the quick test and notice that a Car package now shows the icon like the Car class. I leave it to the reader to move the icon away from the awkward position it has now.
You want to express that certain motors and gears fit each other. Simply you could use a stereotyped relation called "fits", based on an association. So let's create that. Add a new «metaclass» Association (to be found in the right part window now) and drag/drop a Metamodel/Tagged Value named "fits" (without quotes, of course). You might do fancy things with shape script and this relation later if you need to. Left open for your own study.
As alternative you can also express the relation via a tagged value appearing in Motor which lets you select elements of stereotype Gear. Press the space bar to select Tagged Value. Now click and draw from Motor to Gear and name the target role of the relation "fits" (see above). No idea why the quick linker does not provide the right relations. Well. I also do not grasp why the multi-select does not work here when you set the multiplicity to 0..*. The whole matter is complicated and the reader might give me feedback what's wrong here.
Quickly test it and you will see the new "fits" stereotype as well as a tagged value of the same name for a Motor class. Create a Gear element and drag the fits relation from the Resource onto the Gear. A pop-up will allow to select the Motor class and the new relation is stereotyped «fits». Note that this clumsy behavior will not occur later in the MDG. It is just for the test. Check the alternate way with the "fits" tagged value in the Motor class. The ellipsis allows navigation to just «Gear» stereotyped classes. Once again: no idea why the multiple select does not work here. Probably a brain lock in front of the keyboard.
You will definitely have to go through more than these few iterations. Be prepared as substantial changes to stereotypes might not always be done with a synchronization. More on that later.
Having a custom diagram allows you to offer parts of the domain elements in different contexts. Imagine that salesmen and technicians need only those model elements they need. The salesman is not interested in screws needed for a motor and vice versa. So your primary domain analysis should also reflect the different stakeholders along with their relevant domain elements. The salesman wants to see just Cars and add basic information. So his diagram is basically a Commission view. The welding would need information about the design of the car with more technical input. This might be a Design view. The electrician would need a Cabling view. I will not go and create all of these diagram types. Only Design and Commission, but you will get the idea.
Create a «profile» package CDiagram with a simple class diagram inside. Add a «metaclass» Boundary (this creates an empty metaclass element; the contents is going to change completely). Name it Diagram_Class and add two attributes: alias of type string with initial value Design and diagramID of type string with initial value DED. The alias will appear in dialogues and the ID in the upper left corner of the diagram itself.
Add a stereotype Design and draw an Extend relation from that to the metaclass.
Set up a similar tuple for the Commission diagram. You need a new «metaclass» because the attributes are different. So now you should have two tuples.
A primitive MDG file
Now it is time for creating the first MDG. Still at this stage you will not get the complete picture, so just follow the steps.
Right click the CDiagrams package and choose Save as Profile. Change the filename from CProfile to CDiagram. When you save you will have two different .xml files in the Profiles folder.
Now we start to actually create the MDG file. Choose Alt+T followed by T (I do that so often that I use this simple shortcut rather than Tools/Generate MDG Technology File...
Click Next. Simple.
Create a new MTS file. And Next.
Place the file under the MDG folder above the Profile folder. Name it something like CTech. It will receive a .mts extension and saves the settings for the MDG. Next.
Technology: Custom Cars (or whatever represents the modeling technology). Filename: Navigate to program folder and further to Sparx Systems\EA\MDGTechnologies. Save it here as CTech.xml. EA will read this folder on startup and offer your MDG along with others. ID: Any arbitrary string will do. E.g. CTech in our sample. Version: 0.1 which is a good starting point. Remember to increment version and release number during subsequent changes. EA chooses the one with the highest number which is good during testing. So you can have a local MDG which is drawn before the common one for the rest users. Very handy. More on that later. Enter some blurb in the Notes. The rest can be left empty. Add more later when you are a more advanced MDG editor. And Next.
Just add Diagram Types to the selection list. And Next.
Navigate to our Profile folder. Move the CProfile.xml to the right side. And Next.
Again navigate to our Profile folder. Move the CDaigram.xml to the right side. And Next.
Finish. EA responds that it has created the MDG in EA's program folder. You might take a look inside. Or maybe later. Just ensure it is there.
Now you have to test it. Simply start a new instance of EA and navigate to Settings/MDG Technologies... which should show your new technology along with the existing ones. EA has already enabled it. Click on it and see version and notes you entered. Now open an arbitrary EAP file (e.g. the one where you are creating the MDG). Go to a reasonable place and try adding a diagram. You will find the CDiagrams on the left hand side and the Design and Commission types on the right hand side. Very nicely, but currently not too helpful. You have not yet related diagram elements to diagram types. The toolbox is missing. So we silently close the instance and continue with the next large step.
Note: the editor is once again confused. The diagram now does not show up with the tab containing the name and the ID. Neither at print nor at Save As Image... I'll edit this later when the confusion is gone or a kind reader tells me what is wrong here.
Finding out which diagram types are needed and which elements should appear is another crucial phase. You will likely need to redo large areas during MDG design. When design is already ongoing, which is likely, you need to think twice about the current model and its relation to the MDG.
Toolboxes appear in a separate window or - which I prefer since it makes the toolbars window superfluous - via the blank-context menu. You want to relate a toolbox with a diagram so you get only that set of elements which is meaningful in the current modeling context. And that's what we are going to do now.
Create a new «profile» Package and name it CToolbox. Inside create a new Class element ToolboxPage and stereotype it with «metaclass». We will use that metaclass for our toolboxes.
Now create a class diagram named Design. Drag the ToolboxPage as link onto it. Drag/draw from the quicklinker and select MetaModel/Extend. Name the new stereotype Design. Now we need to add the elements to appear in the toolbox for the Design diagrams. Let us simply choose two: Motor and Gear. For that add an attribute called CProfile::Motor with Initial Value "Motor". This will select the Motor stereotype from our profile and let it be displayed as "Motor" (the initial value). Repeat with CProfile::Gear/Gear and have a look in the help file what else can be placed here like default UML elements.
Now we need to save this Diagram (not the package!) as profile. You may have noticed that EA is doing relation-by-name. For what reason ever, but you need to be very careful with typing the correct names. I needed several iterations during creation of this tutorial in order get it correct due to typos. A look in the created MDG file help tracing that. So, right click the diagram and choose "Save as Profile...". The filename contains the "Last Saved File" from Windows. Nice? No! The name itself is at the end of the path and usually not visible. So you need extreme care to get the right file. That goes for saving of diagram and package profiles.
Okay. We will need more than one toolbox. Either you place them in our Profile folder and prefix them with e.g. TB_ or you place them in a separate folder Toolbox nearby the Profile folder which I usually do. Save it with the appropriate name.
Create a new class diagram Commission with a stereotype Commission. Just put Car and Chassis in as toolbox elements. (I wanted to add only Car but had troubles with that, so I added Chassis too which did work. The reason to put in just Car is that the Commission will just create new Cars from customers. They shall not be bothered with other details. My domain is anyway extremely artificial and you must not prove it wrong). Again save the Diagram and take care of the correct location.
We are not done yet. So far we have created two toolboxes, but the diagrams do not know that there is a relation. So let us add that.
Switch to the CDiagrams diagram. In the metaclass for Commission add a new attribute named toolbox with Iniitial Value "Commission". Same with Design/"Design". Finally save the CDiagram package (must I mention the right location?).
DONE! Almost. We only need to re-create the MDG and test it: Alt+T T
Open an existing... Choose the .mts you saved in the beginning. This will give you back all options from the last time. The drop down should hold it still. And Next.
You can leave the version at 0.1 for now. Only once you have a production version else you need to increase the release or version so EA takes your new test version. And Next.
Now you need to add Toolboxes once. And Next.
Navigate to where you saved your toolbox profiles and all of them to the right side. And Next.
Your profile is done and in the right place. We can now do the final step.
Simply restart EA. If you open the provided sample you already have two diagrams in the Sandbox view. Go to Design, click inside and watch Motor and Gear appear in the menu.
Now go to Commission and try the same. Car and Chassis appear but with empty guillemets as symbol for Car. That means EA did not find the stereotype in the profile. You will need to debug what is wrong and correct the MDG. Thanks to Walter Fahmer pointing out the quite simple solution: Go to the Toolbox definition for Commission and change CProfile::Car to CProfile::Car(UML::Class). The reason is that Car extends both Class and Package and thus is not unique. So we have to tell EA via the naming convention which of them we mean. I will not correct the model itself as I think it is a good exercise to go through.
I cannot say much more here. That would go too deep. There are two common issues you will likely encounter. One is the just mentioned empty guillemets. Another is that the toolbox is not connected to the diagram. You will likely have a typo in that case. The last I recall is a not appearing toolbox (so in no context at all). In that case you did something wrong when saving the profiles. The best is to save all profiles and regenerate the MDG.
Your profile is still local to your EA program folder. In a team work you will need to place the MDG on a network share (or maybe a version controlled folder). Use Settings/MDG/Advanced to locate the share. Make sure your MDG has an increased version/release number before you start testing. EA will then automatically prefer the new version over the old on the share. So you can test locally without problems. When you are copy your new version to the share. This is safe as EA only loads the MDG during startup. Any open instance will go on with the old version. New instances will use the new version.
I created this tutorial on the fly in parallel to modeling it with EA. I tried to note each step. Though it might be possible I forgot one or two or I made some other stupid mistakes. I appreciate any feedback to improve this document and hope you find it useful.