Enterprise Architect version 15.2

download
purchase

My Profile

Social Media Channels

facebook  twitter  youtube   linkedin

Displaying items by tag: documents

Subscribe to this RSS feed
Thursday, 02 March 2017 14:25

RepoDoc, a call for testing

Try RepoDoc, a new way of documenting your repository.

It’s easy to use, powerful and we offer it for free to anyone willing to test or help.

 

What is RepoDoc?

A document generator add-in for Enterprise Architect.

 

What makes it special?

  • uses Liquid templates that are easy to create, modify and maintain,
  • offers flexible repository filtering capabilities,
  • makes non-linear document generation possible,
  • supports a wide range of document formats including, but not limited to, HTML, LaTeX, PDF, Markdown, AsciiDoc, CSV, XML or JSON files, SVG, source codes in different languages,
  • contains a built-in post processor.

 

How can you help?

  • try it out and submit your wishes for a must/nice to have functionality,
  • write a new interesting template or let us know what kind of template would you need.

 

What you can achieve?

Here are few examples of documents, generated with RepoDoc. Find more at repodoc.archimetes.com.

 

UML model overview (HTML)

htmldocument

 

Requirements catalogue (LaTeX)

latexdocument

 

Dependency graphs (DOT/Graphviz)

Dependencies between UML elements.

svgdocument

Dependencies between Archimate elements.

svgdocument

 

Class diagram overview (AsciiDoc)

generatedpdfdocument

 

Package list (JSON)

generatedjsondocument

 

Published in Community Resources
Tagged under
Read more...
Monday, 06 February 2017 13:34

Introducing RepoDoc, a document generator for Enterprise Architect

About

RepoDoc is a document generator for Enterprise Architect able to produce a variety of document formats using templates written in any text editor.

 

How it works

RepoDoc takes a document template and a starting package as input. It outputs a plain text document together with repository artifacts specified in the template and taken from the repository. An optional profile may be specified to instruct RepoDoc to post-process the document with a third party software (like Asciidoctor or Pandoc).

repodoc how it works
RepoDoc uses plain text templates and an easy to learn Liquid template language. This allows to output a broad range of different plain text formats like CSV, XML or JSON, but also to post-process the result in various third party backends to produce an office document like DOCX. It also offers new possibilities when iterating repository like multiple iterations, custom loops, conditional expressions and more.

 

How to use

  1. Download and install latest RepoDoc bundle.
  2. Start Enterprise Architect and open your project.
  3. Select RepoDoc from the Specialize ribbon and open its control panel.
  4. Click Generate.
  5. Click View.

repodocuserguide_formdocumentgenerator.png

 

Features

✅ Markup languages

Use your favorite markup language like Markdown or AsciiDoc to prepare your document then convert the output to a HTML or DOCX with a single click.

repodocfeatures_outputexample.png

✅ Conditional expressions

Document only elements you need and when you need them. Write logical conditions based on name, type or number of child elements. No more empty sections or tables in the output document.

{%- for element in package.elements -%}
  {%- if element.type == "Actor" -%}
    Documenting actor name {{ element.name }}
    and actor notes {% if element.notes != "" %}{{ element.notes }}{% endif %}
    (but only if non empty).
  {%- endif -%}
{%- endfor -%}

✅ Multiple iterations

Iterate and document your repository items multiple times. Create requirements section first and then add a use case section. Everything aligned in a single document.

Now I'm documenting only actors.
{%- for element in package.elements -%}
  {%- if element.type == "Actor" -%}
    ...
  {%- endif -%}
{%- endfor -%}
And now I'm documenting only use cases.
{%- for element in package.elements -%}
  {%- if element.type == "UseCase" -%}
    ...
  {%- endif -%}
{%- endfor -%}

✅ Output redirection

Output images or artifacts to individual files. Export data in different formats to multiple files.

✅ Relationships & analysis

Walk through the connections for elements and diagram objects and document important ones. Analyze and document impacts with recursive templates.

repodocfeatures_impact.png

