Generate design work products from models

How to use BIRT reports with Rational Software Architect

Outdated design work products are a big challenge in development and maintenance phase. This article shows how we can generate design work products from IBM® Rational® Software Architect design models by using Eclipse provided Business Intelligence and Reporting Tools (BIRT). This allows the modeling team to focus more on designing the models rather than producing the work products. The generation of work products is as easy as clicking a button, once the BIRT report has been authored.

Shashi B. Pahwa (shashipahwa@in.ibm.com), IT Architect, I.B.M.

author photoShashi Pahwa is Sun Certified J2EE Architect with 11 years of experience using IBM Rational Software Architect, UML 2, BIRT, plugin development. He works in Global Business Services, Gurgaon as public sector application architect. He holds a Master of Computer Science degree from Maharishi Dayanand University, Rohtak India.



Shishir Narain (nshishir@in.ibm.com), IT Architect, IBM

Shishir Narain photoShishir Narain is Open Group certified Master IT Specialist with mature skills in IBM middleware products. He works in IBM Lab Services for WebSphere at India Software Labs, Gurgaon. He has 14 years of experience developing solutions for multiple clients. He has a Master of Technology degree from Indian Institute of Technology, Kanpur.


developerWorks Contributing author
        level

01 November 2011

Many organizations are realizing the prime importance of design and modeling in application development. These design models serve as a shared vision of an application for both the business and development teams. The design models are also amenable to code generation of all boiler plate code, thus allowing rapid development.

Although these models accurately capture aspects of the design, they lack descriptions that are found in typical design artifact work products. To help make these work products comprehensive, designers must manually prepare them by copying from design tools and adding explanations. This is effort intensive and also any change in design forces the designers to manually author the work product again.

In this tutorial, we will show you how to dynamically generate design artifacts from IBM® Rational ® Software Architect models by using BIRT reports. Business Intelligence and Reporting Tools (BIRT) is an Eclipse-based open source reporting system for web applications, especially those based on Java and Java Enterprise Edition (Java EE). Rational Software Architect includes BIRT, which offers capabilities to help you produce a report that includes selected contents of UML models.

By using reports to dynamically generate design documents, you can keep the model and design artifacts in synch without any extra effort.

Prerequisites

  • Rational Software Architect 7.5.5
  • A good understanding of UML models and BIRT
  • Knowledge of XML or XPath

The sample project, model and report are for illustrative purposes and to aid comprehension of BIRT reports generation from Rational Software Architect. The sample project and model are not technically accurate.

The tutorial covers only the important concepts of BIRT reports and how you can use them for UML models.

Sample project

The sample project describes a fictional website akin to IBM developerWorks, which is a professional network and technical resource center where authors can submit articles. The articles are reviewed for technical accuracy and content standards of the site. The articles are tagged under different topics by authors and reviewers. The website subscribers can view the articles and filter them by topics.

To view the project dwSubscriptions, import the archive to Rational Software Architect. Figure 1 represents the sample project model:

Figure 1. Design model for the project
Model of the project that shows various views of the design

The sample project model contains the following parts:

Activity diagram
A diagram that describes the flow of events of a use case and what needs to be done by the system to provide value to an actor. It consists of a sequence of tasks that together produce something for the actor. The flow of events consists of a basic flow, and one or several alternative flows.
 
Component diagram
This diagram describes usage relationships that exist between the various deployment units. Its purpose is to show the dependencies that the software has on the other software components in the system, such as software libraries.
 
Domain model
This model describes various entities, their attributes and relationships. It also describes the constraints that govern the integrity of the model elements that comprise the problem domain.
 
Interaction diagram
This diagram represents the internal behavior of the system. It shows how objects collaborate by sending messages and returning responses to each other.
 
State chart diagram
This diagram represents the behavior or life cycle of a single class. It is a projection of all interaction diagrams for a single class. It describes the following behaviors:
  • States that might be attained.
  • External stimuli (events, messages, responses) that cause a change in state.

