Presenting the new open source Enterprise Architect Shapescript Library

The new open source Enterprise Architect Shapescript Library in Github is an initiative to share shapescripts for Enterprise Architect within the user community.

Shapescripts in Enterprise Architect are used to define the presentation of elements on a diagram. They are mostly used when defining a UML profile in Enterprise Architect that extends UML or another modelling language with project specific elements and properties.

Shapescript examples

When developing UML profiles these shapescripts are stored in the _image attribute on the stereotype element, an they can be easily edited using the profile helper.

Shapescript editor

After a while however you’ll have a bunch of shapescripts scattered over different profiles, and projects, and it becomes hard to manage, or do any kind of version control. Finding a specific shapescript where you used a particular feature is next to impossible if you don’t remember exactly which stereotype this shapescript belonged to.

Exporting shapescripts

With the shapescript editor you can export each shapescript individually, but once you have more then a couple of shapescripts that quickly becomes a drag to save your shapescripts to files.

So I wrote a script called ExportAllShapeScripts that searches a repository for all stereotypes that have a shapescript, and exports all of these shapescripts in one go.

This script is part of the Enterprise-Architect-VBScript-Library. Read the article How to use the Enterprise Architect VBScript Library for instructions on downloading and using the Library in Enterprise Architect.

Running this script will save each shapescript as a textfile with extension .shapeScript, grouped in packages per profile.

Shapescripts saved

The code explained

The export script first uses an SQL query to find all shapescripts. Technically the shapescripts are stored in the default property of the attribute with the name _image. The script is stored as an xml tag Image in a zipped and base64 encoded format. A typical shapescript might look like this in the database:

<Image type="EAShapeScript 1.0" xmlns:dt="urn:schemas-microsoft-com:datatypes" dt:dt="bin.base64">
UEsDBBQAAAAIABpRIkdk2qflMQIAADIHAAAHABEAc3RyLmRhdFVUDQAHncrmVZ3K5lWdyuZV
jVXJTsMwFJxrkfiHCC5FqsRSaIsQhx44sohKcC5toUihqUjYxb8z8xw3jksLsmIn9sx43vOS
HFMMMccECZ749ogZNrGBL6sbSNn3gQwvKFg+DHmKLfZPcM+eZzIeqFGw76Tk3LPvneNj9JEb
Y8TxayoVHMmML+YLRyqWq8emmxP3ybcmuthDC222OyXS4fpEjjGgxh1rH0OTejP2PbF3whly
frewTw2puDbUcVp5kIM62437XHiPDeyy3FnkCXEuviG5D5YXjxrwvcAV6xluiR7za0qP7YUH
oa6X+E1zWzmOncdObsytcjuiSkpPqa3jZBFBgzFleDU/GcfloW1zhJqeJYxHLM8cK3VY1is5
xLJSGINW+5lo33dGDanMGYMyInYLB+hZLWddtqvUMpv9N8dNHJKnHdVZ4/hoMdtfmNhFPNdv
TmMdZSfGhNEUeAsy02eeRnYyuuZR7GPmp1U66lmODlmkKkwca91jj2zh1+XD6cQe6xjnIcbU
45gaI2Gb2c3xaSulvR/uWs9ZdX7210SjDCgPq336MxWjQqe53YXagQnPeWa3WXWWtCMLu+WE
GHE8tXiqc1tXXr4hHNKtkR7tgb8YB+U6Ca8V/R+rY7vdsTqm8B/Wsek7VpWvOi9ufXHf39bq
qd70KLvujteaPML9EbQnMvYldKF9MLQbODVGeDvXR76sTsr1uCz/RdLVf2Bgd391yyUlem44
7bq0RG7jgqfqnHfONr8qbN25f34AUEsBAhcLFAAAAAgAGlEiR2Tap+UxAgAAMgcAAAcACQAA
AAAAAAAAAACAAAAAAHN0ci5kYXRVVAUAB53K5lVQSwUGAAAAAAEAAQA+AAAAZwIAAAAA
</Image>

