Deploying a model repository often eventually leads to user requests for additional features to address specific needs, mostly to save time when using Enterprise Architect (EA). Whilst EA is a very rich and powerful tool, it provides an API to extend further its capabilities e.g. by querying the model or updating/creating model content.
The API can be exploited through the following means:
- EA scripts: stored within a shared repository (EA project), scripts can be executed by users granted with the run scripts permission. This approach is useful to avoid installing and maintaining applications (EA add-ins) on each client. EA can be used as the IDE to implement, test and run scripts. Supported languages include VBScript, JScript, and JavaScript.
- EA add-ins: extension applications must be installed on each client to be available within Enterprise Architect. They can be implemented with most programming languages such as C#, Java, C++, etc. In comparison with scripts, they support enhanced user interfaces and EA broadcast events (to trigger a behaviour e.g. when an element or connector is created).
- eaUtils is an example of a free EA add-in.
- Third-party applications or scripts: EA API can be accessed through third party solutions such as a PowerShell script or a C# command line tool. This is convenient to run scheduled tasks for regular updates or extracts, e.g. update the application portfolio within an ArchiMate Enterprise Architect repository from a CMDB Excel weekly extract.
- Model-based add-ins: defined in the repository, there is no installation needed on clients. Based on JavaScript, the main advantage of using model-based add-ins is related with the EA broadcast events support.
- This is the topic covered in this article.
The table below provides a non-exhaustive comparison of the main differences between the above options:
Introduction
This article provides an example of a model-based add-in, based on a real-life experience, to share its advantages and constraints in terms of implementation and usage.
Initial context: a team of architects working on a db shared EA repository (Enterprise Architecture with a custom ArchiMate - MDG) asked if they could get a warning when creating a relation to avoid duplicates (control on matching relations with the same source and target elements, type, and stereotype). Having multiple relations of the same type between two elements (e.g. flows between application components) being a valid scenario, a user needed to be prompted to either cancel or confirm the new relation. The most common scenario involves preventing creating a duplicate relation on a diagram where the relevant relation has been hidden. In this case the add-in needed to cancel the relation and provide the option to show the hidden relation. To both support EA broadcast events and avoid installation on each client, the EA Model-Based add-in has been identified as a suitable option.
For the purpose of illustrating the use of a model-based add-in, I've kept it simple:
- All types of associated elements and connectors are picked up by the add-in.
- In a more enhanced version, it would be useful to let users configure a list of rules with the connector, source element, and target element type/stereotype, and have the option to include the multiplicities and association ends.
- If the user decides to cancel the connector, he/she can choose to show the hidden connectors on the diagram.
Technical environment: Enterprise Architect 15.2 build 1560.
Implementation
Setting up the model-based add-in class
The first step involves creating a package to manage the model-based add-in. If the EA security is enabled, a lock can be create restrict its access to the administrators.
Once the target package is selected, open the wizard from the Browser (new model from pattern), select Management > Model Add-ins > Broadcast Types, and click on Create Patterns.
This step is required to generate all supported EA broadcast events, so they are available for the model-based add-in.
To create the model-based add-in, create a UML class and change its stereotype to Model Add-Ins::JavascriptAddin.
The following receptions must be added to the class: EA_Connect, EA_GetMenuItems, EA_MenuClick:
- Open the Features view > Receptions.
- Add a new reception and select a signal element within the Broadcast Types > Add-in Events, e.g. EA_Connect.
- Repeat with the other operations to get the following result.
The EA_OnPreNewConnector broadcast event needs to be added to trigger a control any new connector that is about to be created on a diagram. If the add-in returns true, the connector is created. If it returns false, the connector it is deleted / cancelled.
Add a new reception in the class and select Broadcast Events > Pre New-Object Events > EA_OnPreNewConnector.
Functions can be created in the operations. ProcessHiddenConnectors has been created with 2 parameters: connectorsList and diagramID. It will be called from EA_OnPreNewConnector to check if the list of matching connectors contains hidden connectors. In this case it will prompt the user to make them visible. Operations can be called as illustrated here:
this.ProcessHiddenConnectors(connectorList, Info.Get("DiagramID").Value);
Global variables can be defined as class attributes. AddinName attribute has been created with the initial value "ModelHelper". This variable can be accessed with this.AddinName.
Adding JavaScript libraries
To avoid defining everything in the model-based add-in class and define reusable functions, classes can be created in the model and associated with a dependency link:
- xmlHelper.GetNodesfromQueryResult(queryres, colname)
- Inputs: result from Repository.SQLQuery and the name of the column in the query e.g. ea_guid
- Output: XML Node List with the query results
- JSdialog.MsgBox(prompt, title, style)
- Purpose: Session.Prompt available in EA API didn't work properly with the add-in. It was needed to prompt the user to keep or delete the connector, to show hidden connectors. That's why a simple function with several styles available has been implemented (see inputs).
- Inputs:
- prompt: text to display the user
- title: popup window title e.g. ModelHelper (this.AddinName)
- style: one of the following values
- 0 -> OK button
- 1 -> OK/Cancel buttons
- 3 -> Yes/No/Cancel buttons
- 4 -> Yes/No buttons
- Returns the value matching the button clicked by the user
- 1 -> OK
- 2 -> Cancel
- 6 -> Yes
- 7 -> No
- Code:
style += 4096; // active window
var WSH = new COMObject("WScript.Shell");
return WSH.Popup(prompt, 0, title, style);
Examples of code to call this function:
var dialogHelper = new JSdialog();
--> instantiate JSDialog class.
dialogHelper.MsgBox("This Model Addin displays a popup when creating a connector between 2 elements when at least one matching connector (type, stereotype) already exists.\n\nThe user is prompted to confirm the new connector or cancel it. If the connector is cancelled, the user can choose to show any hidden connector(s) on the diagram.\n\nAuthor: Guillaume FINANCE (guillaume...umlchannel.com)", this.AddinName, 0);
--> displays a popup window with a message and a single button, OK (style = 0).
if (dialogHelper.MsgBox(message + " found with the same type/stereotype.\nClick YES to confirm creating the new connector,\nNO to cancel/delete this connector.", this.AddinName, 4) == 6);
--> displays a popup window with a 2 buttons, Yes and No (style = 4), and test if the user answers Yes (6).
Completing the Add-in code
To edit the JavaScript code in the model-based add-in or library class, select the class and use the Develop menu > Behavior > Edit Internal Code (alternative: right click on the class > Features > Edit Internal Code).
The tree structure provides access to each operation and reception. Below is an example of the code to create the menu in EA (About), using the global variable AddinName.
Below is the resulting menu:
Demonstration
Manage Add-Ins shows the installed EA add-ins as well as the model-based add-in. Identified as Optional, any user can enable or disable this add-in:
To test the ModelHelper add-in, the following ArchiMate diagram has been created:
Creating an additional composition link led to the following popup:
Clicking on Yes, the additional composition link has been created.
Both connectors have been hidden:
Attempting to create a new composition link led to the following:
Choosing No to cancel creating this connector led to the following prompt:
Result (choice: Yes, show the hidden connectors).
Summary
Addressed issue: workaround for a Session.Prompt freeze issue when called from the model-based add-in by implementing a generic JavaScript function to display a message box, with multiple buttons style choices (Ok, Yes/No, etc.).
Cons
- Since the source code is maintained through the class operations, there is no overall view of the code. This is not ideal from a development perspective.
- In the code, navigating from a function call to its definition is not currently available, contrary to the scripting implementation where the "Search in Scripts" on a selected text is useful.
- Any change in the code requires to reload the EA project before testing it.
- Debugging with breakpoints does not seem to be available.
Pros
- Supports EA broadcast events.
- Note: users must be informed about background tasks that are automatically triggered based on the defined rules. It is important for them to avoid making mistakes or raising bugs for unexpected behaviour.
- Each user can choose to enable or disable the add-in.
- In a shared EA project, a model-based add-in can be associated with a group of users so its access can be restricted.
- Like EA scripts, the code is maintained in the repository and automatically upddated for all users (enhancements, bug fixes...).
- JavaScript functions can be managed via separate classes (libraries).
- Once it works, a model-based add-in is very useful!