amtech/enterprise-architect

scripts and other code snippets to extend Sparxs Enterprise Architect

README

Table of Contents

• Enterprise Architect Sripting
  • Create a Sequence Diagram in EA using PlantUML
  • Create a C4 Container Diagram in EA using PlantUML
  • Create a PlantUML Script from a Sequence or C4 Diagram In Enterprise Architecht
  • Color Picker
  • Backlog Items
  • Installation Instructions

Enterprise Architect Sripting

PlantUML is awesome; it is accessible, easy to use and you produce nice looking diagrams with minimal effort in a short period of time. The PlantUML script can be published and made available for collaboration.

The problem however it that the PlantUML script used to generate the diagrams are discrete declarations of behaviour. Validation and alignment against the Domain and or Enterprise landscape would typically be manual and the likely outcome would be model divergence.

The cost savings from the speedy delivery of fit for purpose models is long forgotten when the time comes to make changes.

I do believe there is a middle ground where Enterprise and Delivery teams operating at differing speeds can effectively work together. The solution centres around the ability to exchange models between the modelling platform and the script based diagraming tools.

Enterprise Architect does offer a number of methods for model exchange. The simplest being CSV imports, for high order elements, through to XMI import/export for full element, association and diagrams objects.

PlantUML does support XMI export, however at this point it only applies to Class diagrams.

So one solution to close this gap, I have cobbled together a VBScript to run within Enterprise Architect to allow a modeller to Generate a Sequence Diagram using a PlantUML script.

Create a Sequence Diagram in EA using PlantUML

The following screen shot provide an example of what functionality is offered by the scripts.

• participant types of actor, control, boundary, entity and database (will automatically create if not specifically declared in the script)

• boxing timeline elements

• color coding using either #RGB or HTML standard colors

• synchronous, asynchronous, return and message to self flows

• message grouping (alt, loop, critical etc)

• activate and deactivate of timelines

• return value and parameters

• autonum

• header and footer

• sterotypes

• coloring of the flows

• notes

• dividers

The following steps outline the process of creating the sequence diagram within Enterprise Architect:

1. create a new sequence diagram

2. add a note element and paste the desired plantUML script into it

3. right click the Note element and select Run PlantUML Script the following diagram is created

Sample Generated Sequence Diagram

Note	EA’s does have some restrictions on the way the flows can be laid out using the GUI.. and this is especially evident when using nested InteractionFragments. So please check the produced diagram to ensure correct flow placement.

Create a C4 Container Diagram in EA using PlantUML

The C4 Model is a lean graphical notation technique for modelling the architecture of software systems.

Sparxsystem provides a free C4 MDG download which defined the C4 shape toolbox and associated diagrams.

Sample C4 Diagram using the LieberLieber C4 MDG

But wait.. What if you already had your context or container view in plantuml script form. There is no way that you will want to maintain 2 versions of the same document.

Say I had the following script.. how long would it take to manually produce the diagram in EA.

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
'!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Dynamic.puml

' uncomment the following line and comment the first to use locally
' !include C4_Container.puml

'LAYOUT_TOP_DOWN()
'LAYOUT_AS_SKETCH()
'LAYOUT_WITH_LEGEND()

title C4 Container View via script

AddElementTag("Service", $shape=EightSidedShape(), $bgColor='Lightblue',$legendText='service (eight sided)')

AddRelTag(Alert, $textColor="red", $lineColor="red", $lineStyle = DashedLine(), $legendText="console triggered")
AddRelTag(Synchronous, $textColor="black", $lineColor="dimgrey",$legendText="Synchronous")
AddRelTag(Asynchronous,$textColor="black", $lineColor="dimgrey", $lineStyle = DashedLine(), $legendText="Asynchronous")

Container_Boundary(boundary, boundary){
Container(Container1, "Container one", "Application")
Container_Boundary(boundary2, boundary2){
Container(Container3, "Container three","service", $tags='Service', "description")
ContainerDb_Ext(Container4, "Container four","storage", "desc")
Container(Container5, "Container five","Application", "container 5 description")
Container(Container6, "Container six","Application", "container 6 description")
}
}
ContainerDb_Ext(Container2, "Container two","storage", "desc")