So the SQL selects all attributes owned by a element with stereotype «stereotype» with the name _image that have the tag <Image>  in their Default field.

'get all attributes with name _image that have shapescript in the default field and a parent with stereotype «stereotype»
dim sqlGetShapescriptAttributes
sqlGetShapescriptAttributes = "select a.ID from (t_attribute a " & _
							  " inner join t_object o on (o.Object_ID = a.Object_ID " & _
							  "						and o.Stereotype = 'stereotype')) " & _
							  " where a.Name = '_image' " & _
							  " and a.[Default] like '<Image type=""EAShapeScript" & getWC & "'"
dim shapeScriptAttributes
set shapeScriptAttributes = getAttributesByQuery(sqlGetShapescriptAttributes)

Then we loop the schapescript attributes, decode the shapescript and save it as an individual text file.

'loop the shape script attributes
for each shapeScriptAttribute in shapeScriptAttributes
	'get the stereotype
	dim stereotype as EA.Element
	set stereotype = Repository.GetElementByID(shapeScriptAttribute.ParentID)
	dim profile as EA.Package
	set profile = findProfilePackage(stereotype)
	'load the resultset in the xml document
	dim shapeScript
	shapeScript = decodeBase64zippedXML(shapeScriptAttribute.Default,"Image")
	if len(shapeScript) > 0 then
		dim scriptFile
		set scriptFile = New TextFile
		scriptfile.Contents = shapeScript
		'save the script
		scriptFile.FullPath = selectedFolder.FullPath & "\" & profile.Name & "\" & stereotype.Name & ".shapeScript"
		scriptFile.Save
		'debug info
		Session.Output "saving script: " & scriptFile.FullPath
	end if
next

The real difficulty int his script was to decode the shapescript, which is hidden in the method decodeBase64zippedXML  defined in the XML utility script. It first base64 decodes the contents of the tag, then saves it as a zip file, unzips the zip file, gets the text file in the zip file, and returns the contents of the text file. Then it deletes the temporary zip file and folder it was extracted to.

 Contributing

If you have shapescripts of your own that you wish to share you can send a github pull request, or an email to geert@bellekens.com.

Any bright ideas on how to document each of the shapescripts with an image of shape are welcome too.

 

Navigate from and to Composite Diagrams with EA Navigator

With EA Navigator version 2.4.12.0 you can now navigate from and to composite diagrams of an element.

Recently I’ve been working a lot with BPMN models. BPMN models make extensive use of the composite diagram mechanism in EA to drill-down on the processes and sub-processes.

In a classical UML model we usually place the composite diagram under the element, in which case finding the composite diagram, or finding the element(s) that have a diagram as composite diagram, is trivial. They are at the same location in the project browser.BPMN_Library_Model

In most BPMN models however there’s separation between model and library where the library contains the elements, and the model the diagrams. In such a setup it suddenly becomes much harder to find the composite diagram (find in all diagram, then double click the element) and almost impossible to find the element(s) that have a specific diagram as composite diagram.

 

In other words drilling down is relatively easy, but drilling up becomes nearly impossible.

Navigate_Composite_diagramThis problem is now solved by the EA Navigator.  From the Business Process I can now easily navigate to the composite diagram, but more importantly, I can navigate back up to any elements that have this diagram set as their composite diagram.

 

More Information

More information about the EA Navigator add-in for Enterprise Architect can be found here:

How to use the Enterprise Architect Add-in Framework

Since I started writing the EA Navigator and other tools the code has been open source and available on Github. The code is split up in a tool-specific part for the EA Navigator and some other tools, and a framework that can be used to build your own tool.

 Downloading

The code for the framework and the tools is published on GitHub, a version control repository “in the cloud”, which is free for public repositories. The easiest way to download the code is to install GitHub for Windows. That allows you use the Clone in Desktop button on Github.

Clone in Desktop

