Automate document generation from SysML models with Rational Rhapsody ReporterPLUS

Techniques for producing documents required as systems engineering project deliverables

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.

Share:

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

author photoRodrigo 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).



03 May 2011

Also available in Chinese

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 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
Rhapsody to ReporterPLUS to Microsoft Word

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 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
Screen capture of code to omit specific stereotype

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
ReporterPLUS screen showing RTF tags

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
Screen showing how to create unique bookmarks

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
Document showing allocation of activities

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
Node hierarchy to extract states for activities

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

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

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=654294
ArticleTitle=Automate document generation from SysML models with Rational Rhapsody ReporterPLUS
publish-date=05032011