How-To

Linking external RTF documents to item notes in Enterprise Architect


Last updated on aug 5, 2004
Author: Massimo Coletti

Introduction

Enterprise Architect, by Sparx Systems, is one of the leading modeling tool for UML.

The tool allow the designer to create a number of diagrams, documenting widely each of the elements contained in those diagrams.

The tool has also many features to generate rich documentation about the whole project, or single sections or elements. One of the documents that I use widely is the Rich Text Format documentation. This document could be easily edited with Open Ofiice, Word or other popular word processing tools, and represents a good deliverable from the Architect job.

The following steps were applied to Enterprise Architect version 4.10.731, but I am confident that everything works also on previous versions.

The problem

The generated rtf document, is built up by the tool using a collection of fragments, each coming from a single element (such as views, packages, diagrams, and diagram elements such as classes objects, etc.)

The tool allow a certain degree of customisation of the template used to build the final documents.

Each element allows to enter some notes or comments, related to the single element, and those are included in the RTF document.

The following picture gives a sample:

The problem is that the narrative part associated with "important" elements, such as views or diagrams, is usually long, and the designer would like to format it appropriately, using styles, indents, lists, pictures, etc.

Many elements allow the user to link some files (eg. .doc) to them, but the content of those files is not printet nor included during document generation.

The solution

The idea that I had is to write the element-related notes in many short RTF documents; each document should be related to a single EA element (a diagram, a class, etc.).

After that, I loaded into the note field, an include instruction, according to the RTF syntax, like the following example:

For user's convenience, the instruction is reported literally here:

{\field{\*\fldinst
{\insrsid12075035 INCLUDETEXT
"M:\\\\MyDir\\\\MySubdir\\\\DocumentName.rtf"
\\c MSRTF }}
}

The place wher you should insert the document name is highlighted.

Applying this trick, when you generate the RTF document for this element, the include instruction is appended in the proper place. If you open the resulting document, you should perfom a complete field update (important):

and the content of your documents will appear mixed with the automatically generated parts.

This solution allow to write professionally-formatted notes, while mantaining an high degree of automation in the process of generating the deliverables.

Cons

There are two issues with this solution:

The latter issue should be explained. The include instruction is not interpreted by the EA tool, but by Word (or other RTF editor) when you open the generated document.

If you generate the HTML documentation, you will see, in the resulting HTML pages, your include instruction, instead of the included document. It is not nice, nor professional.

Unfortunately, if you choos this solution, you will be forced to decide one format for your generated deliverables: if you will choose RTF, ok, it works. If you will choose HTML, you will apply the same trick in some different way (eg. with IFRAME).

References

That's all, folks!


Return to mcoletti.net Home Page