Session 1144 a

Reporting and Generating Documents in
IBM® Rational® Requirements Composer

M. Akbulut, C. McKay, R. Haven, G. Katragadda, C. Callegari
IBM
makbulut@us.ibm.com, cmckay@us.ibm.com, haven@us.ibm.com,
gopala@us.ibm.com, ccalleg@ar.ibm.com
Session ID: RDM-1144A

The Premier Event for Software and Systems Innovation

Agenda

1. Objectives
2. Reporting overview
 What is reporting (e.g. when to use RRDG vs. RRDI)
 Report architecture
 RRC 4.0 reporting demonstration

3. How to produce RRDI customized reports
 Customization steps
 Best practices
 Customer story
 Cross-product report example

4. How to produce RRDG customized reports
 Best practices
 Customer story
 Demonstration

2
5. Questions
© 2012 IBM Corporation


Objectives

This presentation will cover the following:
– What is IBM® Rational® Reporting for Document Generation (RRDG)?
– What is IBM Rational Reporting for Document Intelligence (RRDI)?
– What is the reporting architecture?
– What are the steps to create RRDG and RRDI custom reports?
– What are best practices for document and report generation?
– What are some real-world document and report generation examples?

3


Agenda

1. Objectives

 Best practices
 Customer story

 Best practices
 Customer story
 Demonstration

4
5. Questions


What is reporting?

 There are two broad categories of information
presentation that are important for software and
systems development:
– Development analytics (e.g. charts and dashboards used as
decision support tools)
– Document generation (e.g. documents generated from lower
level data)

 Both domains produce multiple output formats
(e.g. .doc, .pdf, .csv).

 Both are fundamentally different in their purpose,
and the nature of the information they are
representing.

 For simplicity, we refer to both categories as
“reporting”.
5


What is reporting (continued)?

 IBM Rational Reporting for
Rational
Development Intelligence (RRDI)
Publishing
is a subset of IBM Rational Insight.
Engine
RRDG
 IBM Rational Reporting for
Document Generation (RRDG) is a Rational
subset of IBM Rational Publishing Requirements
Engine (RPE). Composer

RRDI
Rational Rational
Team RRDI RRDI Quality
Concert Rational Manager
Insight

6


What is reporting (continued)?

IBM Rational CLM Data Source:

7


RRDI for development analytics

 RRDI provides you with the capability to create and view charts and dashboard
style reports for data collected in the Rational Collaborative Lifecycle Management
(CLM) solution (e.g. RRC, RTC, RQM).

 RRDI reports are generally used for management purposes.
– The reports are not usually the deliverables
– The reports help to communicate status, monitor progress, and diagnose problems
– They are a key decision support tool

 Traditional development analytic techniques can help us understand the data.
– Crosstabs/pivots – How does the data break down?
– Drill up/down/through – How is the data interrelated?
– Dashboards – What is the big picture?
– Data warehouses – How are we trending over time?

8


RRDI for development analytics (continued)

 A data warehouse is provided to enable historical trend reporting.

 RRDI examples:
 Percentage of open work items or defects
 Change in the number of untested work items
 Show the rate of change of requirements (volatility) over time

9


RRDI: CLM and Insight

Data
Java Manager
RTC ReqPro
XML-
app ETL ETL
storage REST JDBC REST storage app

Data Warehouse
RQM CQ
Java
XML-
app JDBC ETL ETL Facts ETL app
storage REST
ODS REST storage
Dims

RRC ODBC CC
XML-
storage app JDBC ETL ETL app
REST REST storage
RRDI (optional)
Cognos
reports HPQC
engine
templates
studios
metadata ETL REST storage app

CLM 2012
…
ETL app
REST storage

Rational Insight

10


RRDG document generation

 RRDG provides you the capability to generate documents from RRC.

 Documentation is most often a deliverable.
– Specifications are often written in one project phase and then passed into the following phase
– Documents may be contractual deliverables
– Specifications may have to comply with standards/requirements

 RRDG examples:
– A requirements specification
– A document showing test case coverage of requirements

11
11


RRDG document generation (continued)

 Reports can contain linked data from all three CLM products, using
IBM Rational Publishing Engine (RPE).

 A RPE license is required to create document template archive (.dta)
files.

 Customized .dta files can be deployed on the RRC server, where an
RPE client is not needed.

12


RRDG: CLM and RPE

ReqPro
RTC
REST storage app
storage app REST

CQ
RQM
REST storage app
storage app REST

RPE CC
RRC
Engine app
storage
storage app
REST