You can also download the ZIP, but then you’ll have to rename the packages to their original name. To be able to use the framework you’ll need two repositories

If you want to see how the EA Navigator uses the framework you’ll need

Make sure you put all the projects in the same directory as otherwise the references would be broken.

 Compiling

The code for the EA Add-in framework is written in C# using SharpDevelop. You can also open it with Visual Studio or another C# IDE, but then you’ll have to remove the wix projects from the solution.

You can open the complete code in either the Enterprise-Architect-Toolpack \Total Solution.sln or in case you only downloaded the framework then Enterprise-Architect-Add-in-Framework\Total Solution.sln but make sure to start you IDE as administrator.

Before compiling check the reference to Interop.EA. I’ve set it to point to C:\Program Files (x86)\Sparx Systems\EA\Interop.EA.dll but if you have EA installed in another directory you’ll need to replace the existing reference.

Once the references are OK you should be able to compile the solution without any issues.

 The pattern

UML Tooling Framework
To be able to understand the architecture of the framework you’ll have to understand the pattern behind it.

On the right you see a diagram of the general modelling tooling pattern. This pattern describes how to create tools that extend the features of a standard modelling tool in order to support the modelling method used.

This is the pattern I use whenever I develop an Enterprise Architect add-in for a client.

The LanguageObject is an interface that represent the object of the modelling language. In the case of UML each meta class of the meta model is represented as an interface. The LanguageObjects are completely independent of the modelling method or modelling tool used. Once finished this layer hardly ever changes.

The LanguageObject is then implemented by the ToolWrapper. There will be a ToolWrapper layer for each supported case tool. The ToolWrapper wraps the ToolObjects of the case tools API using the adapter pattern.

The MetaObject is only required when you are implementing a tool for a specific modelling method. These MetaObjects represent the meta classes of the modelling methods meta model. They wrap the LanguageObject using the adapter pattern. General tools that are not specific to any modeling method, such as the EA Navigator can skip this layer and use the LanguageObjects directly.

The Client is the actual tool. It only uses the MetaObjects to actually do its job.

In order for this pattern to actually work, it is really important that the dependencies and layers are respected.

 The architecture

To make an add-in you’ll always need three components similar to the three repositories on GitHub. You can see how these component map onto the pattern on the diagram.

Add-in Architecture

UML Tooling Framework

The UML Tooling framework implements the LanguageObjects of the pattern for the UML language. Each element of the UML meta model is represented as a interface defining all attributes and operations as defined in the UML Superstructure.UML Tooling Framework Code

Enterprise Architect Addin Framework

This component implements the ToolWrappers of the pattern. This component actually knows about the Enterprise Architect API. It hides all the ugliness of the API behind a clean set of UML interface implementations. There is a also a bunch of helper functions and stuff like that to make things a bit easier to work with.

EA Addin Framework Code

The Enterprise Architect Add-in Framework also contains an abstract add-in class EAAddinBase that you can inherit from to quickly create a new add-in.

The add-in component

The add-in component is the part that is specific to the add-in. It contains the actual logic and behavior that needs to be executed. This is also that part that you tell Enterprise Architect about. EA will then call the prescribed methods such as EA_GetMenuItem or EA_MenuClick on the AddinClass  at the appropriate moments.

When done correctly only the EA_ operations use API objects in their parameters. The first thing they should do is create the appropriate wrapper class and execute the required behavior on that wrapper. We cannot avoid the dependency to EA’s API because of the parameters in the EA_ methods, but it should be restricted to the parameters only. Make sure the only class that depends on Interop.EA.dll is the AddinClass, and leave this class as bear bones as possible. All functionality should go into functional classes who don’t depend on Interop.EA.dll.

You could even consider to split the MyAddin.dll into two parts, one for only the AddinClass, and one for the functional classes. This would definitely be the preferred architecture once you have multiple add-ins that somehow can re-use some of the functional classes.

 More resources

 Related articles

Source code on GitHub

Sparx Systems

EA Navigator 2.4 released

