View
787
Download
1
Category
Preview:
DESCRIPTION
Citation preview
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
© 2012 IBM Corporation 2
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
Customization steps
Best practices
Customer story
Demonstration
5. Questions
© 2012 IBM Corporation 3
The Premier Event for Software and Systems Innovation
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?
© 2012 IBM Corporation 4
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
Customization steps
Best practices
Customer story
Demonstration
5. Questions
© 2012 IBM Corporation 5
The Premier Event for Software and Systems Innovation
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”.
© 2012 IBM Corporation 6
The Premier Event for Software and Systems Innovation
What is reporting (continued)?
IBM Rational Reporting for Development Intelligence (RRDI) is a subset of IBM Rational Insight.
IBM Rational Reporting for Document Generation (RRDG) is a subset of IBM Rational Publishing Engine (RPE).
Rational
Team
Concert
RRDG
Rational
Insight
RRDI
RRDI RRDI
Rational
Quality
Manager
Rational
Requirements
Composer
Rational
Publishing
Engine
© 2012 IBM Corporation 7
The Premier Event for Software and Systems Innovation
What is reporting (continued)?
IBM Rational CLM Data Source:
© 2012 IBM Corporation 8
The Premier Event for Software and Systems Innovation
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?
© 2012 IBM Corporation 9
The Premier Event for Software and Systems Innovation
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
© 2012 IBM Corporation 10
The Premier Event for Software and Systems Innovation
RRDI: CLM and Insight
Data
Manager Java
Data Warehouse
Java
ODS Facts
Dims ETL
RTC
storage app
RQM
storage app
ETL
ETL
ETL
RRC
storage app
reports
templates
metadata
Cognos
engine
studios
ODBC
XML-
JDBC
XML-
JDBC
XML-
JDBC
REST
REST
REST
RRDI (optional)
ReqPro
storage app
CQ
storage app
ETL
CC
storage app REST
REST
REST
ETL
ETL
HPQC
storage app REST ETL
…
storage app REST ETL
CLM 2012
Rational Insight
© 2012 IBM Corporation 11
The Premier Event for Software and Systems Innovation
11
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
© 2012 IBM Corporation 12
The Premier Event for Software and Systems Innovation
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.
© 2012 IBM Corporation 13
The Premier Event for Software and Systems Innovation
RRDG: CLM and RPE
RTC
storage app
RQM
storage app
RRC
storage app
REST
REST
ReqPro
storage app
CQ
storage app
CC
storage app
REST
HPQC
storage app
…
storage app
RRDG
REST
RPE
Engine
CLM 2012
REST
© 2012 IBM Corporation 14
The Premier Event for Software and Systems Innovation
www.ibm.com/software/rational
© 2012 IBM Corporation 15
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
Customization steps
Best practices
Customer story
Demonstration
5. Questions
© 2012 IBM Corporation 16
The Premier Event for Software and Systems Innovation
Modify the ETL job specification in Data Manager
© 2012 IBM Corporation 17
The Premier Event for Software and Systems Innovation
Add specific project to XDC configuration
© 2012 IBM Corporation 18
The Premier Event for Software and Systems Innovation
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
© 2012 IBM Corporation 19
The Premier Event for Software and Systems Innovation
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)
© 2012 IBM Corporation 20
The Premier Event for Software and Systems Innovation
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)
© 2012 IBM Corporation 21
The Premier Event for Software and Systems Innovation
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
© 2012 IBM Corporation 22
The Premier Event for Software and Systems Innovation
GBS RRC & RQM usage model for a traceability report
© 2012 IBM Corporation 23
The Premier Event for Software and Systems Innovation
Create a report layout in Report Studio
© 2012 IBM Corporation 24
The Premier Event for Software and Systems Innovation
Sample report filter page when running a report
© 2012 IBM Corporation 25
The Premier Event for Software and Systems Innovation
Sample custom requirements traceability report
© 2012 IBM Corporation 26
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
Customization steps
Best practices
Customer story
Demonstration
5. Questions
© 2012 IBM Corporation 27
The Premier Event for Software and Systems Innovation
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.
© 2012 IBM Corporation 28
The Premier Event for Software and Systems Innovation
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.
© 2012 IBM Corporation 29
The Premier Event for Software and Systems Innovation
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.
© 2012 IBM Corporation 30
The Premier Event for Software and Systems Innovation
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.
© 2012 IBM Corporation 31
The Premier Event for Software and Systems Innovation
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.
© 2012 IBM Corporation 32
The Premier Event for Software and Systems Innovation
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.
© 2012 IBM Corporation 33
The Premier Event for Software and Systems Innovation
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).
© 2012 IBM Corporation 34
The Premier Event for Software and Systems Innovation
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.
© 2012 IBM Corporation 35
The Premier Event for Software and Systems Innovation
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).
© 2012 IBM Corporation 36
The Premier Event for Software and Systems Innovation
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.
© 2012 IBM Corporation 37
The Premier Event for Software and Systems Innovation
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.
© 2012 IBM Corporation 38
The Premier Event for Software and Systems Innovation
GBS RRC elements for document generation
© 2012 IBM Corporation 39
The Premier Event for Software and Systems Innovation
GBS document template files
© 2012 IBM Corporation 40
The Premier Event for Software and Systems Innovation
www.ibm.com/software/rational
© 2012 IBM Corporation 41
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
Customization steps
Best practices
Customer story
Demonstration
5. Questions
© 2012 IBM Corporation 42
The Premier Event for Software and Systems Innovation
www.ibm.com/software/rational
© 2012 IBM Corporation 43
The Premier Event for Software and Systems Innovation
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!
© 2012 IBM Corporation 44
The Premier Event for Software and Systems Innovation
Acknowledgements and disclaimers
© 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.
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.
© 2012 IBM Corporation 45
The Premier Event for Software and Systems Innovation
© 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.
www.ibm.com/software/rational
© 2012 IBM Corporation 46
The Premier Event for Software and Systems Innovation
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.
© 2012 IBM Corporation 47
The Premier Event for Software and Systems Innovation
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.
© 2012 IBM Corporation 48
The Premier Event for Software and Systems Innovation
Backup slide - RRDG report customization steps (continued)
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
© 2012 IBM Corporation 49
The Premier Event for Software and Systems Innovation
Backup slide - RRDG report customization steps (continued)
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
© 2012 IBM Corporation 50
The Premier Event for Software and Systems Innovation
Backup slide - RRDG report customization steps (continued)
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.
© 2012 IBM Corporation 51
The Premier Event for Software and Systems Innovation
Backup slide – Document Definition view
© 2012 IBM Corporation 52
The Premier Event for Software and Systems Innovation
Backup slide – Sample Document Definition artifact
© 2012 IBM Corporation 53
The Premier Event for Software and Systems Innovation
Backup slide – Document Section view
© 2012 IBM Corporation 54
The Premier Event for Software and Systems Innovation
Backup slide – Sample Document Section artifact
© 2012 IBM Corporation 55
The Premier Event for Software and Systems Innovation
Backup slide – Sample view for artifact sorting/filtering
© 2012 IBM Corporation 56
The Premier Event for Software and Systems Innovation
Backup slide – Sample report from a custom RRDG solution
Recommended