RRDG HPQC

storage app

CLM 2012
…

storage app

13


www.ibm.com/software/rational

14


Agenda

1. Objectives

 Best practices
 Customer story

 Best practices
 Customer story
 Demonstration

15
5. Questions


Modify the ETL job specification in Data Manager

16


Add specific project to XDC configuration

17


RRDI report customization steps

 Create Report
– Report Studio

 Deploy Report
– Extract into .zip
– Upload to Cognos Administration
– Schedule report execution (optional)
– Publish extract, transform, and load (ETL)
– Schedule ETL

 Establish CLM data linkages, if necessary
– Create linkages across RTC, RQM, RRC artifacts

 Run report
– Select / run report for cross product traceability
18


RRDI best practices

 Understand the out of the box CLM data model
Notes:
• Custom fields are accessible via existing ETL.
• Avoid custom ETL if possible.
• Use Query Studio to browse your data warehouse

 Populate your CLM instance with data, according to your custom usage model.

 Organize the report according to your custom usage model

 Longer term; consider extending business model relevant to your processes
(e.g. add semantics of business / system / component requirements traceability to the
data source)

19


RRDI best practices (continued)

 Save backup copies of .xdc files from which to copy

 Ensure project URL's are properly escaped in .xdc (e.g. “%20” for a
space character)

 Build queries from the bottom up, for maintainability

 Schedule report generation in off hours to:
– Improve perceived performance
– Make a report readily available the next working shift
– Send a copy of a report automatically to your inbox (no access to Rational
Insight required)

20


IBM Application Management Services customer story

As a project team member, I want to generate a matrix report, showing
requirement traceability and test status, so that I may understand:
• Requirement coverage
• Impact analysis of proposed changes
• Correlated design elements
• Affected components
• Test results

21


GBS RRC & RQM usage model for a traceability report

22


Create a report layout in Report Studio

23


Sample report filter page when running a report

24


Sample custom requirements traceability report

25


Agenda

1. Objectives

 Best practices
 Customer story

 Best practices
 Customer story
 Demonstration

26
5. Questions


RRDG report customization steps

1. Identify which documents or reports should be automatically generated from the
RRC 4.0 configuration.

2. Obtain samples of the target documentation with real data.

3. Modify the RRC configuration to support any needed artifact types, artifact
templates, and default artifact template formatting.

4. Prepare the .dta file using RPE 1.1.2.2.

5. If additional styling beyond RPE is needed, prepare the Microsoft® Word .dot file.

6. Place the files on the target RRC server.

7. Update the RRC server’s manifest file with entries for the .dot and .dta files.

8. Reinitialize the RRDG publishing service.
27


General RRDG best practices

 An existing RPE document template from RRC can be a great starting point for:
– Learning RPE
– Template reuse and/or tailoring
– Accessing RRC data

 Understand what your data source has to offer (e.g. RRC REST APIs)

 Add comments to your RPE document template to help:
– The developer quickly understand the template if she or he revisits the template a few months
later.
– Future maintainers quickly understand it
– Translators quickly understand it for the purpose of translating the template into another
language

 Modularize your RPE document template design
– Since RRC allows one document template per report, modularize the template using RPE
containers.
28


General RRDG best practices

 Automate as much of the document generation as possible, using the minimum
RRC variable prompts.

 Always periodically unit test as you add more content to your RPE document
template. Do not perform big bang testing.

 The more document formats you support, the greater the development effort.

29


RRDG development best practices

 The sooner you rush into implementing a document template, the later you
will finish that implementation. In general, consider spending 60% of RPE
development effort on:
– Document analysis
– Experimenting with RPE constructs or workarounds that will display consistently across your
target document file formats
– Document template design

 When you need to debug the cause of a RPE document generation problem,
consider:
– Inserting “Text” constructs to print interim results throughout the document template.
– Temporarily disabling portions of the document template to rule out which area is causing the
problem (e.g. disable a large RPE container by setting a condition of 1 == 2)

 Passing data from the document template to a “Master Page” can be
performed using a variable.

30


RRDG development best practices (continued)

 Do not copy and paste any RPE constructs (e.g. copy a paragraph or text
construct).
Why? Copy and paste can cause major side effects for people translating a document template into
other languages.

 Generate document content from your data source. Keep translation of
content and report definition separate.

31


RRDG formatting best practices

 Try to design RPE document templates to work for all output document file
formats supported, with the minimum amount of RPE code. Try to minimize the
usage of RPE constructs that work only on one specific format.

 If you are supporting .doc and .pdf formats, then use a heading level number