The main new feature of the version 2.4 of the EA Navigator is the Quicksearch. The Quicksearch feature is undoubtedly the fastest way to find anything in a (large) EA model. It is the type of feature which makes you wonder how you could live without it all that time before.

Developing the Quicksearch function was far from easy. I wanted something that resembles what Google does when you start typing, and I started things with a standard Windows Forms ComboBox. But after a while tinkering I finally had to give up and I started my own user control from scratch, combining a TextBox and a ListBox.

Furthermore the EA Navigator now no longer a strictly read-only add-in. With the feature to add an element to a diagram it now is able to make changes to a model for the first time.

Ad last but not least a lot of painfully boring work went into adding all the icons. The EA Navigator now uses more then 90 different icons in its tree.

What’s new in EA Navigator 2.4

Here are the changes for version 2.4.

Quicksearch

The Quicksearch feature is the new textbox on the top right of the EA Navigator window.

Quicksearch

Start typing in the Quicksearch box and you will get a list of all things in the model who’s name start with whatever you have typed.

Quicksearch_dropped

Hovering an item in the dropdown list will show you it’s fully qualified name in the tooltip.

Selecting an item will select it in the EA Navigator tree.

The Quicksearch also comes with a whole bunch of new options

Quicksearch_options

You can choose which types of items to search for, and with the Actions you can choose what to do when an item from the Quicksearch is selected.

Link to Element Feature navigation.

EA has the possibility to define links between features of an element such as Attributes or Operations using the Connect to Element Feature feature, which is very useful in a lot of situations.

Visually EA shows which feature is linked using brackets next to the connected Attribute or Operation.

LinkToElementFeature

The is all nice and dandy, but the downside of the story is that you can only see which features are linked by looking at the diagram.

Now with the EA Navigator you can simply navigate from one feature to the other

NavigateLinkToElementFeature

Add to Diagram

The add to diagram button will add the selected element in the EA Navigator tree to the currently opened diagram.

AddToDiagram

The element will be added to the top left corner of the diagram.

Navigate to GUID

A new button has been added that allows you to navigate to a GUID of an item in EA.

NavigateToGUID

Each item, elements, attributes, operations, diagrams, etc… has a unique id in the form of a GUID (example: {C06EF618-D57C-4f63-BF64-F5A5265694AE}).

Pressing the Navigate to GUID button will allow you to go to that element using it’s GUID. If there’s already a GUID in your windows clipboard then the EA Navigator will use that one. If not the EA navigator will show a dialog where you can past (or type) the GUID.

For elements shown in the project browser you can easily copy the GUID to your clipboard using the context menu Copy Reference|Copy Node GUID to Clipboard

CopyGUIDClipBoard

New Icons

The EA Navigator now shows correct icons for all possible element types in EA allowing you to easily see the difference between Use cases, Classes, Activities, etc..

The icons had become even more more important because of the Quicksearch function. When searching for an element it is especially useful to immediately which type it is.

Icons

Over 70 new icons has been added bringing the total number of icons used by the EA Navigator to 92.

Downloads

More Information

More information about the EA Navigator add-in for Enterprise Architect can be found here:

EA Navigator 2.3 released

The focus of version 2.3 of the EA Navigator is usability.

As a user myself I’m in a good position to evaluate the user-experience of the tool, and I felt the EA Navigator was coming short on that aspect. So I decided to do something about that.

One of the most important improvements, and also the most difficult one, is the switch to background processing.

With all the new features in the latest version I (and other users too) noticed that the EA Navigator was seriously slowing down EA itself. The problem was the fact that the EA Navigator needed some time to build the whole tree for the selected element, and EA was waiting for the add-in to finish before continuing.

On a small local .eap file that effect wasn’t really noticeable, but on large DBMS repositories it became a serious problem, so much even that some users even preferred to uninstall the EA Navigator because of it.

