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
I am an independent IT Analyst and Architect with software development background (Java). Certified in TOGAF 9®, ArchiMate® 2, BABOK® (CCBA®) and BPMN (OCEB).
I have used Sparx Enterprise Architect for designing IT systems, in particular manage and specify requirements, model business processes and architecture on many projects in different organizations over the past several years.
I publish articles about Business Analysis, Enterprise Architecture and Sparx Enterprise Architect on http://zubkiewicz.com website.
Even though Agile promised us “working software over comprehensive documentation” in its Manifesto there are still highly regulated industries, such as banking, healthcare, insurance and government administration (to name just few), where IT systems must be properly documented. Even when your development team is agile, proper documentation is still vital for complex solutions. Quite frankly, most of the IT systems developed in-house are complex and closed – they are developed by handful of people who know them inside out but no one else in the organization knows how they work – just image what would happen if they are gone?
Usually, documentation is written by Business Analysts, System Analysts and Architects as a text documents in Microsoft Word with a set of UML diagrams exported from some modeling tool. It is a terrible but extremely popular way of documenting IT systems (for many reasons which are not in the scope of this article). Fortunately, this mundane and unproductive task can be easily automated even for complex and robust templates.
From this article you will learn how to use Sparx Enterprise Architect to created advanced template for Use Case Specification that can be easily used for documentation generation by any member of your team.
How to create extensive Use Case Specification template in Enterprise Architect?
Let’s start from the repository structure. I have following, very simple setup of the repository in Enterprise Architect (left picture). This setup is focused on the Business Analysis and not System Architecture but this does not matter in context do document generation.
The important thing is that the model in Project Browser is presented in the tree-like structure and this approach is also passed on the Document Generation functionality (internal part of EA responsible for report generation). Which means that we can generate documentation for whole model (staring from root node called ‘Model’ in our example) or just one branch, such as Requirements or UseCases.
When we expand one of the branches of the tree, let’s say UseCases we can see what’s located in that package (right picture).
The problem is, that Document Generator can access only elements within selected branch. So in our case it has access only to contents of the Front Office package. It can not move up in the tree structure or “jump” to another branch. Well, at least simple Document template can not.
But what to do if we want to generate UseCase Specification document that also includes Requirements realized by each UseCase and Mockups? We need to access information from different “part” of the model, but stay in the context of UseCases – which are the main subject of UseCase Specification document.
Well, there are many solutions. The first, obvious, one is to reorganize the structure of the project repository, so everything is “under” UseCases package. This is a terrible solution and don’t do it ever, never! Just think what would happen if you would like to document Requirements or Processes – you would have to change the structure for each Template.
To solve this problem, Sparx engineers added Virtual Documents functionality. This is extremely powerful method of generating documentation which allows us to build one big document out of many parts. Each part has dedicated role of documenting particular concept. So, for example, we would have one part for Requirements, one for UseCases, one for Actors, one for Mockups and so on. In my opinion this functionality works best for huge documents, such as Software Architecture Document (SAD) or Business Requirements Document (BRD), which present concepts holistically and are usually created once in a while. On a daily basis we never need documentation that covers whole scope of the solution (IT system). Generating new version of BRD and handling it to Development team every time one Requirement was changed is not useful. On a daily basis more flexible and fine-grained documentation is needed. Unfortunately, setting up Virtual Documents for each smaller case is mundane and time consuming task.
This brings us to the second solution, instead of creating Virtual Documents manually, we may generate them and then use them to generate documentation. This is two step, semi-automatic solution proposed by Geert Bellekens in his article Generate complex documents from Enterprise Architect with a two-step semi-automated approach. It works very well, however it may be quite hard to comprehend for ordinary EA users. After all, not every Analyst and Architect must be Enterprise Architect super user at the same time.
Now, I’d like to present the third solution. I created it quite recently as it uses new feature added lately to Sparx Enterprise Architect in version 12.1.1224. It allows to generate documentation which includes information from different “project branches” by simply pressing F8 button (Generate Documentation key-shortcut).
What I needed was a template that would generate documentation with following parts:
- UML Use Case diagram for each Use case package
- Detailed information about each Use Case, including
- Description (goal, pre-conditions, post-conditions)
- Scenarios: main scenario and all alternative scenarios
- UML Activity diagram presenting visually all scenarios
- List of requirements realized by the Use Case (trace relationship between Use Case and Requirement)
- Mockup diagrams or other images associated with a Use Case
Below there is a picture that collates Table of Contents (ToC) of generated document and Project Structure (inside Enterprise Architect).
Firstly, it is worth to say that by default Document Generator evaluates only the selected package and its sub-packages. In our case that would be all the elements in the red dashed-line box. The realized requirements has been found by SQL script, and Mockups via Document Script (listings of used scripts are included below).
How this was achieved?
The UseCase Specification template has been created with few additional fragments. Fragments encapsulate some specific part of the template and can be reused among many templates. Each fragment is included in the particular place of the main template, they are highlighted in red.
The first fragment is quite boring from template designer perspective. It’s purpose is to include the UML Activity Diagram of each Use Case into the documentation. Please notice that those Activity Diagrams are automatically generated by Enterprise Architect from Structure Scenarios of each Use Case which is a feature of EA that I absolutely love, but I digress.
SQL Template Fragment
The “Fragment UseCase realized Requirements” is responsible for presenting list of requirements that are realized by the particular UseCase. It uses SQL to retrieve information about requirements from EA’s internal database and displays them in a table.
Because information is retrieved by a SQL query we need to embody template in a custom tag and refer directly to the results of the query (objectname, objectstatus, lastmodification, idAlias).
On the line 5 there is #OBJECTID# token. It is Enterprise Architect parameter that during generation of documentation is replaced by the ID of currently processed element. The value of this ID is passed from the main template, therefore it always (in our case) refers to an element of type UseCase. The rest is self-explanatory.
Document Script Template Fragment
It is a type of template that executes a script in order to retrieve data from a model. However, I used it in a little bit more advanced way. The “Fragment Mockup Diagram” uses Document Script to retrieve information from the model and generate RTF document in memory, which is later included in the generated documentation. It is somewhat complex and definitely not straightforward setup which consists of the following elements:
- “Fragment Mockup Diagram” – a template which is included in our main template and is used to execute a Document Script
- MockupDiagram script – it is a JScript executed when the “Fragment Mockup Diagram” is being evaluated
- MockupTemplate – a template used to generate RTF document from the script
As it was said, the “Fragment Mockup Diagram” is just used to execute the MockupDiagram script. To setup it we need to go into Document Options of the template, then Custom Query tab and select Document Script. From the dropdown menu that appears select MockupDiagram (of course you need to create it first – I will explain how in a moment). I think this images illustrates this better.
The main(#OBJECTID#); code executes the main function of the MockupDiagram script, with ID of the currently processed object, in the same way as it was for SQL query explained above.
Note: For some reason it is necessary to include empty custom tag in this Document Script fragment template. Otherwise, generated documentation does not contain this part of documentation generated by Document Script. I think this is a bug in EA, definitely it’s not described in the documentation.
To create a script in Enterprise Architect select Tools -> Scripting from main menu. In the Scripting window create new Normal Group and add New JScript. The source of the MockupScript is presented on the listing below.
- At line 4 the name of the template is defined. This template will be used to generate content for the “Fragment Mockup Diagram”, which was left empty.
- Line 28 – DocumentGenerator.GetDocumentAsRTF(); – this is a builtin function that does all the magic. It generates RTF document in the memory. Later, this RTF document is injected into the main UseCase Specification template. More information can be found in EA help file here DocumentGenerator Class.
- Lines 49 & 54 – they define condition describing how to find mockups for our UseCase. The assumption here is that in every Package to which UseCase is traced contains Mockups. This gives us easy of use while working with the model
- Line 66 – for each Package we generate part of the RTF document using template defined in line 4.
The MockupTemplate is quite simple template that generates part of documentation from data retrieved by MockupDiagram JScript.
It displays package description (Notes) and includes Mockup Diagrams created in Enterprise Architect or in other tools, such as Balsamiq Mockups, placed on the diagram as images.
Those are all components needed to generate documentation. All the rest is present in the model.
How to use it?
We use our template setup in pretty straightforward way. In Project Browser just select UseCases package and click F8 key. Configure the Generate Documentation as presented on the picture below.
Click generate. After generation is finished just click View to see generated documentation. Below is embedded output PDF file you can also download it from here UseCase Specification PDF.
What was achieved?
The possibility to have complex template that is extremely easy to use (jest press F8 key) without sacrificing the repository structure and use of more advanced documentation techniques which may be overwhelming for some EA users. Also the repository model and template promote use of traceability. Whenever there is new Requirement or new Mockup we can add them to the model
and trace to the particular UseCase. Template will pick up automatically new elements added and they will be included in newly generated documentation. Therefor, you can prepare similar template for your team of designers (Analysts, Architects) and they don’t need to worry about the template while adding or modifying elements.
The sample EAP project file can be downloaded here: EAP UseCaseDocumentationExample. The EAP file contains full model, all examples, templates and scripts. To see and edit templates just go to Resources window (Alt+6). To generate document for yourself just go to How to use it? paragraph above and follow the instructions.
You’re free to modify it and use it for commercial purpose. Any comment or simple “Thank you” will be highly appreciated :-)
This article was originally posted on my blog http://zubkiewicz.com/
How to combine Sparx Enterprise Architect and BABOK to manage Requirements in a modern way?
Days when Business Analyst was using only Word and Excel applications together with e-mail program are slowly fading into the past. This is a good thing. There are many tools that allow us to work faster and smarter. One of them is my favorite Sparx Enterprise Architect. The tool so powerful and versatile that it's hard to find single person who used all of its features :-)
Personally, I used Enterprise Architect in my work for past several years to design IT systems and prepare documentation of them. I used a lot of built-in features of Enterprise Architect to streamline my work and improve quality of my deliverables. Among them Relationship Matrix, powerful template functionality for document generation, extensive support for Use Case modeling.
Among many other things, BABOK Guide defines list of commonly used requirement attributes:
- Absolute reference: provides a unique identifier. The reference is not altered or reused if the requirement is moved, changed, or deleted.
- Author: provides the name of the person who needs to be consulted should the requirement later be found to be ambiguous, unclear, or in conflict.
- Complexity: indicates how difficult the requirement will be to implement.
- Ownership: indicates the individual or group that needs the requirement or will be the business owner after the solution is implemented.
- Priority: indicates relative importance of requirements. Priority can refer to the relative value of a requirement or to the sequence in which it will be implemented.
- Risks: identifies uncertain events that may impact requirements.
- Source: identifies the origin of the requirement. The source is often consulted if the requirement changes or if more information regarding the requirement or the need that drove the requirement has to be obtained.
- Stability: indicates the maturity of the requirement.
- Status: indicates the state of the requirement, whether it is proposed, accepted, verified, postponed, cancelled, or implemented.
- Urgency: indicates how soon the requirement is needed. It is usually only necessary to specify this separately from the priority when a deadline exists for implementation.
Source: BABOK Guide V3, page 45.
As it is stated, those are most commonly used, which means that this list is not written in stone and each Analyst must decides which to use. Actually, for this exercise we have a special task in BABOK Guide named Plan Business Analysis Information Management.
The purpose of Plan Business Analysis Information Management is to develop an approach for how business analysis information will be stored and accessed.
Source: BABOK Guide V3, page 42.
Since I read the Mastering the Requirements Process: Getting Requirements Right (which was quite sometime ago) I extended my requirement attributes list with those two:
- Fit Criteria
Justification is a rationale for requirement. It explains why requirement is needed by stakeholder(s). It is very important attribute as it allows to distinguish between real requirements and solutions requested by stakeholders that pretend to be requirements.
Fit Criteria's aim is to make sure that requirement is verifiable. It means that there is defined way of proofing that the requirement is met. This attribute directly addresses one of the characteristics of a good requirement which is Testable. (Have you ever seen requirements like: "System must be easy to learn" or "System must be user friendly" and wondered What the hell this means? I bet you did! :-) )
Enhanced Requirement Attributes Addin for Sparx Enterprise Architect
Sparx Enterprise Architect does not support all of the mentioned above attributes out of the box. Some are there, but not all of them. You may add missing ones as TaggedValues in requirement element, but working this way on a daily basis is hard and miserable.
To address this problem I created Enhanced Requirement Attributes Addin for Enterprise Architect. In short ERA addin (addin means plugin). It adds new properties window which is dedicated only for Requirement type. When you double click on any Requirement element this new window will be opened by default. Properties for other element types will be opened in EA's default properties window.
Sometimes you may still want to open Requirement element in default properties window, just click 'Default properties' button, or press Alt+Enter keys on the selected element.
Requirement properties window aggregates in one place all most important attributes that were described above. This makes reading and editing a requirement very easy. Requirement properties windows supports:
- Some of BABOK / Volere additional attributes
- Rich edit functionality for Description attribute
- Key shortcuts (Ctrl+S - save & close and Ctrl+W - close without saving)
All of the additional attributes are stored as TaggedValues of Requirement element. This a built-in functionality of Enterprise Architect. There is no custom solution for storing information. As you can see in the picture below, you can access and edit those attributes in normal properties window.
This means you may use ERA Addin without worrying about compatibility. You can be the only person on the project or in your organization using ERA Addin and other Analysts & Architects will still be able to view and edit Requirement without problems. Of course it will not be as easy and convenient as in ERA Addin, but important thing is that you will not break anything!
ERA Addin does not use any custom UML Profile, it works with default, built-in Requirement type. So you can start using it on your already created requirement models without any conversions or problems with migration. There is also no risk, if you will not like ERA Addin you will simply uninstall it, there will be no impact on your model.
Generation of documentation
ERA Addin was created with easy reporting in mind. It comes with a Requirements Details template that is used to generate documentation about all additional requirement attributes. Here you can download sample document with generated documentation about requirements in Stakeholder package.
ERA Addin is free to use for everybody including commercial purposes. It is redistributed under Creative Commons Attribution-NoDerivatives 4.0 International Public License.