(e.g. 1, 2) to define the heading level in RPE. A .dot file can address consistent
heading level styles.

 Use RPE styles to enforce a consistent format across the document.

 When you determine a table format that will work with specific column widths,
use that table format consistently across RPE document template(s) for a
professional look.
32


RRDG formatting best practices (continued)

 Document headings, organization, and formatting can be:
a. Defined in the RRC data source (e.g. RRC artifact templates with default font type and size)

b. Hard coded in an RPE document template

c. Defined in a Microsoft Word .dot file

Advice:

• Option “a” can provide greater tailorability for RRC authors, but it can be involve more effort
in RRC artifact set up.

• Option “b” can be hard coded in a way where there is less work for RRC authors to organize
and format artifacts. On the other hand, option “b” is probably more expensive and less
tailorable to varying organization needs.

• If development would like to maintain fewer formats and does not mind a dependency on
software for file format conversion, option “c” is another possibility (e.g. if .doc and .pdf
formats should be supported, then support the .doc format and ask users to leverage
Microsoft Word 2007 or PrimoPDF® to convert the .doc to .pdf).

33


RRDG formatting best practices (continued)

 For rich text that resides in your data source, ensure that the rich text’s font,
size, etc. are compatible with the font, size, etc. leveraged in your RPE
document template. If necessary, instruct users on the font, size, etc. to
leverage for their rich text data sources.

Example:

– Suppose your document template is leveraging an Arial 10 point font for body text. Also,
suppose your document generation will leverage RRC 4.0 as a data source.

– For any RRC rich text artifacts, ensure the text being input is also an Arial 10 point font.
Otherwise, your document may look non-professional, with varying font types and sizes.

34


RRDG data best practices

 Where possible, use realistic data from your data source to unit test your
document template. Why?
– Junk test data may be too short for testing your document template.

– Realistic data may influence decisions on:

• The ideal width of table columns

• Any needed word wrapping

• Header and footer design

 Design the document template to handle common data errors or warnings
(e.g. display in bold yellow that no data was found for a section in a
generated document).

35


RRDG performance best practices

 Early in your document design, performance test your document generation on
realistic volumes of data in your data source. For example, suppose a
document may rely on 50 to 300 requirement artifacts in RRC. Test those
volumes to ensure your document generation is not taking too long.

 Tips for improving your .dta file on RRDG:
– RPE filter constructs can sometimes improve performance in selecting data from a
data source.

– Minimize the number of times a RPE “data source configuration” construct is used,
to avoid performance degradation.

36


IBM Application Innovation Services customer story

As a Business Analyst, I want to generate a requirement specification according to
my organization's format and tailoring needs, so that I may share the specification
with a customer for review and signoff.

37


GBS RRC elements for document generation

38


GBS document template files

39



40


Agenda

1. Objectives

 Best practices
 Customer story

 Best practices
 Customer story
 Demonstration

41
5. Questions



42


Daily iPod Touch giveaway

 Complete your session surveys online each day at a conference kiosk or on your
Innovate 2012 Portal!

 Each day that you complete all of that day’s session surveys, your name will be entered
to win the daily IPOD touch!

 On Wednesday be sure to complete your full conference evaluation to receive your
free conference t-shirt!

43


Acknowledgements and disclaimers

Availability: References in this presentation to IBM products, programs, or services do not imply that they will be available in all countries
in which IBM operates.

The workshops, sessions and materials have been prepared by IBM or the session speakers and reflect their own views. They are provided for
informational purposes only, and are neither intended to, nor shall have the effect of being, legal or other guidance or advice to any participant.
While efforts were made to verify the completeness and accuracy of the information contained in this presentation, it is provided AS-IS without
warranty of any kind, express or implied. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, this
presentation or any other materials. Nothing contained in this presentation is intended to, nor shall have the effect of, creating any warranties or
representations from IBM or its suppliers or licensors, or altering the terms and conditions of the applicable license agreement governing the use of
IBM software.

All customer examples described are presented as illustrations of how those customers have used IBM products and the results they may have
achieved. Actual environmental costs and performance characteristics may vary by customer. Nothing contained in these materials is intended to,
nor shall have the effect of, stating or implying that any activities undertaken by you will result in any specific sales, revenue growth or other results.

© Copyright IBM Corporation 2012. All rights reserved.
– U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