✅ Version control

RepoDoc uses plain text Liquid templates that are ideal for version control system. Track changes in your templates and tag them easily.

 

Want more?

Select another template or write quickly your own with an easy to learn language. Find out more about RepoDoc at repodoc.archimetes.com.

Published in Community Resources
Tagged under
Read more...
Thursday, 12 November 2015 19:34

Tutorial: Generate complex documents from Enterprise Architect with a two-step semi-automated approach

Bellekens DocGen example
  • Step 1: Create the virtual document with a script
  • Step 2: Generate the document from the virtual document

Document generation is important in most organisations that work with Enterprise Architect. Storing information in the model is good, but most stakeholders still require documents.

Documents are using as a tool for validation, as a work order, or just to give you an overview of a specific set of thing in the model. The main advantages of a document versus a model is that it has a limited scope and a linear order. You can read a document from start to finish, whereas you cannot do that with a model. Documents are, and will always be an important tool in developing applications.

Enterprise Architect comes with a sophisticated document generator that has seen great improvements in the last versions (v10, v11, v12). You also get a standard set of document templates that will quickly generate a document for a part of your model.

The problems arise however the moment you try to do something a bit more sophisticated with the document templates. Get information from different packages, use different templates for the same (set of) elements, etc… You will quickly realize that the approach of having one large template that generates the whole document is not useful for real-world document requirements.

Luckily EA has an alternative to the single template approach: Virtual Documents

Free Download

I’ve put together an example model and an MDG to demonstrate this approach. The MDG contains all scripts, templates and SQL Searches to generate a decent Use Case Document.

Bellekens DocGen MDG and example model
Bellekens DocGen MDG and example model
€0.00
 
 
 

 After you open the Hotellio.eap file, right click on the Reservations use case diagram and choose Create Use Case Document

Create Use Case Document

Then select the package to store the virtual document in and fill in the version.

Finally select the «master document» package and press F8 so start the document generation. Make sure to select the correct cover page and style sheet

Generate Document

Virtual Documents

Virtual Documents are used to define the contents of a document as a set of individual sections, each with its own source and template.

Virtual Documents structure

There are two types of elements that are used for virtual documents

  • Master Document
    Represents the document to be printed. You can give it some parameters that can be used in the document itself such as title, Version, Status, etc…
  • Model Document
    Represents a section in your document. The model document gets an RTFTemplate, and you have to define a source for this section. The source tell us which element(s) from the model should be used in this section. There are two ways to define the source. You can either drag one or more packages onto it, or you can fill in the Model Search and Search Term.

Master Documents get stored in the model as stereotyped packages and they contain stereotypes classes to represent the Model Documents

Virtual Document example

In the project browser this looks like thisVirtual Document project browser.

The Master Documents get the stereotype «master document» They contain tagged values to store things like ReportAlias, ReportTitle. Event though you can assign an RTF template to the master document this seems to be pointless since it gets ignored when printing a document.

Model Documents get the stereotype «model document». The links to the packages that serve as the source for a model document are created by dragging the package from the project browser onto the model document. This creates an attribute that maintains the link to the package.
Tagged values are used to indicate the template to use, the model search to use, and the search value to use on that search.

This mechanism of model documents allows you to very precisely control what will be printed in the document.

Templates

RTF templates are stored in the Resources section of your model. In order to see and manage them enable the resources view using View|Resources

template sections

Templates for document that have a package as source can start from the package tag and access all element, diagram etc.. in that package.

If your source is an SQL search that returns elements your template content can be placed in the element section

SQL Search

The SQL search I use to select a single element based on its GUID this following:

1
2
3
4
5
6
7
8
9
select c.ea_guid AS CLASSGUID,c.object_type AS CLASSTYPE,c.name AS Name, c.stereotype AS Stereotype,
package.name AS PackageName ,package_p1.name AS PackageLevel1,package_p2.name AS PackageLevel2,package_p3.name AS PackageLevel3
from ((((t_object c
inner join t_package  package on c.package_id = package.package_id)
left join t_package  package_p1 on package_p1.package_id = package.parent_id)
left join t_package  package_p2 on package_p2.package_id = package_p1.parent_id)
left join t_package  package_p3 on package_p3.package_id = package_p2.parent_id)
where
c.ea_guid like '<Search Term>'

