Enhanced Reporting

with Enterprise Architect

Webinar December 2012

Questions from the Audience

Questions & Answers

Q: What version of Enterprise Architect includes the Document Fragments capability?

A: Enterprise Architect 10. (Released December, 2012)

Q: What edition of Enterprise Architect do I need (Corporate, Professional etc.)?

A: Document Fragments are available in all editions of Enterprise Architect.

Note: This demonstration also included an example of embedding a Model Script in a Document Fragment template. To create and edit Model Scripts in Enterprise Architect, you must use the Corporate (or above) edition.

Q: Regarding the use of hyperlinks to elements within a Document Fragment, how does Enterprise Architect know what the hyperlink destination is - how do I specify it? There was no reference to an element ID in your example Document Fragment template.

A: When an element is processed during document generation, a start and end bookmark is automatically inserted into the document. When you insert a hyperlink to that element, the hyperlink binds to the first matching bookmark.

Tip: If you wish to report on elements multiple times in a single document, you need to make use of the "No Bookmarks" option. Simply check the "No Bookmarks" option in all templates, except those that contain the information you want to jump to. (By default, "No Bookmarks" is unchecked.) You access the "No Bookmarks" option from the Document Template Designer by clicking the Document Options icon; the "No Bookmarks" option is listed under the first tab.

Q: Why was a Model Script used to add the time, date, document author and repository name/location?

A: These information items are not available via the built-in template editor, as they are not owned by elements in the model hierarchy. The information is stored in the Enterprise Architect repository however, and is available via the API. Since it can be useful to include such information in reports, we chose to extract it using a Model Script invoked from a Document Fragment.

In general, Document Fragments do not require you to use or develop Model Scripts - that's just a convenient option we took advantage of.

Q: What else can be passed into the script function other than Object ID? Can I use a DiagramID?

A: You can also pass a PackageID. We plan to support DiagramID as well, but this capability is not available in the current release (10.0.1004).

Q: Is it possible to call a SQL or script template that returns a single row into a table per call? The goal is to populate a table based on the set of elements that are being reported on - one element per row in the table.

A: We'll assume that the table has a heading row and that a Document Fragment defines a custom query to populate one row of the table based on the input element. For the Document Fragment to operate on each reported element, it must be invoked from within the Element section of a parent template. The table header is also defined in the parent template. In this scenario the Document Fragment will be called for each element one after another, thus filling out one row after another.

Note: When using Document Fragments in this way, the current release of Enterprise Architect generates an extra space between rows. This will be addressed in a future release of Enterprise Architect.

Q: Can SQL queries return multiple columns and display in tables?

A: Yes. To do so, include each column that will populate your table in your Custom (SQL) Query. In your Document Fragment, right-click within the Custom Section and choose the menu option: Insert Custom Field. Type the appropriate column name when prompted for the name of this field. Repeat this for every column returned by your custom SQL query.

Note: You can use the "AS" construct in your SQL query to assign an alias to each column. For example: SELECT DocName AS TemplateName, Author AS TemplateLocation FROM t_document. In that case you may use the column alias for the template field name instead.

Q: Will fragments be extended to call into an EA extension (add-in)?

A: Currently there are no plans to implement add-in support for template fragments. However, Sparx Systems would welcome feedback from users on specific needs or use cases for this capability.

Q: How did you create the headers and footers for your document?

A: Headers and Footers can be created using the built-in templates, whether as part of a Document Fragment, or generic template. To add these to your RTF template:
  1. Open the top-level or master template
  2. Right-click and choose the menu option: Edit > Edit Page Header/Footer
  3. This allows you to edit the header and footer areas. Make the necessary changes.
  4. You may want to have a different header/footer on the first page of the generated document, or delete it entirely from that page.
To do this use the option: Edit > First Page Header/Footer.

Note: To simply view the header/footer, open the template, right-click and use the menu option: View > Page Header/Footer

In our example, we edited a header and footer in the master template called "ATM Project Specification". These will override any header and footer that may be specified in Document Fragment templates.

Q: How do Document Fragments relate to Enterprise Architect's Virtual Documents (Model Documents and Master Documents)?

A: Document Fragments and Virtual Documents provide two different approaches to structuring generated reports. Document Fragments exist at the template-level to provide greater flexibility in:
  1. what information can be reported. For example Document Fragments may report information obtained from Model Scripts, SQL Queries or Element Filters.
  2. how that information is structured. For example you can use multiple fragments to report on the same set of elements multiple times.
Virtual Documents provide a visual, model-driven approach to structuring and sequencing reports. Like Document Fragments, they also allow you to aggregate templates, but operate on a predefined set of input packages. This makes Virtual Documents useful when you have a particular report, or set of reports, to execute in a given model.

Neither capability is a replacement for other - rather they are complementary. It is entirely feasible, for example, that a Virtual Document's template calls one or more Document Fragments to extract necessary information for the report.

Q: Does Sparx intend to include some scripting examples (i.e: the document properties) in the EAExample.eap file?

A: Yes. We intend to provide a library of examples that can be used for common reporting needs. This will likely be included in the Enterprise Architect Base Model, as well as being importable into existing model files/repositories.