IBM, the IBM logo, ibm.com, Rational, the Rational logo, Telelogic, the Telelogic logo, Green Hat, the Green Hat logo, and other IBM products and
services are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. If these
and other IBM trademarked terms are marked on their first occurrence in this information with a trademark symbol (® or ™), these symbols indicate
U.S. registered or common law trademarks owned by IBM at the time this information was published. Such trademarks may also be registered or
common law trademarks in other countries. A current list of IBM trademarks is available on the Web at “Copyright and trademark information” at
www.ibm.com/legal/copytrade.shtml
Microsoft® Office
Other company, product, or service names may be trademarks or service marks of others.

44



© Copyright IBM Corporation 2012. All rights reserved. The information contained in these materials is provided for informational purposes only, and is provided AS IS without warranty of any kind,
express or implied. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, these materials. Nothing contained in these materials is intended to, nor shall have
the effect of, creating any warranties or representations from IBM or its suppliers or licensors, or altering the terms and conditions of the applicable license agreement governing the use of IBM
software. References in these materials to IBM products, programs, or services do not imply that they will be available in all countries in which IBM operates. Product release dates and/or capabilities
referenced in these materials may change at any time at IBM’s sole discretion based on market opportunities or other factors, and are not intended to be a commitment to future product or feature
availability in any way. IBM, the IBM logo, Rational, the Rational logo, Telelogic, the Telelogic logo, and other IBM products and services are trademarks of the International Business Machines
Corporation, in the United States, other countries or both. Other company, product, or service names may be trademarks or service marks of others.

45


Backup slide - RRDG report customization steps

1. Identify which documents or reports should be automatically generated from the RRC
configuration. Check if RRDG is a good candidate for generation of these deliverables.

2. Obtain samples of the target documentation, preferably with real data. Identify:
 Which document standards to comply with (e.g. all Arial 9 point font for body text)
 Which output formats to support (e.g. .pdf, .doc).
 Which artifact types, artifact templates, and default artifact template formatting (e.g. default font, style,
size) are needed in the RRC configuration.

3. Modify the RRC configuration to support the needed artifact types, artifact templates, and
default artifact template formatting.

46


Backup slide - RRDG report customization steps (continued)

4. Reuse/modify/create the document template archive (.dta) file in IBM Rational Publishing
Engine (RPE) version 1.1.2.2.

5. Reuse/modify/create the Microsoft® Word document template (.dot) if needed for additional
formatting (e.g. font, style, etc. for each document heading level)

6. Unit test the .dta file and .dot file as more content is added. If you are using a RPE client for
unit testing, you may reuse/modify/create a temporary RPE document specification (.dsx) file
to specify: the file formats, the RRC data source location, variable values, etc.

Note: The .dsx file will not be used by RRDG.

47



7. Place the .dta file on the RRC server location: <Install
path>/server/conf/rm/reporting/initialization/templates/rrdg/<the appropriate sub directory
where you see other .dta files> with chmod 776 privileges

8. Place the .dot file on the RRC server location: <Install
path>/server/conf/rm/reporting/initialization/templates/word/<the appropriate sub directory
where you see other .dot files> with chmod 776 privileges

48



9. From the path: <Install path>/server/conf/rm/reporting/initialization/META-INF>, open the
MANIFEST.MF file. FYI, this file usually has .dta entries near the top of the file and .dot
entries near the bottom of the file. Add the following two entries:

 First entry (to add near the top of the file):
 Name: <the physical file name of your .dta file, but do not include the .dta at the end of the file name>
 Location: templates/rrdg/<full physical file name of the .dta file>
 Label: <user friendly name of your report or document that a user could select from a RRC report
wizard>
 Description: <Enter a user friendly description of your report or document. Include the file version of
the report or document.>
 Content-Type: application/octet-stream
 Is-Report: true

 Second entry (to add near the bottom of the file):
 Name: <full physical file name of the .dot file>
 Location: templates/word/<full physical file name of the .dot file>
 Content-Type: application/msword

49



10. If this is a new version of your report or document that replaces a previous version, consider
removing the previous .dta and .dot files from the MANIFEST.MF file.

11. Ensure there is an empty line at the end of the MANIFEST.MF file. Save the file.

12. From a web browser, reinitialize the RRDG publishing service using the following url:
https://<server:port>/rm/publish/initialize

Note: No server reboot is necessary.

13. Perform remaining unit/function testing of your document or report generation, using the
RRC user interface to select the report, respond to any variable prompts, etc.

50

Session 1144 a

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Session 1144 a

Similar to Session 1144 a (20)

Recently uploaded

Recently uploaded (20)

Session 1144 a