Author Topic: Is there any solution for Docs Generator (RTF)?  (Read 33759 times)

raphael.abreu

  • EA Novice
  • *
  • Posts: 6
  • Karma: +0/-0
    • View Profile
Is there any solution for Docs Generator (RTF)?
« on: March 07, 2015, 12:32:12 pm »
Dear EA users,

I am big fan of Enterprise Architect, and recently took a front to automate some documents using templates, specifically for document use cases, test reports, user interface description, among others.

As a programmer, I come from a previous experience with Jasper iReport and SAP Crystal Reports, which are excellent tools for reporting (document templates).

I come through this post, explain some difficulties I got working with EA document templates (which is not yet finalized):

1) There is no conditional statements to hide custom fields or even table headers?
2) How do I show or hide a template fragment given a certain condition?

My first mission is to finalize a use case document containing the following sections:

1) Revision History
2) Table of contents
3) UC Description
4) Actors
5) Pre-conditions
6) Event Flow (scenarios)
   6.1) Alternate Flows
   6.2) Exception Flows
7) Post-conditions
8) Extension points
9) User Interface Description (user form details)
10) References


So far so good, I did everything with some difficulty using the assistance of more than 500 lines of JScript code (to fulfill my document model). The EA report template designer is too limited at this point.

What is just missing, is to get the user interface information that are the forms that the user sees in accordance with the use case description (like user registration form to user registration use case description).

Here:


These forms have been created within an element of type "Screen" that is proposed by the user interface diagram (extended model in EA).

Here:




I can see the connector within the element (realization relationship), but how to bring all the elements (form fields of the screen element) for the document to be generated in this way? Ok, I will need to use a template fragment, but I cant use table headers and conditional statements to bring the fields to the example above..

Thank you all!  :D
« Last Edit: March 07, 2015, 12:52:26 pm by aelkz »

raphael.abreu

  • EA Novice
  • *
  • Posts: 6
  • Karma: +0/-0
    • View Profile
Re: Is there any solution for Docs Generator (RTF)
« Reply #1 on: March 07, 2015, 12:49:56 pm »
The use case model description that I use at work, has some peculiarities..
For instance, I did also, a great transformation of Scenario.Step.Uses field from this:



to this (after report generation):



This was made using JScript and the result was better than I expected.
« Last Edit: March 07, 2015, 01:13:48 pm by aelkz »

raphael.abreu

  • EA Novice
  • *
  • Posts: 6
  • Karma: +0/-0
    • View Profile