Sample design output

The file SampleDesignArtifact.pdf in the archive is a sample of the output that we want. By using this output, we will demonstrate how BIRT report can be generated from UML models. Please go through this sample along with the design models to understand the requirements from the BIRT report.

Static model for text content
The artifact consists of design elements from the Rational Software Architect model and static text content that describes the model.

To easily manage the static text, we created the dwStaticModel project and included it in the tutorial archive. The project mirrors the requirements for the static content.
Figure 2. Design model for static content
Screenshot showing the model created for the static content

Review the project, especially the documentation for each package.

Figure 3. Documentation section of the package
Documentation is captured for the various entities

Larger view of Figure 3.

This documentation is used to generate the static content for the report.

Prepare the report

The first thing we do is create a report project named developerWorks and a new report named dwReport.rptdesign

Creating a BIRT report consists of the following steps:

  • Define the connection to the data sources.
  • Define the queries that will generate the data sets for the report.
  • Define the layout of the data elements.

Defining data sources

The report data is in two separate projects: dwSubscriptions and dwStaticModel; therefore we must create the data sources for each project.

  1. Open the Data Explorer view.
  2. Right-click Data Sources, and select New Data Source.
Figure 4. Creating a new data source
Dialog box for creating a new UML data source
  1. Choose UML Data Source, and enter the data source name as StaticDataSource in the Data Source Name text box
  2. Click Next.

The New UML Data Source is displayed.

Figure 5. Specifying the UML meta model for the report
A sample UML model is specified as the data source
  1. Specify the data source by doing the following steps:
    1. Choose Instance Models-> Add
    2. Select Browse Workspace…->dwStaticModel -> dwStaticModel.emx
    3. Confirm the choice by Ok -> Ok -> Finish
  2. The default meta model for the data source is UML 2.1.0 and the notation is 1.0.1.

UML 2.1.0 helps to develop data sets for classes, packages and property level. Notation helps to create data sets for component, interaction, activity and state diagrams

Use these steps again to add another data source DynamicDataSource, and point it to the dwSubscriptions.emx file.

Defining data sets

The next step is to create queries to be used in the reports. First we will create a report from the static text.

Data sets for the static model

We will create data sets for each package under the static model. We begin by creating a data set for Activity Diagrams Packages.

Figure 6. Creating a new data set
Interface for creating a data set
  1. In the Data Explorer view, select Data Set > New Data Set
  2. Select Static Data Source, and enter ActivityStaticDataSet for the data set name.
  3. Click Next. The Row Mapping screen is displayed.

The purpose of this step is to extract the documentation that we wrote for the Activity Diagrams package. We know that the model file is in an XML file. Rational Software Architect has a wizard that helps you create queries that can be used with this XML.

Figure 7. Extracting information from a model
Wizard for extracting information from the UML model
  1. In the Browse section, choose the UML model. Then select the package and click the button next to Row Query Expression. Enter uml:Package.
  2. Edit the row query to be //Package[@name='Activity Diagrams']

The XPath expression means "Get me all packages whose name is Activity Diagrams."

If you want to learn more about UML models, see the Resources section of this article for documentation and the org.eclipse.uml2.uml package.

  1. Click Next. The Column Mapping screen is displayed.

Now we must get the required attributes for the rows that we captured in the previous step. By default, it will display the first level attribute of the selected type (package in this scenario).

  1. Map the following columns from UML model:
    1. Name with @name
    2. Documentation with ownedComment/@body
Figure 8. Mapping columns
Display of column mappings for the data
  1. Click Finish.
  2. To see if the data set is correct, select Preview Results. You should get results like those displayed in Figure 9.
Figure 9. Query results
Display of the query results

Repeat these steps again for the following packages that remain in the static model:

  • Domain Model
  • Component Relationship
  • Introduction
  • Interaction
  • StateChart

