Automate document generation from SysML models with Rational Rhapsody ReporterPLUS

Automate document generation from SysML
models with Rational Rhapsody ReporterPLUS
Techniques for producing documents required as systems
engineering project deliverables

Skill Level: Intermediate

Rodrigo A. Batista (Rodrigo.Batista@suzlon.com)
Systems engineer
Suzlon Energy GmbH

03 May 2011

This article explains techniques to generate documents from IBM® Rational®
Rhapsody SysML models, using the Rhapsody ReporterPLUS feature. Automated
document generation from existing models enhances consistency between the
different representations of the system used throughout system development. Using
the right techniques, it is possible to produce publication-ready, human-readable
documents that support engineering processes.
Model-based systems engineering (MBSE) is widely recognized as providing an
immense improvement to traditional development methods when it comes to
complex or safety-relevant designs. Today, it is even used with document-centric
approaches to fill in the gaps inherent in those methods.

With the advent of SysML, which is an offshoot of UML specifically adapted to
systems engineering, development teams have a semantic-rich notation to build
models that illustrate very different aspects of a system under development. It
greatly assists in all sorts of analysis tasks.

SysML models contain so much information from so many different domains that it is
a logical step to use this information to generate documents when they are required
as part of the deliverables. This article focuses on using the combination of the
ReporterPLUS feature with IBM® Rational® Rhapsody, along with Microsoft Word,
to automate creation of human-readable documents from IBM Rational Rhapsody

Automate document generation from SysML models with Rational Rhapsody ReporterPLUS Trademarks
© Copyright IBM Corporation 2011 Page 1 of 11

developerWorks® ibm.com/developerWorks

SysML models.

For background information on the use of document generation, see "A Modeling
Approach to Document Generation" and "SysML models as a basis for automated
document generation," which are both cited in the Resources section of this article.

Document generation techniques in detail
Document generation from a SysML model using the Rhapsody ReporterPLUS
feature can be very straight-forward. The software already delivers some very useful
templates. Simple new templates can be created easily in a visual manner by using
the drag-and-drop method (for details, see Resources for a link to the online
documentation). But, as always, the devil lies in the detail.

Simon Morrish already provided some very good tips regarding the work with
ReporterPLUS in his presentation titled "Working with ReporterPLUS!" (see
Resources). Systems developers who want more adapted templates will need to get
acquainted with Q-Language, the underlying scripting language for ReporterPLUS
(see the official documentation). This article goes into advanced topics regarding
document generation aimed at creating more readable documents that extract the
important information from a SysML model and put this information in the correct
context.

Figure 1 shows the basic setup for document generation in the tool chain described
in this article.

Figure 1. Tool chain setup

Some of the work of document generation is performed by ReporterPLUS in the .tpl
file (ReporterPLUS template)/ This includes the whole work of information extraction
from the SysML model and some formatting of the generated document. Another
part of the work is performed by the .dot file (Microsoft Word template), which can do
most of the formatting and even some of the more advanced transformations of the
text through Visual Basic for Applications (VBA) macros. The result of this highly
configurable process is, ideally, a very readable document that is well adapted to the
needs of the target audience.

The aim of the setup that this article describes is to generate a document with these


ibm.com/developerWorks developerWorks®

characteristics:

• Customized title page with some fields providing information extracted
from the model
• Table of contents (a standard feature of ReporterPLUS that will be not
further described in this article)
• Table of figures
• Use of rich text formatting in the Rhapsody model description fields
throughout the document
• Attractive tables with adapted width and colored first row
• Suppression of model elements with specific stereotypes attached
• Documentation of model element interdependencies modeled as
allocations
• A requirements traceability table showing all applicable requirements
(only those linked to the model elements described by the document)
hyperlinked to the corresponding model element description in the
generated document.
But first the next section introduces some of the techniques used in the Rational
Rhapsody ReporterPLUS feature.