Rel(Container1,Container3,"blah","Synchronous", $tags=Synchronous)
Rel(Container1,Container5,"blah5","Synchronous", $tags=Synchronous)
Rel(Container1,Container6,"blah6","Synchronous", $tags=Synchronous)
Rel_R(Container3,Container4,"blah2","Alert", $tags=Alert)
Rel(Container3,Container2,"","Asynchronous", $tags=Asynchronous)
SHOW_LEGEND()
@enduml

The following steps outline the process of creating the C4 diagram within Enterprise Architect:

1. create a new C4 diagram

2. add a note element and paste the desired plantUML script into it

3. right click the Note element and select Run PlantUML Script the following diagram is created

Sample C4 Container Diagram via the Run PlantUML Script

Some limitations/half baked functionality..

• no dynamic sterotype creating

• sterotyped person & connectors do not pickup the UML styling

• adding url links to objects or connectors

Create a PlantUML Script from a Sequence or C4 Diagram In Enterprise Architecht

Model Management however is not just about being able to import sequence diagrams. The use case may exist in your organisation where diagrams require to be validated against some Enterprise standards, checking for duplicates within the model, for duplication against an Application Portfolio, naming standards, organisational context; all metadata which extends beyond the basic sequence diagram which has been described.

Hence these diagrams and/or the underlying modelling elements may well be updated within Modelling environment and there is a need to refresh one or more PlantUML scripts.

The following steps outline the process of creating PlantUML script from a sequence diagram within EA:

1. open up an existing sequence diagram

2. add a note element to the sequence diagram

3. right click the Note element and select Create PlantUML script

4. the script will parse the diagram objects and links with the results loaded into the note object.

The above steps also apply to C4 Diagrams.

Sample Generated Generation of PlantUML Script

]

This script preceded the import script and was the basis of discovering where various information about the diagram and underlying modelling objects are stored within EA.

Color Picker

Within PlantUML you are able to assign colors to an object or connector by using the the following values:

• Hex RGB value eg #AABBCC

• Standard HTML Colors eg #LightBlue

• Special PlantUML names i.e. Application, Implementation, Motivation, Physical & Technology

:PlantUML Color Pallete

Managing colors in EA is quite a complex topic. Each element type has a default color and it is also possible to apply default colors based on stereotype (via UML type setting or MDG UML Profile) or via shape scripts and driven possibly by a tagged value.

A modeller can override a default cold via the GUI using color palette.

Behind the scenes, Enterprise Architect will store the value of -1 if a default color is to be applied. If the default has been updated by the modeller, then the value is a decimal representation of the Blue Green Red components of the color is stored.

Hence the need to have a sub routine to allow a PlantUML color code to be converted into the decimal equivalent to be applied to an EA modelling element during the Create Sequence Diagram script.

Likewise when Generating the PlantUML script there is a requirement to take the decimal version and output the #colorname or #rrggbb value.

The common functions available are:

• ColorHexByName (colorName) where a #colorname is supplied as input and the hex RGB value is returned

• ColorNameByHex (colorHex) where a hex RGB is supplied and the color name, if exists is returned

Backlog Items

The following features will be added overtime.

• support other diagram types e.g. use case, class diagrams

• color coding activations

• Notes overlay of one or more timelines

• publish directly to confluence pages

• autonumber paramaters

Installation Instructions

All scripts are included in the MyModel.EAP within this github repo.

Which were created using the following rather manual method:

Activate the the script manager window with EA

1. Create a new Diagram Scripting Group and load it up with:

   • Run PlantUML Script

   • Create PlantUML Script

2. Creates a new Normal Scripting Group and name it PlantUML and load it up with the various diagram specific scripts as per the scripting manager screen shot

3. Create another normal VBScript group, this one is to be called Common and load it up with the following:

   • color-picker

   • Print-Array

   • Sort-Array

EA Script Maanger

Note	This Scripting facility is available in the Corporate, Unified and Ultimate editions. If you intend to use the Scripting facility under Crossover/WINE, you must also install Internet Explorer version 6.0 or above. Script names are case sensitive.