Ensure that the package name is correct in the Row Mapping screen by referring to the package name that is specified in the Static Model project dwStaticModel.

Important: The Introduction package under static contents has sub packages. What will be the Row Query for the sub sections like Description, Identification etc? We leave this as an exercise for the readers. You can also refer to the attached sample report for the answer to this query.

Make sure that you complete all the data sets for the static content. In the next sub section, we will create the data set for the design models.

Data sets for design models

To create a new report parameter, select Outline view ->Report Parameters -> New Parameter. We will pass the package name as a parameter to the report.

Figure 10. Creating report parameters
Setting the parameters for the report

Now we will create a new data set named DomainModelClassDataSet and use it to get all the classes associated with the package name that is being passed as a parameter to the report.

  1. In the first screen of the Query Parameters wizard add a new parameter named packageName.
  2. Click Next.
Figure 11. Specifying parameters for the data set
Window for specifying parameters for the data set

The query parameter helps to externalize the query. This helps to generate custom reports, based on the input parameters passed to the report.

  1. In the Row Mapping screen, Browse 'UML Model' and select Package as expression
Figure 12. Extracting information from the model
Screen for extracting information from the UML model
  1. Change the row query expression to support the following query parameter //Package[@name=$packageName]/Class; and then select Class as the type.
Figure 13. Providing expression for the query
Window for specifying the query expression for the model
  1. Provide the following column mapping
Figure 14. Column mapping for a dynamic class set
Window that displays column mapping for the data
Figure 15. Creating parameters for the query
Window for creating parameters for the report query

To link the report parameter to this data set, select Linked To Report Parameter and assign the packageName parameter.

Figure 16. Linking the report and query parameters
Interface for linking report and query parameters

Now we are finished creating the data set using UML model. In the next section, we will create another data set by using the UML notation model.

Data set for interaction diagrams

To create a data set for interaction diagrams, choose the notation model in the Row Mapping tab.

Figure 17. Choosing the notation model for row mapping
Interface for choosing the notation model for the row mapping
  • In the Row Query Expression text box, enter getDiagrams(//Collaboration[@name='ArticleInteractions']/Interaction) and notation:Diagram.

Note: This expression means "Get me all the diagrams from all the Collaborations whose name is ArticleInteractions. Also the diagrams are below the Interaction."

With the notation model, you can easily query for the images by using the getDiagrams function. This row query gets us the interaction diagrams. We are interested the information that is displayed in Figure 18.

Figure 18. Column mapping for notation
Interface for mapping the result columns with output columns

Use the previous steps in this section to complete the wizard.

The notation model can be used in other cases where we need diagrams. See the report in the sample archive to see how we to create the rest of the datasets.

Now that we have the data set and data source ready, we can create the report, which involves creating the layout, putting the report elements on the report and setting the data sources.

Create the report layout

We have not described the report layout in detail because it is out of scope for this article. See the attached report for the layout details.

For this sample, we used the data sets that we created in this article and basic knowledge of BIRT to create the report. Other report layout considerations like header and footer, different main page, images, indexes can be used to make the report look polished.


Running the report

In this section, we describe how we can run the report and verify that the output report matches to our requirements.

Figure 19. Running the report
Menu for starting the report configuration wizard

Create a new configuration, and choose the following options to generate PDF report.

Figure 20. Creating report configurations
Interface for creating a new configuration for the BIRT report

Set the parameters for the report.

Figure 21. Setting the runtime parameters for the report
Interface for adding runtime parameters to the report

Summary

We generated design artifacts from the Rational Software Architect models by using the BIRT reports. In addition to the discussion on UML and Notation models, we also practiced the steps for creating data sources and data sets.


Downloads

DescriptionNameSize
File for articlePI_0612.zip37KB
Sample output design artifact work productsSampleDesignArtifact.pdf360KB

Resources

Learn

Get products and technologies

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=767156
ArticleTitle=Generate design work products from models
publish-date=11012011