Automate document generation from SysML     models with Rational Rhapsody ReporterPLUS     Techniques for producing docume...
developerWorks®                                                                      ibm.com/developerWorks     SysML mode...
ibm.com/developerWorks                                                                  developerWorks®     characteristic...
developerWorks®                                                                      ibm.com/developerWorks     At differe...
ibm.com/developerWorks                                                               developerWorks®     unique, take the ...
developerWorks®                                                                      ibm.com/developerWorks           3.  ...
ibm.com/developerWorks                                                                developerWorks®                  Loo...
developerWorks®                                                                      ibm.com/developerWorks     After the ...
ibm.com/developerWorks                                                               developerWorks®     Resources     Lea...
developerWorks®                                                                      ibm.com/developerWorks        • Stay ...
ibm.com/developerWorks                                                                developerWorks®                    R...
Upcoming SlideShare
Loading in …5
×

Automate document generation from SysML models with Rational Rhapsody ReporterPLUSl models with rational rhapsody reporterplus

1,278 views

Published on

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.

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
1,278
On SlideShare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
20
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Automate document generation from SysML models with Rational Rhapsody ReporterPLUSl models with rational rhapsody reporterplus

  1. 1. 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 RhapsodyAutomate document generation from SysML models with Rational Rhapsody ReporterPLUS Trademarks© Copyright IBM Corporation 2011 Page 1 of 11
  2. 2. 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 theseAutomate document generation from SysML models with Rational Rhapsody ReporterPLUS Trademarks© Copyright IBM Corporation 2011 Page 2 of 11
  3. 3. 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 stereotypesAutomate document generation from SysML models with Rational Rhapsody ReporterPLUS Trademarks© Copyright IBM Corporation 2011 Page 3 of 11
  4. 4. developerWorks® ibm.com/developerWorks 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 Microsofts 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 bookmarksAutomate document generation from SysML models with Rational Rhapsody ReporterPLUS Trademarks© Copyright IBM Corporation 2011 Page 4 of 11
  5. 5. ibm.com/developerWorks developerWorks® 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. Weilkiens SYSMOD, or S. Friedenthals 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]Automate document generation from SysML models with Rational Rhapsody ReporterPLUS Trademarks© Copyright IBM Corporation 2011 Page 5 of 11
  6. 6. developerWorks® ibm.com/developerWorks 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 elements 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:Automate document generation from SysML models with Rational Rhapsody ReporterPLUS Trademarks© Copyright IBM Corporation 2011 Page 6 of 11
  7. 7. ibm.com/developerWorks developerWorks® 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.Automate document generation from SysML models with Rational Rhapsody ReporterPLUS Trademarks© Copyright IBM Corporation 2011 Page 7 of 11
  8. 8. developerWorks® ibm.com/developerWorks 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.Automate document generation from SysML models with Rational Rhapsody ReporterPLUS Trademarks© Copyright IBM Corporation 2011 Page 8 of 11
  9. 9. ibm.com/developerWorks developerWorks® 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 chapters "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.Automate document generation from SysML models with Rational Rhapsody ReporterPLUS Trademarks© Copyright IBM Corporation 2011 Page 9 of 11
  10. 10. developerWorks® ibm.com/developerWorks • 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. Youll 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. BatistaAutomate document generation from SysML models with Rational Rhapsody ReporterPLUS Trademarks© Copyright IBM Corporation 2011 Page 10 of 11
  11. 11. ibm.com/developerWorks developerWorks® 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 Trademarks© Copyright IBM Corporation 2011 Page 11 of 11

×