To solve this issue I started experimenting with multithreaded processing. The idea that, after a new element was selected, that the EA Navigator would start loading the element in a background thread. That allows us to return the control to EA almost immediately. The result is that the user doesn’t need to wait for the EA Navigator to finish before continuing to use EA.

What’s new in EA Navigator 2.3

Here are the changes for version 2.3.

Performance improved

The overall performance has been improved by doing the time consuming work of the EA Navigator in a background thread.
When several elements are being selected before the EA Navigator has finished loading them they will get queued. So now you might notice now and then that the EA Navigator is catching up after you finished clicking.

New Toolbar

The new toolbar allows fast access to functions such as Select in Project BrowserOpen Properties, or To FQN.
There’s also a button for the new Settings dialog, and the About dialog

New Settings

You can now configure certain options in the EA Navigator. The options are stored on a per user basis in a config file in the user profile.

The available options are:

  • Doubleclick action:
    Decide what the EA navigator should do when you double-click on a node.
  • Show Toolbar:
    Show or hide the toolbar.
  • Show Context Menus:
    Show or Hide the Navigate context menu when right clicking on an element.
  • Track Selected Element:
    Controls whether or not the EA Navigator load the selected element in the navigator window.

Open in Navigator

If you have disabled tracking of the selected element in the settings then you have a new context menu option load the element in the navigator window.

Select relevant element when opening diagram

When opening a diagram via the Navigator window the relevant element will be selected. So if you open a sequence diagram from under the Operation/Diagrams section the message calling that operation will be selected

Show stereotypes in names of elements

Elements now show their stereotypes in the navigator window.
Up to 20 characters of stereotype information will be show. Multiple stereotypes are separated by a comma, and if there’s more than can be displayed there will be two dots at the end to indicate that.

Downloads

More Information

More information about the EA Navigator add-in for Enterprise Architect can be found here:

EA Navigator 2.2 released

Since the release of version 2.1 the EA Navigator has been quite stable. Not much need for major improvements or bugfixes.

So version 2.2 has been about little changes and updates.

The most remarkable new feature is the new context menu with the ability to open the properties dialog of an element. Not remarkable because of the feature itself, but because of the loops and holes I had to jump through to get that part working. Opening the properties dialog is not really a supported API function of EA, so I had to resort to using an undocumented CustomCommand function to hack my way into it. Unfortunately I never got it working for messages.

What’s new in EA Navigator 2.2

Open Properties via new context menu

Each element in the navigator now has a context menu when you right-click on it.

Open Properties  opens the properties dialog of the element.

Select in Project Browser  selects the element in the project browser, just like a double-click would.

Fully Qualified name in the tooltip

Hovering above an element will show the fully qualified name of that element in the tooltip.

This helps to quickly see where that element is coming from (and if you need that one, or another one).

Communication Diagrams

Next to sequence diagrams you can also have messages on Communication Diagram (the old Collaboration Diagrams). Version 2.2 now also supports Communication Diagrams the same way it supports Sequence Diagrams.

This feature was requested by Chris on Github.

Datatypes and Enumerations

Datatypes and Enumerations are now also supported the same way as classes.

Downloads

More Information

More information about the EA Navigator add-in for Enterprise Architect can be found here:

EA Navigator is now an official Sparx Systems 3rd party add-in

I’m proud to announce that the EA Navigator has made the “official” Sparx Systems 3rd party add-in list.

Sparx Systems doesn’t just publish any add-in for Enterprise Architect. Each add-in on the list has been demonstrated to the the people of Sparx, and only if they approve it it will be added to the list.

So a couple of week ago I had an appointment to do a web conference with Sparx to do a little demo of my add-in.

Now they have approved it and the part about the EA Navigator has been published, and it even has its own url for direct navigation: http://www.sparxsystems.com/products/3rdparty.html#EAnavigator.

This is how it looks like:

EA Navigator 2.1 released

With the current release 2.1 the EA Navigator has now matured into a real product that will make the life of any Enterprise Architect user a lot easier.
I can know, as it’s primary user I use it constantly during my daily modelling tasks, and I can assure you that it has already saved me heaps of time.

