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/