Direct Answer
Sparx EA has a powerful built-in scripting and automation capability that most teams never fully use. You can automate diagram generation, model validation, batch reporting, element creation, and custom toolbox behaviour — in VBScript, JScript, or C# (via the Add-In API). The capability is real. The honest qualifier: scripting in Sparx EA requires dedicated internal capability to build and maintain. Ad hoc scripts written by one architect and abandoned when they move on create more problems than they solve. Sparx Services’ Amplify offering is designed to build this capability sustainably in your team — not as a one-off delivery.
Key Takeaways
- Sparx EA’s scripting engine supports VBScript, JScript, and (via Add-In) C# — covering everything from simple model searches to full automation pipelines
- The Add-In API gives full programmatic access to the EA repository: read, write, validate, generate, transform
- Practical automation wins: batch diagram generation, model validation, automated reporting, MDG element creation, integration with external data sources
- Honest limitation: scripting requires dedicated skill to build and maintain — without it, scripts become liabilities
- When NOT to automate: one-off tasks, rapidly-changing model structures, and anything better served by EA’s native capabilities
- The Amplify offering builds sustainable scripting capability in your team, including documentation, testing discipline, and handover
What the Scripting Engine Does
Sparx EA’s internal scripting engine is accessible via the Scripting window (Extensions > Scripting in the main menu). It supports three languages:
VBScript: The original, most widely documented scripting language for Sparx EA. Large body of community examples available. Synchronous, straightforward, directly accesses the EA Automation Interface. Adequate for most internal automation tasks.
JScript: Microsoft’s JavaScript implementation, available as an alternative to VBScript. Syntactically familiar to web developers but with the same EA Automation Interface access.
C# (via Add-In API): For production-grade automation, the Add-In framework allows you to build compiled .NET assemblies that integrate directly into the Sparx EA UI — adding menu items, toolbox entries, ribbon controls, and event handlers. The Add-In API is the right choice for team-wide automation that will be used regularly and needs to be reliable.
All three access the same underlying EA Automation Interface — a COM-based object model that exposes the full repository structure: packages, elements, connectors, diagrams, attributes, operations, tagged values, and constraints.
The EA Automation Interface: What You Can Touch
The Automation Interface is the key to understanding what scripting can and cannot do. Everything in the EA repository is accessible programmatically:
- Repository navigation: Iterate packages, find elements by name, GUID, or type; traverse the full model hierarchy
- Element creation and modification: Create new elements, set properties, add tagged values, link to other elements via connectors
- Diagram manipulation: Create diagrams, add diagram objects, set positions and formatting, generate diagram images
- Model search: Run SQL queries directly against the repository database, or use EA’s built-in Model Search with custom queries
- Validation: Apply validation rules programmatically and collect results
- Document generation: Trigger RTF/PDF report generation from templates
- External data: Read from files, call web services, write to databases — EA scripts run in the Windows environment and can use any COM-accessible library
What the Automation Interface does not do natively: it does not provide REST API access (that is what EA GraphLink adds), and it does not run without an active EA client session (automation scripts require EA to be open).
Practical Automation Scenarios
Batch Diagram Generation
If your programme produces a defined set of diagrams on a regular cycle — weekly architecture views, monthly change impact diagrams, release documentation — these can be scripted to run unattended (or at the click of a button), generating consistent diagram images or RTF documents from the current model state.
This eliminates a significant manual effort in programmes where diagram production is a recurring deliverable, and ensures consistency: the script generates diagrams to the same standard every time, without the variation that comes from different architects applying different formatting choices.
Model Validation Scripts
Sparx EA includes built-in UML validation, but real programmes have model conventions that go beyond UML syntax. Common custom validation rules:
- Every element of type X must have a description
- Every interface must have at least one realising component
- Every requirement must have a traceability link to a design element
- No package may exceed a defined element count (a model health check)
- Every tagged value of type Y must contain a value from a defined list
These rules can be implemented as VBScript or C# validators that run against the model on demand or as part of a model review process. Validation results can be written to a report, logged to a file, or surfaced as EA model issues.
Automated Reporting
Most EA reporting is done via EA’s built-in document generation (RTF templates) or via model search and manual export. Scripted reporting extends this to:
- Scheduled or triggered report generation (e.g., every time a specific package is changed)
- Multi-format output (generate the RTF, convert to PDF, archive to SharePoint)
- Data-driven reports that combine EA model data with external sources (e.g., join EA application inventory with CMDB data from a SQL query)
- Custom HTML reports generated directly from the model for stakeholder consumption
MDG Element Creation and Governance
When teams are working with custom MDG stereotypes, creating new elements with the correct stereotype, the correct tagged values, and the correct parent package can be error-prone when done manually. Scripts can provide guided creation wizards — prompting the architect for the required information and creating a correctly-formed element, reducing MDG compliance errors.
Integration with External Data Sources
Sparx EA scripts can call external web services (via WinHTTP or MSXML COM objects), read from Excel files (via COM automation), query SQL databases (via ADO), and write results back to the EA model. Practical examples:
- Pull application data from a CMDB API and populate EA application elements
- Read requirement data from a Jira or Azure DevOps export and create linked EA requirement elements
- Push EA model metadata to an external register or governance tool
These integrations require care — they are writing to the model and must be idempotent, well-tested, and documented. But they eliminate the manual synchronisation work that otherwise falls on architects.
The Add-In API: Production-Grade Automation
For automation that needs to be reliable, maintainable, and used by an entire team, the Add-In API is the right approach. A Sparx EA Add-In is a .NET DLL registered as a COM server and declared in the Windows registry as an EA Add-In.
Add-Ins can:
- Add custom menu items, ribbon controls, and toolbox pages
- React to EA events (element created, diagram opened, model saved)
- Implement custom validation rules that integrate with EA’s built-in validation framework
- Add custom properties pages for specific stereotype types
- Generate custom diagram layouts
The development and testing workflow for Add-Ins is a software development discipline — version control, unit testing, build pipeline, deployment packaging. Teams that approach Add-In development as “a quick script” consistently underestimate the maintenance burden.
When NOT to Automate
The honest assessment: scripting in Sparx EA is not always the right answer.
Don’t automate one-off tasks. If you need to bulk-update 500 elements once, write the script, run it, delete it. Don’t invest in making it production-quality.
Don’t automate rapidly-changing model structures. Scripts that iterate over a package hierarchy or rely on specific element types break when the model structure is reorganised. If your model is still being designed, stabilise the structure first.
Don’t replace native EA capabilities with custom scripts. EA’s built-in document generation, model search, and diagram templates cover most reporting needs. Before writing a script, confirm that EA’s native tools genuinely cannot do what you need.
Don’t automate without a skill owner. This is the most important limit. A VBScript file that no current team member understands is an operational liability. Before committing to an automation investment, confirm that at least one person in your team can maintain it.
The Maintenance Burden: What Teams Consistently Underestimate
Scripting in EA is deceptively easy to start — VBScript is accessible, the Automation Interface is well-documented, and early scripts often work quickly. The maintenance burden emerges later:
- EA version upgrades occasionally change API behaviour
- Model structure changes (new packages, renamed stereotypes) break element-finding logic
- Scripts written for one project are repurposed for another with different conventions and fail silently
- The person who wrote the script leaves the team
Sparx Services’ Amplify engagement addresses this directly: scripts and Add-Ins produced in an Amplify engagement are documented to a defined standard, tested against the team’s actual repository, and include knowledge transfer to at least two team members. We do not deliver a script without delivering the capability to maintain it.
FAQ
Q: What scripting languages does Sparx EA support? A: Sparx EA’s internal scripting engine supports VBScript and JScript. For production Add-Ins — compiled automation that integrates into the EA UI — the Add-In API uses .NET (C# or VB.NET). VBScript is the most widely used for internal scripts because of the large community knowledge base. For any automation that will be team-wide and regularly used, the Add-In framework with C# is the appropriate choice.
Q: Can I automate diagram generation in Sparx EA? A: Yes. Sparx EA’s Automation Interface provides programmatic access to diagrams — you can create new diagrams, add elements to existing diagrams, set positions and formatting, and generate image or document output. Batch diagram generation (e.g., generating a standard set of views across a portfolio of applications) is one of the most common automation use cases. The output quality depends on how well the underlying model elements are connected — automation cannot compensate for a poorly-structured model.
Q: What is the difference between EA scripting and EA Add-Ins? A: Scripts (VBScript or JScript) run inside the EA scripting engine — they are quick to develop, don’t require compilation, and are useful for personal or team-internal automation. Add-Ins are compiled .NET assemblies that extend the EA application itself — adding menu items, toolbox pages, event handlers, and custom UI. Add-Ins are the right choice for team-wide production automation; scripts are the right choice for per-project or personal automation. Both access the same underlying EA Automation Interface.
Q: Can Sparx EA scripts access external databases or APIs? A: Yes. EA scripts run in the Windows environment and can use COM-accessible libraries — including ADO for database access, WinHTTP for REST API calls, and MSXML for XML/web service interaction. This allows scripts to pull data from external systems (CMDB, Jira, ServiceNow) and populate EA model elements, or push EA model data to external registers. These integrations require careful design and testing to ensure they are idempotent and don’t corrupt the model.
Q: How do I validate custom modelling conventions in Sparx EA? A: EA’s built-in validation checks UML syntax, but custom conventions (e.g., “every Application element must have a Business Owner tagged value”) require custom validation scripts. These can be implemented as VBScript scripts that iterate model elements and check conditions, or as C# Add-In validators that integrate with EA’s built-in validation framework (appearing in the same Validation Results window as built-in checks). Sparx Services’ Amplify engagement typically includes a set of custom validators aligned to the team’s MDG conventions.
Q: When should a team invest in EA scripting capability? A: Invest in scripting when you have: (1) a stable model structure that scripts can rely on, (2) a repeating task that consumes significant manual effort, (3) at least one team member who can own the scripts long-term. Do not invest in scripting as a substitute for good MDG governance — a well-structured model with consistent stereotypes and tagged values produces better results from EA’s native capabilities than a poorly-structured model with complex scripts applied on top.
Work with Sparx Services
Building scripting and automation capability in Sparx EA is a core component of the Amplify offering. Amplify is designed for architecture practices that want to accelerate their EA programme — through custom validators, automated reporting, MDG-compliant element creation tools, and integration scripts — while building the internal capability to maintain what is delivered.
Amplify engagements are scoped between $45K and $160K depending on the complexity of the automation requirements and the size of the practice.
Explore the Amplify Offering | Talk to a Sparx Services Architect
