Top Community Contributors
London User Group; Call for Speakers
Written by DT_Sam
Introducing RepoDoc, a document generator for Enterprise Architect
Written by Archimetes
Written by philchudley
SysML 1.4 reference card
Written by Guillaume
Enterprise Architect identified for Agile Development and DevOps: SD Times In-depth Feature
Written by sparxsystems
Enterprise Architect User Group: London 2017
Written by DT_Sam
Panorama 360 Insurance and Wealth Management Enterprise Business Framework is available on Amazon
Written by Pierre Gagne
We are Profiling EA Users
Written by sparxsystems
Delete or move elements to package which are found by Searches (SQL, Query Builder, Standard Searches). These vbscripts allow you to easily handle found elements and to develop your own vbscripts to manipulate found things. In effect these scripts use bookmarked or elements copied to clipboard. It's an extension fo Geert Bellekens VBScripting Library.
- Use SQL Searches to move or delete found elements, diagrams or packages copied to Clipboard
- Use Bookmarked elements from e.g. Standard / QueryBuilder Searches to move or delete elements
- Handle bookmarked or result of SQL searches with your individual script
These scripts are using Geert Bellekens Script Framework (powerful!, Open Source)
- See also there for updates, folder ho
Standard Search / Bookmark:
- Set bookmarks
- e.g. by Standard Search
- If move: Select target package in ProjectBrowser
- Run Script:
- hoModelSearch, DeleteBookmarkedItems or
- hoProjectBrowser, MoveBookmarkedToSelectedPackage
Standard Search / Clipboard:
- Run SQL Search
- each row shall contain GUID of the items to handle
- Copy wanted rows to clipboard (eg: CTRL+A, CTRL+C)
- If move: Select target package in ProjectBrowser
- Run Script:
- hoModelSearch, DeleteClipmarkedItems or
- hoProjectBrowser, MoveClipmarkedToSelectedPackage
In Action: Delete item found by SQL Search or Query Builder Search
- Run SQL Search with element GUID as result / Run Query Builder Search
- Copy to Clipboard (SQL Search / Bookmark (Query Builder Search)
- Run Delete ClipboardedItems / Delete BookmarkedItems
Move items found by SQL Search to package
- Copy found elements to Clipboard
- Select Package, Right Click, Scripts,...
Move bookmarked items
(bookmarked in eg. Diagram or found by Standard Search / Query Builder Search) to selected package)
- Run Standard Search or Query Builder Search
- Bookmark wanted elements
- Select Package, Right Click, Scripts,...
- It works
- Project DataManagement, Import ReferenceData, Select File (Script.xml)
- Select 'Automation Scripts'
- See the scripts for details:
- ho (reusable groups to extend functionality according to your needs)
- hoModelSearch Group of type ModelSearch
- hoProjectBrowser Group of type ProjectBrowser
Bookmarks (see also EA help):
- Search Window: Query Builder Results, Right Click, Bookmark Element,
- Diagram: Select elements, Shift + Space
- Diagram: Select elements, Edit, Bookmark selected,
Designing solution architecture is about making best possible choices in context of current requirements and constraints. Behind every architecture decision there is some context and every architect should document the reasons of important decisions that are made. This article will focus on how to document architectural decisions in the context of project requirements in Sparx Enterprise Architect.
Value of architecture documentation
As an architect one needs to document important issues, possible solutions and reasons for choosing one of the solutions. There are various reasons to document decisions in projects lifecycle:
Reasoning that stood behind a choice will blur with time so the architect will not be able to precisely discuss or defend the choices or evaluate if the decisions made are still valid
Architect may need to describe reasons for his decisions for various reasons like some other architect joining the team or client (or consultancy company hired by client) having some questions about the design
Requirements and constraints may change in time and decisions may have to be reviewed. Knowledge about full context behind decisions made is fundamental in review them.
Architect may choose to leave project or for some other reason other architect may have to take over the responsibilities of the architect who originally made the decisions
Building database of architectural patterns and decision will allow the company to learn with every project, instead of relying on memory of individuals
Software architecture is also the dominant factor contributing to poor software architecture quality metrics of system. Bad architecture choices lead to costly development and maintenance and poor extensibility. They also have a tremendous impact on other software architecture quality metrics of system as reliability, scalability or testability. SEI has done research in this area, see A Field Study of Technical Debt . Documenting architectural decisions is one of TOGAF's principles .
What to document
Deciding on what to document requires experience. Documentation must be lean and contain enough information to be helpful. A very good analysis is available in Sustainable Architectural Design Decisions  article, you can also find many blog posts or discussions on this subject on forums and social media portals. One thing to remember is that software architecture documentation is not a replacement for low level design documentation (if such is provided in project) or documenting code. You can also read about what to document in Documenting Software Architectures: Views and Beyond .
Deciding on what the documentation should contain also depends on the project. As discussed in Sustainable Architectural Design Decisions  formal documentation with many fields will in many cases result in gradual degradation of quality of documentation and even questioning the business value of documenting software architecture at all. A minimalistic and lean documentation may contain:
Issue name – a short name to identify issue in human readable form
Issue statement – description of the issue in textual form
Context (this includes requirements) of the issue – context should include functional requirements, non-functional requirements and other factors that have impact on decision.
Descriptions of alternative solutions - description in textual form
Reasons for choosing one solution - description in textual form
Status of decision – one of a few states
Date of last modification or evaluation
Depending on specific context or requirements other information may be included of course.
Where to keep documentation
Decisions can be kept in various places like:
Files based on some templates
Using case tool that is used to model requirements ha an advantage of keeping all data together and allowing to do searches on data easily. One of the important aspects of documenting software architecture decisions discussed in Sustainable Architectural Design Decisions  is keeping decisions with requirements.
Sparx Systems Enterprise Architect is an example of a CASE tool that allows architects to document the software architecture design decisions with links to the requirements. Sparx Systems Enterprise Architect is often used to manage requirements, design the solutions architecture and to convey design to development teams. Using Sparx Enterprise Architect makes it possible to keep requirements, architectural issues log and other design artifact (like state machines, process models, service models) in one place and to create connections between issues and requirements. This allows us to partially or fully automate process of selecting issues that need to be reviewed. Additional benefit of using Sparx Enterprise Architect is the document generation features of Enterprise Architect. It is possible to keep all requirements management, analysis and design data in Enterprise Architect and to generate documentation straight from EA. Other artifact like notes made on meetings that have impact on design may also be included as linked documents or as a simple link to version control system.
Using Sparx Enterprise Architect and UML Profile
To efficiently store architectural decisions in Enterprise Architect one should create a profile. It is possible to create an architectural decisions log without a profile, using one of extension mechanisms of UML like stereotypes or tagged values. Using profile gives us a better separation between model elements and allows to search for some data in the model more easily. Custom document templates for linked documents can also be used to store architectural decisions - details on how to do this can be found in Enterprise Architect documentation . Searching these documents would be more difficult as it would require to build custom application or a plugin. Using UML profile gives use more searching options.
Creating UML profiles is described well in Enterprise Architect documentation  so there is no need to repeat this information. This article will focus only on main steps of creating UML profile in EA.
In order to create a custom UML profile in Enterprise Architect you create a Profile element in the model (see  for details). Then you add required meta classes and stereotypes to the Profile element.
Architecture decision log profile should contain five stereotypes:
Architectural issues log – this stereotype extends package
Architectural issue – this stereotype extends package
Architectural context – this stereotype extends artifact
Architectural decision - this stereotype extends artifact
Architectural alternative solution - this stereotype extends artifact
Architectural issues log and Architectural issue stereotypes extend package in order to be containers for other elements. Architectural issues log will contain many Architectural issues.
Each issues will have it's own packages in order to lessen the maintenance cost for Enterprise Architect model in the context of document generation. If we would keep them in one package then ordering the elements would be problematic, especially if later some new alternative decisions would be added.
Architectural issue will store description of the problem and a short title (we wont to keep the log simple). Architectural issue will also group architectural issue context, decision and alternative solutions. Each context must be connected via a trace relation to the requirements that engendered this issue.
Architectural context element will specify known constraints (both technical and non-technical) that limit possible solution space.
Architectural decision will contain reasoning on why the solution was chosen. This should be a short text as every alternative solution should contain advantages and disadvantages of a given solution that will give a good insight on each solution. This model allows to work with alternative solutions more easily, each solution has its dedicated element so they do not get mixed up making them harder to read.
Each Architectural issue will contain a number of Architectural alternative solution. Each solution alternative is independent solution option.
Architectural issues log is a package that will group various architectural issues.
This profile will contain necessary fields to convey information discussed in previous chapter:
Issue name – the Architectural issue element name (Enterprise Architect provided it)
Issue statement – the description of Architectural issue element
Context (this includes requirements) of the issue – Architectural context element will specify known constraints (both technical and non-technical) in it's description.
Descriptions (free text) of alternative solutions – the description of separate Architectural alternative solution elements
Reasons for choosing one solution (free text) - the reasons will be described in Architectural decision element's description
Status of decision – the status field of Architectural decision element
Date of last modification or evaluation – this will be the date on Architectural decision element
All the elements are shown on the diagram below:
In order to be used the profile must be first exported from Enterprise Architect as a profile and then imported as a resource. To export the profile right click the profile's package element and select Advances and then Save Package as UML Profile (see image below):
To import the profile right click UML Profile In Resources view and then choos Import Profile:
After doing this a new category of tools will be available. Image below shows an example of a small decision log created using this profile:
Custom model search
When we have the profile in place we can create a custom search that will allow us to find the decision for which requirements have changed. Both elements have last modification date so it is easy to track down issues that need to be reviewed.
We can do it in several ways:
Building a custom application that will use Enterprise Architect automation interface  to search repository – this requires a custom application to be build prior to executing any searches. Application would not be integrated with Enterprise Architect.
Search the Enterprise Architect database – using database level searches may be problematic as there may be differences between Access and some RDMBS' SQL executed to search the model for issues to review. Additionally if this solution will be chosen then search would not be integrated with Enterprise Architect.
Create Enterprise Architect plug-in - similar but not the same to building custom application. Plugin would be integrated with Enterprise Architect and thus more convenient to use.
Do a custom model search using Enterprise Architect extension features – the only thing required is to build a query and let Enterprise Architect handle query execution.
Last solution is quite simple and thanks to the fact that it uses Enterprise Architect extension features user will work with Enterprise Architect only to manage Architecture Decisions Log.
Such custom model search can be created in two ways:
With query designer
With SQL queries
Second option is more powerful but a little bit more difficult. There is a very good description on how to create such query on Bellekens blog . In our case we will search for objects with type “Architecture issue” and choose those for which the requirements changed. The query that does this search can be found below:
select decision.ea_guid as NodeGUID, decision.name as Name
from (((( t_object req -- start with requirements
-- go to dependency connector
inner join t_connector requc on requc.End_Object_ID = req.Object_ID)
-- get Architectural decision context
inner join t_object ctx on requc.Start_Object_ID = ctx.Object_ID)
-- go to dependency connector for decisions
inner join t_connector decon on decon.End_Object_ID = ctx.Object_ID)
-- get Architectural decision
inner join t_object decision on decon.Start_Object_ID = decision.Object_ID)
where ctx.Object_Type = 'Artifact' and ctx.Stereotype = 'Architectural context'
and decision.Object_Type = 'Artifact' and decision.Stereotype = 'Architectural decision'
and decision.ModifiedDate < req.ModifiedDate
Description of columns and tables used:
t_object - this is a table that stores information about elements in model
ea_guid - UUID in Enterprise Architect model
name - name of element
Object_ID - object identifier in Enterprise Architect repository
Object_Type - type of object (class, artifact, interface, etc.)
Stereotype - stereotype of this object
ModifiedDate - date of modification
t_connector - this is table stores elements about relations (also elements in model)
End_Object_ID - id of object at the end of relation
Start_Object_ID - id of object at the start of relation
Using this simple query we can quickly validate our model and see what needs to be reviewed.
In order to extend the query by adding some columns not covered in this example than be sure to take a look at Read Inside Enterprise Architect  site.
Keeping project documentation together is important for maintenance and architectural solution library. Creating such library must not be too much burden so it will not become an unwanted task. With Enterprise Architect and custom profile creating such portfolio is easy. Keeping all project information in one place makes it possible not only to maintain decisions by checking if they are valid or learn on past decisions and reuse them. It also allows to build cohesive and comprehensive project documentation. Thanks to Enterprise Architect powerful reporting features we can generate documentation for the projects straight out of Enterprise Architect. Architecture decisions are part of projects documentation, a very important part so they need to be included. No more copy & paste of diagrams and their descriptions.
Creating Charts in Enterprise Architect to Aid Decision Making
Date: September 2014
Mr Scott Hebbard, Communications Manager at Sparx Systems, will show how Charts in Enterprise Architect can help you manage projects, communicate strategy, identify trends, track KPI's and make informed decisions.
In this webinar you will learn how to:
- Place Charts and Graphs on diagrams, group them to display an interactive project dashboard and include them in generated reports
- Source data from the model, from specific Packages within the model, or from a custom SQL query that extracts the information from the model
- Create burn down charts and time series graphs that are automatically updated by Enterprise Architect on a regular basis.