Generate document structured according to element relationship tree?

[kents]

Hi all,

I need to generate a document that is structured according to the links between elements in my model, not according to the package hierarchy. Is this possible using EA's built in document report generator?

Here is the scenario in more detail. I have an EA model that contains elements of types "feature", "requirements" and "test cases". These are linked to each other in a tree structure: at the root of the tree is a feature; this feature is linked to lower level features, which can in turn be linked to lower level features (and so on to an arbitrary depth); each feature element in the tree may also be linked to zero, one or more "requirement" elements; the leaf feature elements are linked to one or more "requirement" elements; each requirement element is linked to zero, one or more "test case" elements. The elements in this tree are spread over many different packages in the model. I need to generate a test plan document containing information taken from the test case elements, and the section hierarchy in the document must correspond to the feature hierarchy in my model.

If EA's built in document report generator cannot do this, does anyone know of a third party tool that can? Or is it going to be a case of writing my own script to do it?

Thanks in advance for any help you can give me.

[qwerty]

I'm an alien in this area. Maybe there's a way with EA's doc feature or eaDocX is something to help out. So what I did is to use the automation to create a LaTeX document and create PDFs from that. Works a charm. Unfortunately, once I loosen the grip people start jelling for Word documents (just to break off hell and demand changes in unreadable Word revision histories to be reflected in the model which in the meantime has developed and you can't get it in synch). Sigh.

q.

[Sunshine]

As far as I know the only way to get that nesting using the built in doc gen is to structure your model that way. So a feature contained a requirement etc. If that's not how your want to structure your model the other options are;

a) To write some specialized SQL query along with some reporting. So if you are using eap files as your repository which is basically MS Access you can try writing MS Access SQL and using those in a MS Access Report. Or similarly if you are using MS SQL you can use SQL Server reporting services.  I'm sure there will be options for the other database supported too.

b) I've once seen someone do is by leveraging the built-in scripting and use jscript to create a rtf file. I think they did come a cropper when there was a cyclic set of relationships in the model and ended up  with infinite loop blowing the thing up.

[qwerty]

Re b) detecting a cycle is very easy be remembering the visited elements.

q.

[PeterHeintz]

I would try to proceed as follows.

Create a template fragment for your feature elements (root of the tree = root of the document) ensuring that the feature name becomes a headline (what you seem to need)

Include a custom section in that template to call a custom script returning your test cases by hopping over the requirements. (I am not absolutely sure if there is a way to provide the identification of the current processed feature to the script)

Make this template fragment above selectable with a template selector fragment

Write a document template that ignores your packages but calls the template selector which fires to feature elements only.

Go to the package containing all you feature, to create the document

Another possibility would be, doing that outside of EA by SQL Queries and reporting featured provided by MS Access or something even better. (in fact a) from Sunshine).

[Uffe]

Hi Kent,


Just a couple pointers.

There are two options you may not have considered: model documents and the specification manager. Whether they'll be of much use in your scenario I couldn't say.

You can do a fair bit with template fragments, and also the element filters within the templates, but if you want complete control over the document generation process control flow you're going to have to script it.

Depending on your familiarity with the document generation facility in general, it may be less effort to write a script where you control everything than to construct a complex set of templates to achieve the same result.

But I'd hold off on any decision until the undisputed master of document generation weighs in: Geert Bellekens. I assume he's at the User Group meeting in Brussels today.


/Uffe

[Geert Bellekens]

Uffe, you're too kind.

I was indeed at the EA User Group event in Brussels today, and it just so happens that I did a training yesterday on the first day about "Advanced document generation using the standard RTF templates".

The way I do this type of thing is basically :
- Lots of small manageable templates and fragment (mainly SQL, and if need be script fragments)
- Virtual document to glue all the parts together
- Create the virtual document with a script.

Basically the script is the only thing that has to know how to build the document structure based on a starting point (diagram, element, package,...)

More info and a working EA example can be found here: https://bellekens.com/2015/11/12/tutorial-generate-complex-documents-from-enterprise-architect-with-a-two-step-semi-automated-approach/

Geert

[kents]

qwerty, Sunshine, Peter, Uffe and Geert - thank you all for your suggestions.

It looks as though the solution has to involve scripting, because I need to walk a tree of linked elements.

Geert, I will certainly have a good look at your tutorial and example. At first glance it looks as though that approach, but using a script instead of SQL so that I can get the elements recursively, might well be the best.

Thanks again, everyone,

kents

[Sunshine]

Upon reflection of the suggestions from various people in previous posts I think if I had the problem I'd use fragment template with a custom script to navigate the relationships. I must admit I'd forgotten about fragment templates with scripts in my original suggestion.

Wonderful sharing ideas in the community to get a better outcomes isn't it? Thats what I love about this community - great people sharing their thoughts and ideas.

[Dermot]

If it is of any use to you, there is some very old VB 6 script covering a recursive parse of the heirarchy for requirements. This report gives a basic text form of the Traceability view. For a look at the tree it produced see:
http://www.sparxsystems.com/bin/FormalRequirements.pdf
For the VB code see (hopefully usefull as starter for a scripted RTF report) - see in RequirementMain.bas the routine DumpHierarchy():
http://www.sparxsystems.com/resources/developers/autint_vb_download.html
This might help as a starter for calling  templates to report this in the using the Document Automation.

[kents]

Thanks for your further input Sunshine and Dermot.

In fact it turns out that I don't need to use scripts within EA at all, as I have now found a relatively simple solution to my problem: RepoDoc, from Archimetes (http://www.archimetes.com). Essentially, with RepoDoc you prepare a template in the liquid template language, using a plain text editor. When I first looked at RepoDoc, it had the liquid feature that supports recursion disabled, but when I explained my problem to Jan at Archimetes, he very quickly produced a development version of RepoDoc  and a template that did what I needed in terms of following links from one model element to another to an arbitrary depth. The template was 70 lines long in total. That development version of RepoDoc has now been formally released. I have found the liquid template language easy to learn, but powerful.

This solution won't necessarily be for everyone, because it doesn't support generating Microsoft Word documents. But with the addition of easily available (and free) post-processing tools, RepoDoc can produce good looking documents in pdf format, which is what I want (because I don't agree with providing customer-facing documentation as Microsoft Word documents.)

Disclaimer: I have no connection with Archimetes other than as a (soon to be) customer. I'm just posting what I have found in case it is useful to others.

Thanks, everyone.

[PeterHeintz]

Thank you for sharing that information!

[Jan Prochaska]

FYI - We have recently released a new version of RepoDoc that offers seamless export to Word, HTML or PDF. The version is available on https://repodoc.archimetes.com