More Related Content Similar to Session 1144 a Similar to Session 1144 a (20) Session 1144 a1. 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
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
2
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?
3
© 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
4
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”.
5
© 2012 IBM Corporation
6. The Premier Event for Software and Systems Innovation
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
© 2012 IBM Corporation
7. The Premier Event for Software and Systems Innovation
What is reporting (continued)?
IBM Rational CLM Data Source:
7
© 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?
8
© 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
9
© 2012 IBM Corporation
10. The Premier Event for Software and Systems Innovation
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
© 2012 IBM Corporation
11. The Premier Event for Software and Systems Innovation
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
© 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.
12
© 2012 IBM Corporation
13. The Premier Event for Software and Systems Innovation
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
© 2012 IBM Corporation
14. The Premier Event for Software and Systems Innovation
www.ibm.com/software/rational
14
© 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
15
5. Questions
© 2012 IBM Corporation
16. The Premier Event for Software and Systems Innovation
Modify the ETL job specification in Data Manager
16
© 2012 IBM Corporation
17. The Premier Event for Software and Systems Innovation
Add specific project to XDC configuration
17
© 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
18
© 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)
19
© 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)
20
© 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
21
© 2012 IBM Corporation
22. The Premier Event for Software and Systems Innovation
GBS RRC & RQM usage model for a traceability report
22
© 2012 IBM Corporation
23. The Premier Event for Software and Systems Innovation
Create a report layout in Report Studio
23
© 2012 IBM Corporation
24. The Premier Event for Software and Systems Innovation
Sample report filter page when running a report
24
© 2012 IBM Corporation
25. The Premier Event for Software and Systems Innovation
Sample custom requirements traceability report
25
© 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
26
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.
27
© 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.
28
© 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.
29
© 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.
30
© 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.
31
© 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.
32
© 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).
33
© 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.
34
© 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).
35
© 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.
36
© 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.
37
© 2012 IBM Corporation
38. The Premier Event for Software and Systems Innovation
GBS RRC elements for document generation
38
© 2012 IBM Corporation
39. The Premier Event for Software and Systems Innovation
GBS document template files
39
© 2012 IBM Corporation
40. The Premier Event for Software and Systems Innovation
www.ibm.com/software/rational
40
© 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
41
5. Questions
© 2012 IBM Corporation
42. The Premier Event for Software and Systems Innovation
www.ibm.com/software/rational
42
© 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!
43
© 2012 IBM Corporation
44. The Premier Event for Software and Systems Innovation
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
© 2012 IBM Corporation
45. The Premier Event for Software and Systems Innovation
www.ibm.com/software/rational
© 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
© 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.
46
© 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.
47
© 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
48
© 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
49
© 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.
50
© 2012 IBM Corporation
51. The Premier Event for Software and Systems Innovation
Backup slide – Document Definition view
51
© 2012 IBM Corporation
52. The Premier Event for Software and Systems Innovation
Backup slide – Sample Document Definition artifact
52
© 2012 IBM Corporation
53. The Premier Event for Software and Systems Innovation
Backup slide – Document Section view
53
© 2012 IBM Corporation
54. The Premier Event for Software and Systems Innovation
Backup slide – Sample Document Section artifact
54
© 2012 IBM Corporation
55. The Premier Event for Software and Systems Innovation
Backup slide – Sample view for artifact sorting/filtering
55
© 2012 IBM Corporation
56. The Premier Event for Software and Systems Innovation
Backup slide – Sample report from a custom RRDG solution
56
© 2012 IBM Corporation