One feature of the UML diagram in Visio is the ability to create professional reports of the detail contained in your drawings. These reports can be shared with the development team and added to any change control policy your organization or project may have in place. Visio UML ships with support for creating reports for static structure (class diagrams), activity, statechart, component, and deployment diagrams. In this section, we'll review the creation of Visio UML reports and discuss the reports you may commonly want to include in your own project work.
Each of the reports contains a listing of the contents of the report and quite a bit of detail about each of the
within whichever diagram the report is run for. For instance, an activity diagram report will include each action state and each transition from one state to another. It will also include most of the important UML-
information included in the Visio shape properties.
To get started, let's use the sample UML diagram that ships with Visio Enterprise Architect -
This is a fictional application design for referee certification. To
the sample UML model, start Visio and select
File New Browse Sample Drawings.
You'll see an
dialog like the screenshot overleaf. Select
and press the
This is actually a great sample UML model to review. It contains most of the common UML diagrams that you are likely to encounter. I
wouldn't have spent the time to format colors and shading, but
, this is a good UML example to use as guidance for your own diagrams.
Notice the tab bar at the bottom of the drawing page. If you scroll through the available drawings, you'll find
Let's create a report and discuss its contents. We'll start with the
Static Structure Report.
From the Visio
menu, find the
menu and select
and you'll see this dialog:
Notice the list of available reports. We are going to run the
Static Structure Report
, but let's take a moment to review what options are available in this dialog first. Toward the bottom of the dialog, we see
the report. Printing and previewing reports have obvious benefit, but if we are using our UML reports as a part of a development project, we probably want the information contained in these reports for some historical or change control purpose. For that reason, exporting the reports is a good thing to review. Visio will export our report to Rich Text Format, (RTF). RTF can be read by just about any word processor. The main benefit of exporting your reports is the creation of a file that you can save, include in a change control package, or even add to your source code
application like SourceSafe.
We'll get to exporting a report shortly; let's finish with the other tabs in this dialog. Click on the
tab and you see a form that lets you modify the default
of the report.
title textbox you can add text to be printed at the top of your reports. Changes will be displayed in the
textbox near the middle of the form. You can also insert common fields like
Document Title, Current Date, File
Put your cursor somewhere in the
box and press the
button. From the list that appears, select
. Depending on where you had the cursor in the
box, your display will look something like the following:
button will reset whatever changes you made to the report title and subtitle to the original settings. Another option that is
is the ability to assign the starting page number of the report. If our report is to be included with other documentation, a project
document for instance, then we might to start our page numbering well after page one. The
button opens the standard
dialog you'd expect to find in any Windows application.
page lets you select what items are to be included in the report itself. These include:
Code Generation -
the target language and code template you've selected in the diagram.
any constraints you've identified within the drawing
a standard tagged value that most Visio drawing shapes and all UML shapes contain.
Tagged Values -
-defined values contained in each shape's properties within the Visio diagram.
If your diagrams contain a lot of detail stored within the shapes
, then turning on all of these options is probably a good idea. If you are not generating code from your diagrams, that option obviously isn't necessary. It will just clutter up the report.
Static Structure Diagram Report
OK, let's generate a Static Structure diagram. Still in the
file, from the menu select
In the dialog that appears select
, and press the
button. You'll see a
dialog so browse to a directory on your machine and name the report file
Static Structure Report.
Notice that our only option is to create an RTF file. Press the
button. The report is generated very quickly. Browse to the directory that contains the new file and open it with a word-processing application. In our case, we're using Microsoft Word. WordPerfect or even WordPad that ships with Windows will work too.
The report itself is very long - over 40 pages in Word. It contains all of the detail that is available from the Visio diagram about the
diagram. Although we won't run through each of the sections of the report in too much detail, let's review a couple of major sections.
The first section of the report is a summary of the diagram. It contains the name of the diagram, the model type (in this case
), it's visibility, and the packages it contains, among other things. The
section is a statistical review of the contents of the diagram. It counts interfaces, classes, the total number of attributes, parameters, etc. It's a lengthy list and I
how useful it really is. Other than
, do we care how many
we have in our entire diagram? In most cases, probably not.
The balance of the report is a lot of detail about the packages and classes contained within the diagram. In this sample
diagram there is only the standard
and it contains all of the classes in the diagram. In Word the header of the Package section looks like this:
Each class within the diagram has its own section as well. The details in these class detail sections are probably the most useful in terms of documentation. Here's what the
class looks like in the report:
of the class are listed with a large amount of detail for each attribute including
information. Also, notice the
section of the
detail. In this diagram the diagram author chose C++ and the default code template. The
of the class follow its
That section if formatted similarly, as the following screenshot illustrates:
Each operation is listed with a tremendous amount of detail about the operation, its scope, and all of the input and output parameters. You can see why these reports can get so long - there's a lot of information included for even the most simple of attributes and operations. One nice feature about the
section if you've included
detail in the report is information about the code that was generated. Specifically, where the code file is and what language was used to generate the code.
The last portion of the class detail in this report is information that describes the associations our class has with other classes. This information is probably the second most useful data contained within the report, behind details about attributes and operations. We won't review the meaning of
and associations in a UML context, but here's what the report
use about the
class in this particular
Deployment Diagram Report
diagram report, another useful report is the
diagram report. It includes a detailed listing of Nodes and Components contained within the
diagram. In the case of our
UML example, the diagram is rather simple so the report is much smaller than our previous example. It's only three pages. The diagram itself contains two
The report itself is
compact (I wonder about the pages and pages of detail in the
report and how much it will get used). The report contains details about the
just like our
report. Then, each node (
) has its own sections of the report.
The deployment report can easily be created and distributed to development, support, and implementation groups. Given the lack of overwhelming detail that we found in the
report, we can expect team
in these other groups to use and understand the contents of this report, making it much more
throughout the entire project lifecycle.
The last report we'll look at in this section is the
It is very closely related to the Deployment report, but provides us with a bit more information about our components and their relationships to one another.
UML example the Component diagram looks like this:
Like the Deployment diagram, it is simple and easy to understand. We can therefore expect the report to be simple and easy to understand. The information that a Component diagram, and hence its report, contains that we don't find in a Deployment diagram is dependency or relationships with other components. The diagram shows those dependencies as dashed lines. In the report, we see those dependencies as sub sections, as the following screenshot illustrates:
In this report, we see that the component named
is dependent upon the component named
If the diagram included Node information for the
component, that detail would also be displayed. It is probably reasonable to expect
diagrams and their reports to be used together.