And because any real product should have a logo, so I proudly present to you: The EA navigator logo.

After the complete re-factoring  of version 2.0 version 2.1 has been more about polishing and refining. I’v been using my own user feedback to enhance the existing features, and add the features I was missing.

One of the things I’ve been focusing on  is the bi-directionality of all navigate features. So if I can navigate from an operation to the sequence diagrams that use it, then I also want to be able to navigate from that sequence diagram back to the operations it shows.

What’s new in EA Navigator 2.1

New and improved icons

Most of the icons used in the navigator window have gotten an update. The folder icons now already show what kind of elements can be found here.

Tagged values

In Enterprise Architect you can define “RefGUID” style tagged values is you want to link an element to another element (see EA Manual for more information).
This is a flexible way to add your own customized relations to the model.

All tagged values of a class are being examined. If their value is a reference to another element they will show up in the navigator:

Referencing Tagged Values

The referencing tagged values allow for navigation in the other direction. It will show all RefGUID style tagged values that reference the selected element.
This feature is available for all types of elements.

Owner

The owner feature simply allows to navigate further to the owner of the element. This feature is available for all types of elements.

The owner feature is a bit special as it doesn’t have a folder that you have to open, but it shows directly under the selected element.

Sequence diagram operations

Starting from a sequence diagram you can now quickly navigate to all operations called on the diagram. This sequence diagram

shows up like this in the EA Navigator window

Other changes

  • Attribute Type
    The attribute type’s behavior has been changed to show without a containing folder, just like the owner feature.
  • Relationship select
    Relationships can now also be selected. Selecting a Relationship will select it’s source, except for sequence diagram messages, they open their sequence diagram when double-clicked.
  • Number of items in window
    The number of items retained in the navigator window has been increased to 50.
  • Implementation to operation
    From a Behavior (Interaction, Statemachine or Activity) or from a diagram contained by such an element can be navigated to the operation it is implementing.
  • Add/Remove programs Icon 
    The EA Navigator now has its own icon that shows up in the add/remove programs, to easily identify the add-in among all other installed programs.

Downloads

More Information

More information about the EA Navigator add-in for Enterprise Architect can be found here:

EA Navigator 2.0 released

Attention! A more recent version of the EA Navigator is currently available.
See EA Navigator Downloads

I’ve just released the first “major” upgrade to the EA Navigator add in.

In this release no additional features have been added, the only thing that was changed is that the EA Navigator will now use a docked window in EA to navigate between the different elements.

Now instead of having to right-click and choose an option from the Extensions|Navigate context menu, the Navigator window will immediately show the options for the currently selected element.

In order to show this window select the option Extensions|Add-In Windows

This will show the EA Navigator control in a window you can dock anywhere in the application.

Now all you need to do to select an item in the project browser is double-click it.

The EA Navigator window retains the last 20 elements, so you can easily find the element you were working on just before.

Downloads

More Information

More information about the EA Navigator add-in for Enterprise Architect can be found here:

Select a model element from its node path (FQN) with EA Navigator 1.3

Attention! A more recent version of the EA Navigator is currently available.
See EA Navigator Downloads

Enterprise Architect has the nice feature that you can copy the node path of almost everything in the model to your clipboard.

For this example that would copy the string Model.Package2.Class1.testAttribute to the clipboard.
I use this feature a lot in say analysis documents, emails to other EA users etc… and for a model as small is this, the other user can easily identify the element I’m referring too.

For larger models however, finding the element based on the fully qualifed name (FQN) can prove to be quite the task, and unfortunately EA doesn’t provide a function to find the damn thing based on its FQN.

So I decided to add that feature to the my EA Navigator add in.

All you need to do is copy the Node Path into your clipboard and choose the option “To FQN”

The add in will then select the item in the project browser.

Downloads

More Information

More information about the EA Navigator add-in for Enterprise Architect can be found here: