Use Rational Publishing Engine with Rational Rhapsody
Use IBM Rational Publishing Engine with IBM Rational Rhapsody
Rajesh Singh
August 28, 2013
Page 1 of 30
“Rational Support Whitepaper”
PREPARATION FOR INTEGRATION................................................................4
...................................................................................................4
UNDERSTANDING THE COMPONENTS............................................................5
...........................................................................................5
.........................................................................................6
..............................................................................................7
........................................................................................8
............................................................................................9
...........................................................................................10
CONSTRUCTING A TEMPLATE......................................................................11
.................................................................................11
......................................................................................11
...................................................................................12
ONFIGURE THE DOCUMENT SPECIFICATION
......................................................................13
............................................................................................14
........................................................................................15
.......................................................................................16
ODIFY THE TEMPLATE TO RESTRUCTURE THE OUTPUT
...........................................................17
......................................................................................18
..................................................................................................19
EXTRACTING USE CASE DIAGRAM...............................................................21
........................................................................................22
ACCESSING THE ELEMENTS OF ACTIVITY DIAGRAM....................................25
USING THE “CAST TO TYPE” FUNCTIONALITY.............................................25
EXTRACTING INFORMATION OUT OF TWO DOMAIN SOURCES....................27
SWITCHING OFF STICKY TOOLS..................................................................27
RPE VERSUS RHAPSODY REPORTERPLUS....................................................28
MORE INFORMATION..................................................................................29
Page 2 of 30
“Rational Support Whitepaper”
Introduction
This white paper introduces the basics of using IBM Rational Publishing Engine (RPE) to extract data from IBM Rational Rhapsody. RPE helps in creating reports to represent data in a easy-to-use format. This white paper is useful for project support teams, system and software engineers, and the program and project managers.
In this white paper, you also learn to use the Rational Publishing Engine Launcher to configure documentation generation for projects. You can generate documents that integrate information from sources like schemas available with Rational Rhapsody and Rational DOORS. You can also design document templates to meet your document generation needs.
You must have an understanding on these topics:
• Basic knowledge about XML files and XML schema definitions
• Some knowledge of Rational tools like Rhapsody, DOORS, and so on
• Some knowledge of Object Oriented concepts such as inheritance and encapsulation
This white paper provides you with the knowledge to perform these activities:
• Create an RPE template for Rational Rhapsody
• Obtain a valid Rational Rhapsody schema
• Run a document specification to extract data from Rational Rhapsody
This white paper does not target information specific to tools development.
Page 3 of 30
“Rational Support Whitepaper”
Preparation for integration
To setup integration between Rational Rhapsody and Rational Publishing Engine, you must install both the products. The RPE interface installs with Rational Rhapsody internally. The basis of the interaction between RPE and Rational Rhapsody is the
REST Services and API, explained in later topics of this white paper.
Prerequisites
• IBM Rational Rhapsody V7.5.1 or above
• IBM Rational Publishing Engine V1.1 or above
• Rational License Key Server V8.1 or above o Node locked licenses are not available
• It is mandatory to have the license features shown in figure 1.1
available in the license file for the integration to work successfully.
Figure 1.1: License feature line required for Rational Publishing Engine
Note: There is a concept of licensed template. There is no RPE license requirement for using such templates.
Page 4 of 30
“Rational Support Whitepaper”
Understanding the components
This section gives an overview of different elements involved in the overall reporting aspect. It covers information on the Rational Rhapsody Schema, REST services, different functional views of the RPE Document Studio, RPE Launcher, and so on.
Rhapsody web server
The basis of the interaction between RPE and Rational Rhapsody is the REST Services and API. Rational Rhapsody provides a web server that exposes the Rhapsody model. RPE can connect to the web server by way of its URI to work with Rhapsody.
Invoke the web server command prompt window:
• In Rational Rhapsody, select the menu option Tools > Rational Publishing
Engine > Generate a report .
• You can also start the web server manually from the Rhapsody installation directory:
<Rhapsody Install>/ApplicationServer/startserver.bat
Figure 1.2: Application server window
Page 5 of 30
“Rational Support Whitepaper”
REST accessible data
Rational Rhapsody web server provides a REST (Representational State Transfer) API to Rhapsody. RPE makes HTTP requests of the REST API. The web server provides the REST API as a window to the Rhapsody model that other tools can use to get project information.
Figure 1.3: Web server window
Open a web browser and enter the address (URL) from the console window to observe the XML schema format of the Rhapsody model.
For example: < http://localhost:27463/Rational/Rhapsody/>
You can see an example of this in figure 1.4
.
Page 6 of 30
“Rational Support Whitepaper”
Figure 1.4: Rhapsody web server in browser
Rhapsody schemas
• Rational Rhapsody provides the REST based schema for data extraction.
• The schema defines the whole Rational Rhapsody model structure in the form of a browser. The model structure includes items such as the project, packages, diagrams, elements, and attributes.
• To build a template, a Rational Rhapsody schema file (.xsd) is required. This essentially tells RPE the structure of the specific Rational Rhapsody project.
• Rational Rhapsody includes schemas for UML, SysML, Autosar, and UPDM.
• The default schema is available in the Rational Rhapsody installation directory:
<Rhapsody Installation>\RPE\Schemas\Default.xsd
Page 7 of 30
“Rational Support Whitepaper”
RPE Document Studio
RPE Document Studio is a stand-alone application used for designing document templates. Document Studio provides various views and wizards that help you design templates. You can drag elements to create template contents without writing it manually.
Figure 1.7
shows the different functional views in the RPE document studio.
Figure 1.5: RPE document Studio
Page 8 of 30
“Rational Support Whitepaper”
Data source schema
Building a template requires a data source and the understanding of the model hierarchy. You can add a default data source schema from the Rational Rhapsody installation directory.
There are several ways to add a new data source schema:
• Selecting the menu option Data > Add Data Source Schema
• In the Outline Pane
• In the Data Source Schemas Pane
Figure 1.6
shows the window for adding the data source schema.
Figure 1.6: Data source Schema Wizard
Page 9 of 30
“Rational Support Whitepaper”
The RPE Launcher
The Rational Publishing Engine Launcher is used to configure documentation generation for projects. You can use RPE Launcher to define:
• Which template, or .dta file, to use
• Which Rhapsody project from which to get the actual data
• The path to store the generated report
• The URI properties
You can select the RPE Launcher perspective using the Open Perspective icon in
RPE Document Studio, as shown in figure 1.7
.
Figure 1.7: RPE Launcher Perspective
Page 10 of 30
“Rational Support Whitepaper”
Constructing a template
The steps and example in this section help you understand the working and building of a template to generate a document.
The sample Rhapsody model
You see the example template returning the packages names in the output document from the Rhapsody model. Figure 1.8
shows the sample Rhapsody model browser hierarchy.
Figure 1.8: Sample Rhapsody model
New document template
A template defines the structure of the information using elements such as paragraphs, containers, tables and figures. These elements are available in the
Palette section and can be used to build the template in the template editor in the center of the Document Studio.
Page 11 of 30
“Rational Support Whitepaper”
Use the menu option File > Save As to save a new template. In the example with figure 1.9
, the template file is test.dta
.
Figure 1.9: Naming the template
Add a data source schema
A data source schema, file format .xsd, is added to design and build the template. A data source schema wizard helps with this task. You can access the wizard using the menu option Data > Add Data Source Schema .
Figure 1.10: Data source schema wizard
Note that you can add one of the available default schemas from the Rhapsody
Installation directory.
Page 12 of 30
“Rational Support Whitepaper”
Configure the document specification
You use the RPE Launcher to define a document specification, file format .dsx, in terms of references to existing templates. The templates must be configured in the
Launcher using the Properties view with the information required to connect to an actual data source.
Using figure 1.11
as an example, you have defined Rational Rhapsody as a data source in Rational Publishing Engine. The URI is provided with the server address.
Figure 1.11: RPE Launcher window
Page 13 of 30
“Rational Support Whitepaper”
Insert a container
A container node is an iterator where you insert the query. You can insert a container from the palette to the document template.
Figure 1.12: A container in the editor
The query can be added to the container which iterates over the packages in the
Rhapsody model.
Figure 1.13: A container in the editor
Page 14 of 30
“Rational Support Whitepaper”
Insert a text element
You can insert a text element from the palette inside the recently added container present in the template content editor. It is an element that prints any string data entered by the end user.
Figure 1.14: A text element inside the container
You can also use the text element to extract the data from the Rational Rhapsody model dynamically at run time. These steps allow for getting the package name dynamically from the Rhapsody model.
1. Double click the text element to open the Set Content for Current
Element dialog
2. Expand the right attribute section
3. Select the name data item
4. Click OK
Figure 1.15: Setting a value inside the text element
Page 15 of 30
“Rational Support Whitepaper”
Generating the report
You can generate the report at times to test the designed template for the right output document. Click Generate Current Document on the tool bar.
Figure 1.16: Icon to generate document
Once report generation is complete, you see a results dialog presented with hyper links to the generated documents.
Figure 1.17: The result window
Once report generation is complete, you see a results dialog presented with hyper links to the generated documents.
Figure 1.18: The generated report
Page 16 of 30
“Rational Support Whitepaper”
Modify the template to restructure the output
All of the package names print into one long string, as shown in figure 1.18
. The
You can further modify the template to get the generated output in required format.
Adding a paragraph helps in formatting the document.
1. Select the Paragraph tool and click inside the container
2. Have the wrap the text field with a paragraph
3. Alternatively in the outline view of Document Studio, use the CTRL key to select the text nodes and drag them both onto the new paragraph container
Figure 1.19: Adding a paragraph
The restructured template helps you tidy up the generated document. Choose to the generate the document and click Yes to save the changes to the template.
Figure 1.20: Formatted output
Page 17 of 30
“Rational Support Whitepaper”
Multiple package levels
The Rhapsody model can have elements at different, nested levels, many level deep in the browser hierarchy. Figure 1.21
shows the three level nesting of the packages in the Rhapsody model:
Figure 1.21: Rhapsody model with multilevel packages
In order to generate all three packages under one package name at the first level, you can use the query in figure 1.2.2
.
Figure 1.22: Query to get package names
Page 18 of 30
“Rational Support Whitepaper”
However, you can modify the query by setting two of the properties to get all the three multi level packages shown in figure 1.23
.
Setting Recursion Level = 3
Setting Recursive Segments = 2
Figure 1.23: Setting properties for the container
Using filters
You can filter out certain information from the Rhapsody model in the generated report. You can define your own filter using JavaScript. This example removes the default referenced packages <PredefinedTypes, PredefinedTypesCPP> in the
Rhapsody model.
The default package hierarchy in a new Rhapsody model contains three packages at the project level: “Default”, “PredefinedTypes” and “PredefinedTypesCpp”. The packages “PredefinedTypes” and “PredefinedTypesCpp” comes as reference (REF).
The RPE query in figure 1.24
generates the report containing the three packages in the Rhapsody model.
Figure 1.24: Query to get package names
Page 19 of 30
“Rational Support Whitepaper”
In order to remove the referenced packages in the generated report, use the filter in the RPE template.
1. Right click the text item
2. Select Data and click Edit Condition
Figure 1.25: Invoke window to set the condition
The Set Condition for Current Element dialog opens, where you set the Java
Script filter.
Figure 1.26 : Window to set condition
Page 20 of 30
“Rational Support Whitepaper”
1. In the left operand pane, select the isReference attribute
2. Leave the Operator as “Equals”
3. In the right operand pane, type “false”
4. Click Add
Note : These filters help remove the predefined packages from the generated document.
Extracting use case diagram
This section covers the steps on extracting the Use Case diagram from a Rhapsody model. The template below shows how to extract the Use case diagram under a package in the Rhapsody model. Similarly the other diagrams such as activities and state charts at different levels in Rhapsody model can also be extracted.
1. In the RPE Document Studio, add a new container in the schema
2. Locate the Use Case Diagram node
3.
Drag the node onto the container. The context should be:
Projects/Project/Packages/Package/UseCaseDiagrams/UseCaseDiagram
4. Add a paragraph to the Use Case Diagram container.
5. Add a text item to the paragraph.
Figure 1.27: View from RPE Document Studio
6. Double click the text box and select the Data Expression tab
7. Expand Attributes to select the right context
Page 21 of 30
“Rational Support Whitepaper”
8. The number of contexts increases as the template gets larger
9. Match the right context from the available list under Attributes
Figure 1.28: Selecting the right context
10. Select “name” as the data for the context
11. Click OK
Figure 1.29: Selecting the data
Note : Generate the document to verify the correct identification of the Use Case
Diagram name .
Page 22 of 30
“Rational Support Whitepaper”
Adding diagram image
1. Add a new container to get the diagram image
2. Traverse the schema to find the node Pictures > Picture
3. Drag in the node to the new container
Figure 1.30: Adding picture node
4. Select the Image tool from the palette and click inside the picture container.
Figure 1.31: Adding a picture container
5. Double click the IMG node.
6. Select the Data Expression tab.
7. Expand the attribute section corresponding to the picture container.
8. Select path and click OK .
Page 23 of 30
“Rational Support Whitepaper”
Figure 1.39: Path to the picture
Note : The generated document now includes the Use Case diagram available under a package.
Figure 1.40: Generated Use Case Diagram
Page 24 of 30
“Rational Support Whitepaper”
Accessing the elements of activity diagram
UML activity diagrams have different types of contained elements. Such types include Actions, Object Nodes, Accept Time Event, and call behaviors.
The template in figure 1.41
helps in getting the name of all the states (elements) of the activity diagram at the package level.
Figure 1.41: Access the states of Activity diagram
Note : The Rhapsody schema defines a generic aggregation to show
"ActivityDiagram" can contain states. Hence, the state name returns all the states and contained elements of Activity diagram.
In order to get a specific element of the activity diagram, you can use the new functionality called “Cast to Type”.
Using the “Cast to Type” functionality
You can cast from a common type to a concrete type by using the CAST operator provided by RPE.
Figure 1.42: Selecting Cast to type perspective
Page 25 of 30
“Rational Support Whitepaper”
Note : RPE provides this functionality starting in V1.1.2.1.
Figure 1.43
shows how the you can cast the generic state of an activity diagram into a specific "ObjectNode" type. Similarly, you can use the state to cast for other specific types like "AcceptTimeEvent", "CallBehavior", and so on.
Figure 1.43: Casting to specific type
After casting, you can use the value from the specific node to design the template to get the "ObjectNode" of the activity diagram at the package level.
Figure 1.44: Template using cast node
Page 26 of 30
“Rational Support Whitepaper”
Extracting information out of two domain sources
You can add more than one data source with RPE for extracting information in parallel. The document specification seen in figure 1.45
has two data sources – One for Rational Rhapsody and one for DOORS.
Figure 1.45: Two data source in RPE
Here, you can further extend the template to retrieve the requirement information out of models for both Rhapsody (diagram, requirement name) and DOORS
(requirement text, priority and status).
Switching off sticky tools
From the tool bar, select Window -> Preferences
1. In the tree, select RPE > RPE Document Studio .
2. Select “No” for the option Keep current palette tool selected after insertion in template .
3. Click OK .
Page 27 of 30
“Rational Support Whitepaper”
Figure 1.46: Switch off sticky tool
RPE versus Rhapsody ReporterPLUS
Why should you consider switching to RPE?
• RPE is the current solution. There are no enhancements for Rhapsody
ReporterPLUS.
• RPE supports multiple data sources, including DOORS and any REST tool. This support enables traceability reports across data sources.
• Multiple templates can be used to generate one document
• RPE scales better with model size
• Loads only the part of the model required for generation
• Performance is vastly superior
For example - Generation speed increases as only the required part of model gets loaded. ReporterPLUS loads the complete model first.
Page 28 of 30
“Rational Support Whitepaper”
More Information
• Rational Publishing Engine Information Centers http://www.ibm.com/support/docview.wss?uid=swg27016561
• Efficient document production using Rational Publishing Engine (IBM Training) http://www.ibm.com/services/learning/ites.wss/us/en?
pageType=course_description&courseCode=QG126
• Rational Rhapsody Information Centers http://www.ibm.com/support/docview.wss?uid=swg27016562
Page 29 of 30
“Rational Support Whitepaper”
Copyrights, trademarks, and disclaimers
IBM, the IBM logo, ibm.com, and Rational are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide.
Other product and service names might be trademarks of IBM or other companies.
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROVIDED FOR
INFORMATIONAL PURPOSES ONLY. WHILE EFFORTS WERE MADE TO VERIFY THE
COMPLETENESS AND ACCURACY OF THE INFORMATION CONTAINED IN THIS
DOCUMENT, IT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED. IN ADDITION, THIS INFORMATION IS BASED ON IBM’S CURRENT
PRODUCT PLANS AND STRATEGY, WHICH ARE SUBJECT TO CHANGE BY IBM
WITHOUT NOTICE. IBM SHALL NOT BE RESPONSIBLE FOR ANY DAMAGES ARISING
OUT OF THE USE OF, OR OTHERWISE RELATED TO, THIS DOCUMENT OR ANY OTHER
DOCUMENTATION. NOTHING CONTAINED IN THIS DOCUMENT IS INTENDED TO,
NOR SHALL HAVE THE EFFECT OF, CREATING ANY WARRANTIES OR REDOCUMENTS
FROM IBM (OR ITS SUPPLIERS OR LICENSORS), OR ALTERING THE TERMS AND
CONDITIONS OF ANY AGREEMENT OR LICENSE GOVERNING THE USE OF IBM
PRODUCTS OR SOFTWARE.
© Copyright International Business Machines Corporation 2013. All rights reserved.
Page 30 of 30
“Rational Support Whitepaper”