Rhapsody ReporterPLUS techniques
In Rational Rhapsody, whenever a model element is created that the user does not
intend to be part of the documentation, it needs a specific stereotype attached to it.
If, for example, the model includes simulation-related elements that will not appear in
the system documentation (because it will describe only the physical system), the
user can include a stereotype called «forSimulationOnly». In Rhapsody
ReporterPLUS, you can include this constraint (also shown in the screenshot in
Figure 2) in any loop where you want to prevent such model elements from
appearing in the final document:

$name of [stereotypes]~<> "forSimulationOnly"

Figure 2. Omitting specific stereotypes



At different places in the document, description fields extracted from the SysML
model are going to be inserted. They can have rich text formatting (RTF), which will
not be automatically translated by Microsoft Word to the corresponding formatting.
To translate this formatting code into actual bold, italics, font sizes, and other styles,
you will need to use Microsoft's Visual Basic for Applications (VBA). To this end, the
first step is to tag the RTF fields so that the VBA macros can find them later on:

1. First, proceed by locating the RTF-formatted model elements in the tree
structure for the document in ReporterPLUS. These elements are
descriptions attached to model elements that are accessible through the
«$descriptionRTF» field.

2. In the body of the document section, precede this tag with
##BeginRTF##, and then put a ##EndRTF## after the description field.

Figure 3 shows how this looks in ReporterPLUS. Enclosing the tag like this will make
it easier to find the RTF-formatted code using regular expressions in VBA.

Figure 3. Tagging RTF Heading and Body fields

In a similar way, you can indicate the place where you want to have the table of
figures by using this markup: ##InsertTOF##.

For the figure captions, you can put the name of the diagram inside
##BeginFigureCaption## and ##EndFigureCaption## tags.

According to the requirements stipulated, the resulting document shall include
hyperlinks from the requirements to the elements that they are allocated to. For that
purpose, you can use Microsoft Word bookmarks. To make these bookmarks



unique, take the GUID from the Rational Rhapsody model, which is unique inside a
model.

The GUID is a further model property that is available in ReporterPLUS. In
Q-Language, this is accessible as «$GUID». To generate the bookmark, you will
need to use the follwing code:

[BOOKMARK: name=(«$GUID»)]«$displayName» [CR]

Figure 4 shows the creation of these bookmarks in ReporterPLUS.

Figure 4. Creating bookmarks using GUIDs

In common systems engineering processes such as IBM® Harmony, T. Weilkien's
SYSMOD, or S. Friedenthal's OOSEM, functions in a model are always allocated to
physical blocks to indicate their expected behavior. In addition to this allocation
between SysML activities and blocks, you use special allocations between activities
and states, stereotyped as «validInState», to create a bridge between the
activities and the state or mode of operation where they are expected to be
performed. We show this relationship in the documentation in the form, as shown in
Figure 5 (columns for "Function Name" and "Available in States/Modes").

Figure 5. The allocation of activities to blocks and states in the generated
document

In order to achieve this, a somewhat more complex construct is required. This is the
procedure:

1. Iterate over blocks.

2. Iterate over the association "references" with this condition:
$name = $name of [dependsOn]



3. The activity name is output though:
«$displayName of [owner]»

4. Iterate over the "dependency" class with this condition:

5. $metaClass of [dependsOn] = "State" and (for_all x in
[dependsOn]->[stereotypes] =>$name of x =
"validInState")
This will look for all dependencies that have a «validInState» stereotype
and are linked to states.

6. The state name is output through:
«$displayName of [dependsOn]»

Figure 6 shows the corresponding node structure in the ReporterPLUS template.

Figure 6. Allocating activities to blocks and states, template node structure

Finally, you need to have hyperlinks from the requirements to the elements that they
are allocated to. You have already seen how the GUIDs for the different elements in
the model have been used to create the bookmarks. The hyperlinks are created by
using the following command in ReporterPLUS:

