Enterprise Architect supports most modelling languages and notations i.e. UML, BPMN, SysML, and ArchiMate. Whether EA is used to build models for a software application, identify business processes, define the system with the MBSE approach, or carry the IT landscape via the business, application and technical layers, customizing the notation with stereotypes and adding tailored features is almost a recurring request. Automated tasks and additional features can be built using EA API via scripts, add-ins, external tools, etc.
Based on a large number of scripts implemented for clients involved in software, data, and systems engineering, Guillaume will share his experience on this growing activity over the past years:
- Overview of the covered topics (custom Excel import/export, model QA, save users' time in avoiding repetive or time consuming tasks, manage EA users & groups via Excel, run a reverse on unsupported languages such as Fortran...)
- Demonstration of a selection of scripts.
- The need to organize and name scripts.
- Debug scripts.
- Compatibility with different DBMS and the Cloud connexion
- Hints and custom scripts to publish scripts
- Addressing the lack of sub menus with more than 20 scripts
- Automatically trigger scripts with Geert's free ea-matic add-in
EA User Group London 2018 - Extending EA with custom scripts to cater for specific needs and user requests using Sparx API
1. EXTENDING EA WITH CUSTOM SCRIPTS
TO CATER FOR SPECIFIC NEEDS
AND USER REQUESTS
LONDON EAUG 2018
Blog: www.umlchannel.com
Add-in: www.eautils.com
Twitter: @umlchannel
Guillaume FINANCE
5. Custom EA User Interface (13.5) New features using EA API…
INTRODUCTION
EA Scripts
5
EA tool customization
6. Why do we need scripts?
Replace repetitive tasks performed by users
INTRODUCTION
Custom Excel publication
Update details in Excel
Work with Excel
Custom tools and solutions integration
Model QA
And much more!
6
7. Internal use
Why do we need scripts?
INTRODUCTION
7
EA users
(analysts, architects…)
Stakeholders, client…
Method & processes,
model consistency…
Third party tools
Outside people & applications
8. Alternatives in using EA API
INTRODUCTION
EA add-ins
3rd party tools,
ext. scripts
Excel macros
EA Scripts
Installation User Interface Language(s)
None - import file in
the project, available
for all users
VBScript, JavaScript,
JScript
Message or Input box,
system output…
8
EA DATA
9. Alternatives in using EA API
INTRODUCTION
EA add-ins
3rd party tools,
ext. scripts
Excel macros
EA Scripts
Installation User Interface Language(s)
None - import file in
the project, available
for all users
VBScript, JavaScript,
JScript
Enhanced windows,
system output…
Installation on all
clients, available to
use with any project
C#, VB.Net, Java,
C++…
Message or Input box,
system output…
9
EA DATA
10. Alternatives in using EA API
INTRODUCTION
EA add-ins
3rd party tools,
ext. scripts
Excel macros
EA Scripts
Installation User Interface Language(s)
None - import file in
the project, available
for all users
VBScript, JavaScript,
JScript
Enhanced windows,
system output…
Installation on all
clients, available to
use with any project
C#, VB.Net, Java,
C++…
Optional Linked with the
chosen language
C#, VB.Net, Java, C++,
Python, Perl…
Message or Input box,
system output…
10
EA DATA
11. Alternatives in using EA API
INTRODUCTION
EA add-ins
3rd party tools,
ext. scripts
Excel macros
EA Scripts
Installation User Interface Language(s)
None - import file in
the project, available
for all users
VBScript, JavaScript,
JScript
Enhanced windows,
system output…
Installation on all
clients, available to
use with any project
C#, VB.Net, Java,
C++…
Optional Linked with the
chosen language
C#, VB.Net, Java, C++,
Python, Perl…
n/a (Excel required) Excel Excel VBA
Message or Input box,
system output…
11
EA DATA
12. Alternatives in using EA API
INTRODUCTION
EA add-ins
3rd party tools,
ext. scripts
Excel macros
EA Scripts
Installation User Interface Language(s)
None - import file in
the project, available
for all users
VBScript, JavaScript,
JScript
Enhanced windows,
system output…
Installation on all
clients, available to
use with any project
C#, VB.Net, Java,
C++…
Optional Linked with the
chosen language
C#, VB.Net, Java, C++,
Python, Perl…
n/a (Excel required) Excel Excel VBA
Message or Input box,
system output…
12
EA DATA
Web applications
Custom tools integration
13. Alternatives in using EA API
INTRODUCTION
EA add-ins
3rd party tools,
ext. scripts
Excel macros
EA Scripts
Installation User Interface Language(s)
None - import file in
the project, available
for all users
VBScript, JavaScript,
JScript
Enhanced windows,
system output…
Installation on all
clients, available to
use with any project
C#, VB.Net, Java,
C++…
Optional Linked with the
chosen language
C#, VB.Net, Java, C++,
Python, Perl…
n/a (Excel required) Excel Excel VBA
Message or Input box,
system output…
13
EA DATA
Web applications
Custom tools integration
Compatible with frequent
releases for a large group of users
15. Script Group Types
18
A script is defined under a group
EA SCRIPTS OVERVIEW
Main group types
Scripts under a Normal Group are available from the Scripting view
Scripts under a Project Browser Group are available from the Scripting view or via a right click in the Project Browser
Scripts under a Diagram Group are available from the Scripting view or via a right click in a diagram
16. Scripts organization
EA SCRIPTS OVERVIEW
Reserved for the scripts
administrator/dev team
Libraries of reusable
functions and routines
Users scripts, available
from a diagram or the
Project Browser
Use Groups to organize your scripts
Example:
16
17. Naming conventions
EA SCRIPTS OVERVIEW
Define prefixes to group and identify script functions
Example:
XLS = Excel related scripts (XLS-1 = import/export, XLS-2 = others)
QA = Quality related (QA-1 = cleaning, QA-2 = stats, QA-3 = controls)
TSK = Automated tasks (TSK-1 = generate, TSK-2 = migrate, TSK-3 = update)
SEC = Users, groups and permissions
XT = Extract EA information
17
New order
18. Re-used script functions
EA SCRIPTS OVERVIEW
Project Browser and Diagram scripts + Common script
18
«Project Browser script»
XLS-1-c-Excel Export Class
Details from Branch
«Diagram script»
XLS-1-e-Excel Export Class
Details
«Normal script»
ExportClassDetails-Common
+ processPackage()
+ processDiagram()
- exportClassElements()
Exports details of EA Elements …
1- Located in the provided package (processPackage)
2- Or matching Diagram Objects in the provided Diagram List (processDiagram)
Both call exportClassElements private function
Calls processPackage with
the current package
Calls processDiagram with
the current diagram
Re-used script
19. EA API Methods
EA Automation Interface provides a way of accessing the internals of Enterprise Architect models
EA SCRIPTS OVERVIEW
Repository
Package
EA API Object Model
Element, Connector, Diagram, etc.
set parentPkg = Repository.GetPackageByID(curElement.PackageID): element’s parent package
set curElement = Repository.GetElementByID(selectedDiagObject.ElementID): element matching a diagram object
Using Object methods - VBScript examples:
19
Repository
+ GetDiagramByGuid(String): Object
+ Execute(String): Void
+ GetAttributeByGuid(String): Attribute
+ GetElementsByQuery(String, String): Collection
+ SQLQuery(String): String
+ GetAttributeByID(Int32): Attribute
+ GetElementByID(Int32): Element
+ GetPackageByID(Int32): Package
+ GetDiagramByID(Int32): Diagram
+ GetConnectorByID(Int32): Connector
+ OpenDiagram(Int32): Void
+ GetElementByGuid(String): Element
+ GetConnectorByGuid(String): Connector
«property»
+ IsSecurityEnabled(): Boolean
+ ProjectGUID(): String
Package
«property»
+ Name(): String
+ Packages(): Collection
+ Elements(): Collection
+ Diagrams(): Collection
+ Notes(): String
+ PackageID(): Int32
+ PackageGUID(): String
+ TreePos(): Int32
+ Element(): Element
+ Alias(): String
Element
+ Update(): Boolean
+ Refresh(): Void
«property»
+ Name(): String
+ TaggedValues(): Collection
+ Notes(): String
+ ElementGUID(): String
+ Stereotype(): String
+ Type(): String
+ ElementID(): Int32
+ PackageID(): Int32
+ Methods(): Collection
+ Attributes(): Collection
+ ClassifierID(): Int32
+ TreePos(): Int32
+ ObjectType(): ObjectType
+ Properties(): Properties
provides an entry point to the
model packages and collections
e.g. a Class, Use Case
or an Object
The classes contain anon-exhaustive list
of operations and properties.
*1
1
20. Run SQL queries against the model
EA SCRIPTS OVERVIEW
When a query or update cannot be achieved via a method.
SQL queries can be used …
20
To select specific elements, preventing time consuming loops.
e.g. select datatype stereotyped Classes with the name matching the given variable;
SELECT Object_ID FROM t_object WHERE (Object_Type = 'Class' and (Stereotype = 'datatype'))
and name = '"&attributeType&"'"
To address performance issues related. Example with a bulk creation of ~1000 attributes :
API method call execution time: 120 minutes
set elementAttr = elt.Attributes.AddNew("&attrName&","")
elementAttr.Update()
API method call with a SQL insert execution time : 4 minutes
insert into t_attribute(object_id, name, ea_guid) values …
21. Use SQL queries
EA SCRIPTS OVERVIEW
21
Repository object available methods:
Repository.GetElementSet(query,2) : returns a collection of EA elements according to the SQL query
22. Use SQL queries
EA SCRIPTS OVERVIEW
22
Repository object available methods:
Repository.GetElementSet(query,2) : returns a collection of EA elements according to the SQL query
Repository.SQLQuery(query) : returns an XML formatted string value (SELECT queries only)
23. Use SQL queries
EA SCRIPTS OVERVIEW
23
Repository object available methods:
Repository.GetElementSet(query,2) : returns a collection of EA elements according to the SQL query
Repository.SQLQuery(query) : returns an XML formatted string value (SELECT queries only)
Repository.Execute(query) : runs a query (UPDATE/DELETE/INSERT)
24. Use SQL queries
EA SCRIPTS OVERVIEW
24
Be careful when running UPDATE/DELETE/INSERT queries, it can delete or break your model!
Queries must be compatible with the used DBMS (MySQL, SQL Server, Postgres, Oracle, Jet/EAP)
e.g. apply the right asterisk wild card * vs %
Use Repository.RepositoryType method to get the DB name e.g. POSTGRES
Use EA SQL Scratch pad
To build queries (IntelliSense available: Ctrl+Space)
To test and fix queries from the DEBUG System Output
25. Documentation
EA SCRIPTS OVERVIEW
25
Object Model API: see EA User Guide
EA DB schema: generate a reverse (98 tables)
http://www.sparxsystems.com/enterprise_architect_user_guide/14.0/automation/reference.html
27. For the developer
SCRIPTS HELPERS
27
Scripting variables used
bShowOutput = false
'bShowOutput = true
sOutputPath = ""
'sOutputPath = "C:UsersGFIDesktop"
dim outHeader
outHeader = " | XLS_1-Excel Export Class Details from Branch"
Debug Mode
if (bShowOutput) then
Session.Output SQL
end if
z
Prompt for a Folder?
Script name for
the System Output
Session.Output Now & outHeader & " - Starting"
Dev Helper
28. For the developer
SCRIPTS HELPERS
28
Scripting source EA project Publication EA project Target EA project
XML file
Export reference data
(Automation Scripts)
XML file
Import reference data
Export reference data
(Automation Scripts)
XML file
Import reference data
Delete temporary script
groups SCRIPT: Delete temp scripts
Export reference data
(Automation Scripts)
XML file
Import reference data
Delete temporary script
groups SCRIPT: Delete temp scripts
Disable the scripting
Debug Mode SCRIPT: Set DEBUG OFF
Export reference data
(Automation Scripts)
All scripts are exported
(no selection available)
Publication process :
DEMO
XML file
Import reference data
Delete temporary script
groups SCRIPT: Delete temp scripts
Disable the scripting
Debug Mode SCRIPT: Set DEBUG OFF
XML file
Export reference data
(Automation Scripts)
Export reference data
(Automation Scripts)
XML file
Import reference data
Delete temporary script
groups SCRIPT: Delete temp scripts
Disable the scripting
Debug Mode SCRIPT: Set DEBUG OFF
XML file
Export reference data
(Automation Scripts)
Export reference data
(Automation Scripts)
Import reference data
Published scripts
available to install
EA Support EA AdminEA Support
Deletes
reserved scripts
Updates all scripts
'bShowOutput = true
'sOutputPath =
"C:UsersGFIDesktop"
Dev Helper
Dev working project Intermediary project (blank) Client project
29. For the users
SCRIPTS HELPERS
29
Store the last selected folder for the input or output file(s)
Save time with the option to reuse the previous file location
Built-in help
DEMO
Apply scripts filters
Workaround for the lack of sub menus with 15+ scripts
User Helper
31. Automatically triggered scripts for users
EA-MATIC ADD-IN
31
ea-Matic is a free add-in by Geert Bellekens.
ea-Matic can trigger a script with an associated event.
Replaces users repetitive tasks.
DEMO
EA broadcast events are sent to all add-ins.
e.g. EAOnPostNewElement is received when a new element is created
bellekens.com/ea-matic
'EA-Matic
'a new connector has been created.
function EA_OnPostNewConnector(Info)
'get the connector id
dim connectorID, newConnector
connectorID = Info.Get("ConnectorID")
set newConnector = Repository.GetConnectorByID(connectorID)
MsgBox "New connector type: " & newConnector.Type
end function
“Magic keyword”
User Helper
Associated
event
Add-in installed only for the target users.
33. Principles
SCRIPT DEBUGGING
33
Script debugging aids in the development and maintenance of scripts.
Set Breakpoints to step over/into/out.
View local variables values at the time of execution.
Start Debug
Run Script
34. Code editor key shortcuts
HINTS
34
Ctrl+F2 to set bookmarks, F2/Shift+F2 go to next or previous
Ctrl+Shift+C = Toggle line comment on selection
Ctrl+Space = Intellisense
Shift+Alt+Return = Fullscreen
Ctrl+U = to lowercase, Ctrl+Shift+U = to uppercase
Ctrl+keypad(-) Zoom out, Ctrl+keypad(+) Zoom in, Ctrl+keypad(/) restore
37. Internal use
DEMONSTRATION
37
EA users
Stakeholders, client…
Method
Third party tools
Outside applications & people
Standards
Lock/unlock Branch
Versions
Migrate Diagrams
Attributes mapping
User Helper
Move classes/tables with
criteria (prefix, attr count)
QA
Compare model
with template
Manage EA user permissions
Admin
UML to JDL Generator
(JHipster Entities)
Main topics
38. Main topics
DEMONSTRATION
38
DEMO
EA User Group London 2018
Author: Guillaume FINANCE | Blog: www.umlchannel.com | EA add-in: www.eautils.com
Extending EA with custom scripts