Subscribe to an RSS feed of changes to this page.

This course page is a little different to the others. Nearly all of our Enterprise Architect (EA) training is conducted in-house for clients. At the end of all our in-house courses, we burn photos of the whiteboards and any other relevant material onto a CD and hand it to the client. This means there is no need to post it here. So instead, this page is a collection of “tips, trick and traps” for using EA.

Many people seem to forget that the “L” in UML stands for language. Just like any other language, the UML has a well-defined syntax and grammar. Each of the UML’s elements has a precise meaning that is described in the UML metamodel. Now the UML metamodel makes great reading for insomniacs but for the rest of us, Zicomi Systems has taken the hard work out of understanding how to use UML correctly with Mentor, their UML visual dictionary.

We think that Zicomi Mentor is a “must have” companion to EA and we occasionally find ourselves referring to mentor during a course to help us answer some of the trickier questions we get asked. Mentor runs as an EA plugin, which means that the precise definition of any UML element included in your model is only a right-click away.

There are several options for producing documentation using EA.

These are fine for simple reports but there are some types of report that are difficult (impossible?) to produce. For example, an alphabetic list of elements showing the package that contains them.

RTF reports can be combined with MS Word (Open Office?) style sheets and macros to achieve the desired formatting.

EA’s repository is an SQL database, which means that any SQL reporting tool can be used to produce documentation. Crystal Reports is a good candidate. EA’s repository can also be opened as an MS Access database but requires extreme care. Changing any data will nicely corrupt your repository.

One of the major problems with SQL reporting tools is the difficulty of recursively iterating through packages in the repository. This is an inherent SQL problem not a problem with EA.

The entire contents of EA’s repository can be accessed via the automation interface. Any programming language that is capable of generating ActiveX COM clients can be used to access the repository via the automation interface.

We use the open source scripting language PHP. One of its advantages is that is designed from the ground up to generate HTML. We create a very plain .html file from the PHP script and then load it into MS Word. The document is then saved in MS Word’s native .doc format and a style sheet is attached. There is always a minimal amount of manual editing required to deal with page breaks and orphaned lines etc.

The main advantage of this method is that you have total control over the contents and structure of your documentation.

We have seen clients do much the same thing using MS Visual Basic. One client had achieved a very nice integration with MS Word. EA documentation could be inserted into a document simply by selecting an MS Word menu option.

This idea was suggested to us by Geoffrey Sparks himself. It is designed to overcome the problems in recursively iterating through packages in the repository using SQL. The solution is simple. Write a short automation interface script that dumps the package hierarchy to a simple table. The table should include element IDs and a generated sequence number that identifies the element’s position in the package hierarchy.

This table is then joined to other tables in the repository to create reports in package hierarchy order.

We wrote a very simple PHP script to do this and have used the approach on a number of projects.

• Export the repository using EA’s .csv export feature. Reports could then be create using tools such as MS Access or Excel. However, the .csv export only exports a limited number of element features.

• Export the repository using EA’s XMI export feature. Reports could then be created by parsing the exported XML file. In theory, this could be achieved using XSLT. However this approach would only be for the very bold with “mucho” time on their hands.

One of the most common misunderstandings we come across during our courses concerns the relationship between EA’s diagrams and the repository. We feel that sometimes this misunderstanding is made worse by the “document-centric” view that is promoted by some of EA’s menu options and toolbar buttons:

New Project

Open Project

Save Project As…

Our view is that EA is not really a “document-centric” tool. All of the UML elements that you add to a diagram are actually stored in an SQL database known as a “repository”. For anything other than ad-hoc or personal use, it is usually best to configure a single, shared repository.

The diagram below is a photograph of a whiteboard diagram we find ourselves drawing quite often. On the left of the diagram is the shared repository that stores details of all the UML elements including their position on a diagram. It is common for a shared repository such as this to be deployed on a server.

On the right of the diagram are a couple of users running EA on their workstations. As the users reposition UML elements on their diagrams it would be theoretically possible to continuously update the database with each element’s current position. However, even with a modest number of users the network traffic and load on the database would become unacceptable.

So the strategy adopted by EA is to “cache” the diagram locally on the workstation and only update the database with the position of all the diagram elements when the user “saves” the diagram.

There are two consequences of this strategy that frequently leads to misunderstandings:

• “Deleting” an element from a diagram in fact only “removes” the element from the diagram leaving its details intact in the repository.
• “Undo” only undoes changes to the cached diagram. It does not undo any updates to the repository such as adding a new element.

Naturally deleting an element from the repository also means that it is removed from all diagrams on which it appears. Database updates cannot be undone, so once an element is deleted from the repository its gone for good.

All of the above applies equally well when the repository is stored in a MS Jet database deployed on the same workstation running EA – its just less obvious. We think it helps to mentally rename the toolbar buttons to the following:

Create new repository

Open/connect to an existing repository

Syncronise the repository with a locally cached diagram

When reading thse code examples it is probably best to regard them as “proof of concept” examples. Also remember that our strengths lie in using EA for UML modelling - not writing PHP code

$repository = new COM("EA.Repository") or die("Can't open EA");
$repository->OpenFile($proj_name);
 
$project = $repository->GetProjectInterface();

Function DumpRepository($repository, $pack_level , 
                        $pack_sequence) {
 
    # Allow for repositories that contain no models
    if ($repository->Models->Count>0) {
        for ($m=0; $m<$repository->Models->Count; $m++){
            $model=$repository->Models->GetAt($m);
            $models[$model->TreePos]=$model;
            }
 
        ksort($models);
 
        foreach ($models as $model) {
            $pack_sequence=DumpPackages($model, $pack_level, 
                                        $pack_sequence);
            }
        }
    return;
}
 
Function DumpPackages($this_package, $pack_level, 
                      $pack_sequence) {
 
    $pack_level=$pack_level+1;
    $pack_sequence=$pack_sequence+1;
    
    echo("$pack_level, $pack_sequence, $this_package->PackageID, 
         \"$this_package->Name\" \n");
 
 
    # Allow for packages that contain no nested packages
    if ($this_package->Packages->Count>0) {
        for ($p=0; $p<$this_package->Packages->Count; $p++) {
            $package=$this_package->Packages->GetAt($p);
            if ($package->TreePos==0) {
                $packages[$package->Name]=$package;
                }
            else {
                $packages[$package->TreePos]=$package;
                }
            }
 
        ksort($packages);
        
        foreach($packages as $package) {
            $pack_sequence=DumpPackages($package, $pack_level, 
                                        $pack_sequence);
            }
        }
 
    return $pack_sequence;
}

Function DumpElements($package) {
 
    for ($e=0; $e<$package->Elements->Count; $e++) {
        $element=$package->Elements->GetAt($e);
        if ($element->TreePos==0) {
            $types[$element->Type][$element->Name]=$element;
            }
        else {
            $types[$element->Type][$element->TreePos]=$element;
            }
        }
    ksort($types);
        
    foreach($types as $elements) {
        ksort($elements);
        foreach ($elements as $element) {
            $connectors=$element->Connectors->Count;
            echo($fp, "<p><b>$element->Name ($element->Type)
                       </b></p>");
            if ($element->Attributes->Count>0) {
                DumpAttributes($element);
                }
            if ($element->Connectors->Count>0) {
                DumpConnectors($element);
                }
            }
        }
 
    return;
}