[LINK: text=("some text"), bookmark=(someBookmark)]

Now you need to iterate only over all requirements, see whether they are allocated
to model elements, and find this element's GUID:

1. Iterate over the Requirement class.

2. Iterate over class the Class class, with this condition:
<Specific Object>filter { ($name of [dependsOn] ~=
$name of this) } over all "Dependency"
Tip:



Look for all elements in the model with a dependency on this requirement.

3. Create a hyperlink using «$name of [dependent]» as the text and
«$GUID of [dependent]» as the bookmark.

Rational Rhapsody ReporterPLUS can do basic formatting in the sense of font styles
(bold, italic, underline). It can also create bookmarks and links to them. It cannot do
more advanced table formatting (width, cell colors, and so forth) to create figure and
table captions or to interpret rich text format. The section that follows, "Formatting
with Microsoft Word and VBA macros," covers, in detail, the steps required to
overcome these limitations.

Formatting with Microsoft Word and VBA macros
The Microsoft Word template will handle some reformatting of the document. To
make the process automatic, the corresponding procedures are called in the
AutoOpen() macro of the document. This is a special macro that is automatically
called upon opening the document.

1. In order to create the AutoOpen() macro, you will need to press Alt-F11 in
Microsoft Word to access the VBA environment, and then create a
module.

2. In that module, write a procedure called AutoOpen().

3. In that procedure you can enter your custom formatting code.

You can find more information on the AutoOpen() macro on the Microsoft Support
website (see Resources).

The problem with simply using AutoOpen() is that all reformatting is performed every
time that the document is opened, as opposed to only the first time. To prevent this,
define (in the template) a Boolean document property called "FormattingPerformed"
set to false. The AutoOpen() macro checks this property. If it is false, it performs all
formatting operations and then sets it to true. If the property is true, then the
formatting has already been performed and the AutoOpen() terminates.

Create figure captions

The next step is to create captions for all of the figures in the document. The macro
searches for all instances of ##BeginFigureCaption## and
##EndFigureCaption##, removes these tags, and puts the text in between these
tags in a figure caption, using the InsertCaption VBA method. This article does not
go into implementation details for these macros, please refer to the basic VBA
literature.



After the captions are created, you can let Microsoft Word generate a Table of
Figures. Look for the ##InsertTOF## tag, remove it, and at that same place in the
document, execute the following VBA code:

ActiveDocument.TablesOfFigures.Add Caption:="Figure"

Format tables

To format tables:

1. Define a new table style with shading of the first row.

2. Apply the style to each table in the document.

3. Then set the wdAutoFitContent property and change border styles to
fit the desired appearance (see Figure 5).

Next, you need to tackle the task of replacing the RTF formatting commands
included by ReporterPLUS as clear text with correctly formatted text. To achieve
this, you can use the method described in the Microsoft Help and online Support:
How to paste a Rich Text Format string into Word with Visual Basic Automation (see
Resources for a link). The method basically requires the RTF text to be explicitly
copied to the clipboard as RTF text:

lRTF = RegisterClipboardFormat("Rich Text Format")

Then you copy it from the clipboard and paste it back into the document. Because
this requires access to Microsoft Windows DLL files that are normally not directly
available for VBA macros, you will need some additional code. For details, see the
same Microsoft Support document mentioned previously.

Summary
As this article has explained, you can use the Rational Rhapsody ReporterPLUS
feature (which is highly configurable, using Q Language) and the flexibility available
for document manipulation through VBA to customize document generation from
IBM Rational Rhapsody SysML models. With these tools, you can truly suit the
needs of your target audience.