Printing

When you select the Master Document you can open up the document generation dialog by pressing F8

Generate Document

Here you can set the cover page, table of contents, and the style sheet to use.

Side note: Invest in the style sheet. It will save you time and frustration afterwards. It is difficult, and awkward to set styles using the RTF editor, but if you do it once in the stylesheet you don’t have to to it over and over again in each template. Also make sure to create your own “normal” style and call it “my normal” or something like that. Use this instead of the regular “normal”. There seems to be some weird behavior associated by the “normal” style, so I learned it’s best not to use it at all.

Then press generate, and the document generator will create one big document containing

  • The cover page
  • The table of contents page
  • All model documents in the order they appear in the project browser.

If you are not happy with the content of the document, or the order of the model documents then you can change them in EA and re-print the document.

One of the advantages is that the content of the document is stored in EA. So after a revision of the model you can print exactly the same content again and compare it with the previous version.

 Automatically generate virtual documents

Using virtual documents like that is all nice and good, but it still requires quite a lot of work to assemble the virtual document itself. For a somewhat realistic document you easily end up with tens of model documents, all pointing to different element or packages, and different template.
And you have to repeat that process for all the different documents you want to generate.

Doing the same thing over and over again is exactly what computers are build for. Instead of having to assemble the virtual document manually we will write a little script to do it for us.

The first thing well need to do is to make the Master Document package. This VBScript function does that for us.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
function addMasterDocument(packageGUID, documentName,documentVersion,documentAlias)
    dim ownerPackage as EA.Package
    set ownerPackage = Repository.GetPackageByGuid(packageGUID)
    dim masterDocumentPackage as EA.Package
    set masterDocumentPackage = ownerPackage.Packages.AddNew(documentName, "package")
    masterDocumentPackage.Update
    masterDocumentPackage.Element.Stereotype = "master document"
    masterDocumentPackage.Alias = documentAlias
    masterDocumentPackage.Version = documentVersion
    masterDocumentPackage.Update
    'link to the master template
    dim templateTag as EA.TaggedValue
    for each templateTag in masterDocumentPackage.Element.TaggedValues
        if templateTag.Name = "RTFTemplate" then
            templateTag.Value = "(model document: master template)"
            templateTag.Notes = "Default: (model document: master template)"
            templateTag.Update
            exit for
        end if
    next
    'return
    set addMasterDocument= masterDocumentPackage
end function

Then we need to make the Model Documents.To make one with a Package as source we use this function

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
function addModelDocumentForPackage(masterDocument,package,name, treepos, template)
    dim modelDocElement as EA.Element
    set modelDocElement = masterDocument.Elements.AddNew(name, "Class")
    'set the position
    modelDocElement.TreePos = treepos
    modelDocElement.StereotypeEx = "model document"
    modelDocElement.Update
    'add tagged values
    dim templateTag as EA.TaggedValue
    for each templateTag in modelDocElement.TaggedValues
        if templateTag.Name = "RTFTemplate" then
            templateTag.Value = template
            templateTag.Notes = "Default: Model Report"
            templateTag.Update
            exit for
        end if
    next
    'add attribute
    dim attribute as EA.Attribute
    set attribute = modelDocElement.Attributes.AddNew(package.Name, "Package")
    attribute.ClassifierID = package.Element.ElementID
    attribute.Update
end function

To make one with an SQL Search as source we use this function

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
function addModelDocumentWithSearch(masterDocument, template,elementName, elementGUID, treepos, searchName)
    dim modelDocElement as EA.Element;
    set modelDocElement = masterDocument.Elements.AddNew(elementName, "Class")
    'set the position
    modelDocElement.TreePos = treepos
    modelDocElement.StereotypeEx = "model document"