Re: Is there any solution for Docs Generator (RTF)
« Reply #2 on: March 08, 2015, 01:19:44 am »
nevermind. I`ve already solved.  ;D ;D ;D

Graham_Moir

  • EA User
  • **
  • Posts: 749
  • Karma: +10/-15
    • View Profile
Re: Is there any solution for Docs Generator (RTF)
« Reply #3 on: March 11, 2015, 09:47:28 pm »
Can you post the solution for everyone else to see?


Pawel Zubkiewicz

  • EA User
  • **
  • Posts: 78
  • Karma: +2/-1
    • View Profile
    • zubkiewicz.com
Re: Is there any solution for Docs Generator (RTF)
« Reply #4 on: September 22, 2015, 07:44:17 pm »
I would also like to see your JScript code. I have similar problems with template engine.

Could you please post your solution here?
Enhanced Requirement Attributes Addin for Enterprise Architect (ERA Addin) - http://zubkiewicz.com/?p=239

raphael.abreu

  • EA Novice
  • *
  • Posts: 6
  • Karma: +0/-0
    • View Profile
Re: Is there any solution for Docs Generator (RTF)
« Reply #5 on: September 23, 2015, 03:23:20 am »
Dear EA users,

Since the beginning of this post, I experienced extreme difficulties with the RTF reporting tool of Enterprise Architect.

After a lot of heartache and effort in getting a "standard" work with my team, I managed to reach the following conclusion: Do not use the built-in report generator.

Instead, use the EA Java API to build an interface/engine for reading the .EAP (repository) file for building custom reports with Jasper Reports (and iReport designer)

I am saying this because today my team is already working with my solutions embedded in EA, but our needs began to evolve and there are no conditions to be fulfilled by the built-in report generator.

Currently I can generate the following documents (with EA built-in report designer):
- Use Case Document (with full specs linked to business rules, user interface, extension points, actors, .etc)
- User Document Interface (linked to the Use Case document, works like a UI desciptor with all fields and specific rules for presentation)
- Business Rules Document (linked to the Use Case document)
All documents based on RUP to a software factory project team.

I do not consider posting the solution here because I had a lot of work, to the point of being able to encapsulate all in one API in JScript/VBScript and report templates - which in total exceeded 5.000 lines of source code.

Consider my opinion to solve using other reporting tool like Jasper Reports in support of the EA Java provided API (eaapi.jar and SSJavaCOM.dll). Use as a starting point the Mogwai project (http://mogwai.sourceforge.net/eareport.html) which has a prepared solution to make this work along with Jasper Reports only. This solution allows even export all EA diagrams (which makes this completely plausible and functional for development teams and excellent for huge projects: 20+ members).

Regards.  ;)
« Last Edit: September 23, 2015, 06:23:36 am by aelkz »

Geert Bellekens

  • EA Guru
  • *****
  • Posts: 13287
  • Karma: +557/-33
  • Make EA work for YOU!
    • View Profile
    • Enterprise Architect Consultant and Value Added Reseller
Re: Is there any solution for Docs Generator (RTF)
« Reply #6 on: September 23, 2015, 03:46:11 pm »
Raphael,

I have to disagree.
Recently I've been doing a lot of document generation using the standard built-in RTF document generator and I must say that there has been nothing that I couldn't do.

Agreed, you have to know EA, know the API and know the database, but if there is something you couldn't do using the standard RTF generator then it is probably because of a lack of EA knowledge rather then a problem with the RTF docgen.

The "trick" is to use virtual documents, containing small document sections and not to try and fit everything into one big template.

If constructing the virtual document seems too much work then you can always automate that part with a script (which I did).

I've made custom document generators in the past, but I cannot justify that anymore with the improvements to the RTF document generation int he last few years.

I dare you to show me a document requirement that cannot be achieved with the standard document generator!

Sometimes it pays off to get the help of EA consultant before venturing into a custom-build adventure.

Geert

Graham_Moir

  • EA User
  • **
  • Posts: 749
  • Karma: +10/-15
    • View Profile
Re: Is there any solution for Docs Generator (RTF)
« Reply #7 on: September 24, 2015, 06:39:14 pm »
Thanks Geert.  It's good to hear that you haven't found situations where the RTF/Doc generator doesn't meet your needs.  

But does that mean you could give us guidance on how to solve Raphael's original requirements via the generator, namely

1) There is no conditional statements to hide custom fields or even table headers?
2) How do I show or hide a template fragment given a certain condition?

Geert Bellekens

  • EA Guru
  • *****
  • Posts: 13287
  • Karma: +557/-33
  • Make EA work for YOU!
    • View Profile
    • Enterprise Architect Consultant and Value Added Reseller
Re: Is there any solution for Docs Generator (RTF)
« Reply #8 on: September 24, 2015, 07:50:09 pm »
Hi Graham,

I can't do things that are not supported by EA (apart from sending in a feature request), but there are usually other ways to achieve the actual requirement.

both requirements quoted are more of a "solution" then they are "requirements".

Sometimes you can solve it by creating different templates (one with and one without the specific field or table)

Sometimes it can help to isolate that part in its own template and (if needed) give it its own model document.

Sometimes you have to convince the client that his requirement is rubbish and not worth implementing ;)

This being said, I'm not saying that there isn't room for improvement. There are a lot of things that are either difficult, akward, or almost impossible with the document generator.
So by all means keep sending feature requests to Sparx to get them to continue improving the document generator.

Geert

raphael.abreu

  • EA Novice
  • *
  • Posts: 6
  • Karma: +0/-0
    • View Profile
Re: Is there any solution for Docs Generator (RTF)
« Reply #9 on: September 25, 2015, 12:12:07 am »
I'm being realistic friends.

What I have demonstrated here is just the top of the iceberg. For those who have worked with document generation, custom reports, implement such solutions in the built-in editor, makes the work quite costly or impossible for the following reasons:

1) Too much overhead for creating simple solutions: No grouping of elements, sort records from a list/collection, sub-reports loop, conditional statements, hide fields/labels, labels and fragments with specific rules, support for styles and conditional styles, etc. .; You must write source-code for some cases.

2) Lack of functionality to create custom graphics. For example: Pie, Bar, Line, Scatter and multiple-series charts.

3) Lack of functionality for creating design elements. For example, lines, arrows, boxes/frames, and rectangles (elements present in simple reports).

2) The tool provides a tied way to build custom reports: You will be required to create an absurd amount of fragments or create a virtual document (which is also a complex solution);

3) The use of JScript, JavaScript and VBScript makes the development of these reports to KEEP and EVOLVE with too much effort. Especially because you will have problems to run them because not every machine supports scripting execution and ActiveX by default - trust me;

4) The runtime generation can also be a problem if you have the need to generate a lot of documents: you will have to wait 1 minute for each document to be generated by the amount of logic processing algorithms implemented.

5) Documentation and tutorials: The material is too poor. You can search on google someone who has performed complex reports in EA: you will not find!

Geert in analysis of your responses:

"both requirements quoted are more of a" solution "then They are" requirements ""
> This is a feature that both the Jasper Reports and Crystal Reports use (widely known tools) so I do not see as a solution but as a characteristic of a report generator tool: it is a common need.

"Sometimes you can solve it by creating different templates (one with and one without the specific field or table)"
YES! In my solution I needed to create about 20 fragments to generate only one section! This is ridiculous! In other tools I can do the same thing using only 2 report fragments.
Assuming you need a sub-report that has 10 fields: If each field has to be hidden by a specific rule, you will have to create 10 sub reports. But if other rules than these apply, you will have N x 9 x 8 x 7 x 6 ... templates for creation.
In other tools I create just one template and apply the necessary rule in each field, reducing my efforts and the amount of used templates: reuse.

"Sometimes you have to convince the client that his requirement is rubbish and not worth implementing"
Does not apply to my scenario: All the models used are in accordance with the RUP templates proposed by a common software factory. I do not even entered the scope of customer needs, as this is an entirely different and an even greater demand scenario.

Folks, this is why I came to the conclusion described above. Why reinvent the wheel if the market already has more robust solutions to meet the conditions above? Why delegate this work to a professional to make it to the point of writing specific solutions and maintain a huge load of nearly identical templates to meet basic requirements.

The RFT generator works basically like a text-extractor not a reporting tool.
I really like the EA for everything else, but failed to convince me after six months of use to work with document generation.

« Last Edit: September 25, 2015, 12:13:52 am by aelkz »

Guillaume

  • EA Practitioner
  • ***
  • Posts: 1357
  • Karma: +42/-2
    • View Profile
    • www.umlchannel.com
Re: Is there any solution for Docs Generator (RTF)
« Reply #10 on: September 25, 2015, 06:12:39 pm »
IMHO there isn't any ideal solution to generate documents from EA i.e. in almost all cases you have to spend quite a lot of time to achieve what you want. However it is much more efficient to generate a doc from EA compared with a manual doc where you copy and paste diagrams, content, etc.
 
Depending on the amount of efforts and time you've spent, you can eventually achieve what you were looking for, perhaps following a couple of tradeoffs.

The available options are:
- EA RTF generator: it works but it's not an ideal solution as you have to define a lot of templates and model documents, hence maintenance can be an issue over time. I also had an issue for a number of customers where we couldn't use their Company's Word template. It is a suitable solution for a lot of EA users, but it tends to be limited or over-complicated I think.
- eaDocX : has the advantage to work directly in Word (hence you can use a Word template and Styles), lets you define the content with a fairly good amount of options (select a package, diagram, use model views, etc), and profiles for the rendering. Overall it works well and saves you time compared with EA RTF, although I think there can be cases where you cannot get exactly what you need. It also provides various other interesting features (like the document management for roles, versions, etc.)
- Mogwai : I used this a couple of years ago, having tweaked the Java code. The interesting approach with this is that it generates a pivot XML File, so you can literally put anything you want in a Word doc. This is achieved via XPath queries that you define and call from Word Control zones. 2 major issues I found with Mogwai: it takes ages to generate the diagrams and XML pivot file each time you've changed your models (up to 30 minutes or more!), and it started to break when I had to use multiple embedded Word content control elements in a template. Final issue was that you had to be quite technical to use it (Xpath queries tested in XML spy on the XML pivot file..).
- Custom solutions: I met a number of people who created their own custom doc generators This can be suitable when a company doesn't find any easy way to achieve something specific, although it is a bit of a shame to think there are numerous doc generators out there, some of which are probably really good, which are only used for a single company.

Then anyone's free to decide which way to go.

« Last Edit: September 25, 2015, 06:16:18 pm by gfuk »
Guillaume

Blog: www.umlchannel.com | Free utilities addin: www.eautils.com


Geert Bellekens

  • EA Guru
  • *****
  • Posts: 13287
  • Karma: +557/-33
  • Make EA work for YOU!
    • View Profile
    • Enterprise Architect Consultant and Value Added Reseller
Re: Is there any solution for Docs Generator (RTF)
« Reply #11 on: September 25, 2015, 06:19:11 pm »
Nice summary Guillaume, might be worth to write a blog post about it.

I've done/used all of the options except for Mogwai.

I still like my own custom document generators (yes multiple ::)) best, but with the current state of the RTF generator I cannot in good fate defend a custom build solution anymore.
Too bad, because custom generators are usually much faster and provide the most flexibility of all options (and I like writing my own tools  ;D).

Geert

Ian Mitchell

  • EA User
  • **
  • Posts: 506
  • Karma: +22/-4
  • The eaDocX and Model Expert guy
    • View Profile
Re: Is there any solution for Docs Generator (RTF)
« Reply #12 on: October 01, 2015, 07:53:52 am »
Ok, so a few people have suggested that I make a comment on this one.
Declaration of Interest: I'm the author of eaDocX, a competitor to the RTF generator, but I'm also a Sparx partner, so I'm treading a fine line here between what I want to write, and what won't get me into trouble with HQ.

Much of the comment above concerns how much, and what type of code you need to write in order to get a document you can be proud of.
I reject the idea that EA users should have to write any code at all in order to get great documents. There are lots and lots and lots of EA users who don't write code. And don't have access, any more, to people who can write code for them. They are business analysts and process modellers and even actual Enterprise Architects, and they just don't write code.
So any document creation mechanism which relies, even in a small way, on writing code, or even requiring understanding of the increasingly complex EA internal data model, just is not fit for purpose. When these people are told they need to write code to make a document, they go straight back to Visio and Word, and those tools are the completion here.
It's why I wrote eaDocX. So you don't need to code documents any more. You choose what to print, and how you want it to look. So the silent, non-coding majority of EA users can just keep thinking and modelling.
And I can sense I'm in trouble with HQ already.....
Ian Mitchell, Designer, eaDocX


www.eaDocX.com
www.theartfulmodeller.com

qwerty

  • EA Guru
  • *****
  • Posts: 13584
  • Karma: +396/-301
  • I'm no guru at all
    • View Profile
Re: Is there any solution for Docs Generator (RTF)
« Reply #13 on: October 01, 2015, 08:21:18 am »
I know I'm just one of those Gauls standing against R.T.F. Caesar but where there are others it's quite fun to use the miracle drink called LaTeX. Once you took a sip of that it simply blasts those Roman Text Forces away. I know we are few but we stand fast 8-)

q.

RoyC

  • EA Administrator
  • EA Practitioner
  • *****
  • Posts: 1297
  • Karma: +21/-4
  • Read The Help!
    • View Profile
Re: Is there any solution for Docs Generator (RTF)
« Reply #14 on: October 01, 2015, 09:03:37 am »
And there was I thinking you fell into a cauldron of LaTeX when you were a baby. You can stop hiding now and declare yourself openly as qwertix.
« Last Edit: October 01, 2015, 09:04:24 am by RoyC »
Best Regards, Roy