Resources
Learn
• Citations in this article:
• Jenkins, S. A Modeling Approach to Document Generation, INCOSE
Insight. December 2009, Volume 12, Issue 4.
• Batista et al. SysML models as a basis for automated document
generation. Presented by Batista, R. et al. at the INCOSE German
chapter's "Tag des Systems Engineering 2010" conference.
• Q Language section of the ReporterPLUS Guide. Official documentation.
• Morrish, S. Working with ReporterPLUS!. 2008. You can download the
PDF called "ReporterPLUS hints."
• Microsoft Support website: How to paste a Rich Text Format string into
Word with Visual Basic Automation. Retrieved 23 February 2011.
• Microsoft Support website: WD2000: Auto Macros in Word. Retrieved 23
February 2011.

• Read the Reporting with Rational Rhapsody ReporterPLUS documentation in
the Reporting section of the IBM Rational Rhapsody Information Center.
• To learn more about this tool for collaborative, model-driven development for
embedded systems, start with these overviews:
• Introduction to Rational Rhapsody
• The Rational Rhapsody Developer product page
• The Rational Rhapsody page on IBM developerWorks

• Explore the various versions, too:
• IBM® Rational® Rhapsody® Architect for Software, a visual development
environment for embedded systems and software
• IBM® Rational® Rhapsody® Architect for Systems Engineers
• IBM® Rational® Rhapsody® Designer for Systems Engineers
• IBM® Rational® Rhapsody® Developer edition. This edition is required for
Eclipse users and these editions are available to create specialized C,
C++, Java, or Ada projects.

• Visit the Rational software area on developerWorks for technical resources and
best practices for Rational Software Delivery Platform products.



• Stay current with developerWorks technical events and webcasts focused on a
variety of IBM products and IT industry topics.
• Attend a free developerWorks Live! briefing to get up-to-speed quickly on
IBM products and tools, as well as IT industry trends.
• Watch developerWorks on-demand demos, ranging from product
installation and setup demos for beginners to advanced functionality for
experienced developers.

• Improve your skills. Take the Telelogic Rhapsody ReporterPLUS web-based
training course (OQQ205), and check the Rational training and certification
catalog, which includes many types of courses on a wide range of topics. You
can take some of them anywhere, any time, and many of the "Getting Started"
ones are free.
Get products and technologies
• Download Rational Rhapsody Developer and try it free for 30 days.
• Evaluate IBM software in the way that suits you best: Download it for a trial, try
it online, use it in a cloud environment, or spend a few hours in the SOA
Sandbox learning how to implement service-oriented architecture efficiently.
Discuss
• Join the discussion in the Rational Rhapsody forum. Ask and answer questions
and increase your expertise when you get involved in the other Rational forums,
cafés, and wikis, too.
• Share your knowledge and help others who use Rational software by writing a
developerWorks article. You'll get worldwide exposure, RSS syndication, a
byline and a bio, and the benefit of professional editing and production on the
developerWorks Rational website.
• Follow Rational software on Facebook and Twitter (@ibmrational), and add your
comments and requests.
• Connect with others who share your interests by joining the developerWorks
community and responding to the developer-driven blogs.

About the author
Rodrigo A. Batista



Rodrigo A. Batista graduated from RWTH Aachen (Germany) as an
aeronautics engineer. He has been working for more than seven years
in the aerospace industry, particularly in the development of electronic
equipment. In recent years, he has been actively involved in the
deployment of systems engineering processes with emphasis in
requirements engineering and model-based systems engineering
(MBSE). Since February 2011 he has been working for Suzlon Energy
GmbH, in the wind energy sector. The work presented in this article
originated during his consultancy job at Berner & Mattner
Systemtechnik GmbH (http://www.berner-mattner.com).


Automate document generation from SysML models with Rational Rhapsody ReporterPLUS

Recommended

Recommended

More Related Content

What's hot

What's hot (15)

Similar to Automate document generation from SysML models with Rational Rhapsody ReporterPLUS

Similar to Automate document generation from SysML models with Rational Rhapsody ReporterPLUS (20)

More from Bill Duncan

More from Bill Duncan (20)

Recently uploaded

Recently uploaded (20)

Automate document generation from SysML models with Rational Rhapsody ReporterPLUS