TCR Style Guide

Tivoli Tivoli Common Reporting
Version 1.2.0.1
Development and Style Guide
SC23-8861-01
Tivoli Tivoli Common Reporting
Version 1.2.0.1
Development and Style Guide
SC23-8861-01
Note
Before using this information and the product it supports, read the information in Notices on page A-1.
Fourth Edition (September 2009)

This edition applies to version 1.2.0.1 of Tivoli Common Reporting and to all subsequent releases and modifications
until otherwise indicated in new editions.
Copyright International Business Machines Corporation 2007, 2009.
US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Table of Contents
WHATS NEW..............................................................................................................................................3
TABLE OF CONTENTS.............................................................................................................................4
SECTION 1 TIVOLI COMMON REPORTING OVERVIEW...............................................................7
1.1 GETTING STARTED WITH TIVOLI COMMON REPORTING ....................................................................................7
1.2 REPORT CONTENT IS KEY............................................................................................................................7
SECTION 2 TOOLS......................................................................................................................................9
2.1 OVERVIEW.................................................................................................................................................9
2.2 EDUCATIONAL MATERIALS..........................................................................................................................9
2.3 JAVA.........................................................................................................................................................9
2.4 ECLIPSE AND BIRT....................................................................................................................................9
2.5 DATABASE DRIVERS..................................................................................................................................10
2.5.1 IBM DB2....................................................................................................................................10
2.5.2 Microsoft SQL Server................................................................................................................11
2.5.3 Oracle............................................................................................................................................11
2.5.4 How to Add a JDBC Driver and Configure a JDBC Datasource.................................................11
SECTION 3 STYLE GUIDELINES..........................................................................................................15
3.1 DOCUMENT LAYOUT ................................................................................................................................16
3.1.1 Overall Document Style................................................................................................................16
3.1.2 Overall Document Color Pallet....................................................................................................17
3.2 REPORT HEADER......................................................................................................................................18
3.3 REPORT INTRODUCTION.............................................................................................................................18
3.3.1 Report Title....................................................................................................................................18
3.3.2 Report Sub-Title............................................................................................................................18
3.3.3 Secondary Title..............................................................................................................................19
3.3.4 Parameters....................................................................................................................................19
3.4 INFORMATION SECTIONS ............................................................................................................................21
3.4.1 Section Title...................................................................................................................................21
3.4.2 Charts............................................................................................................................................22
3.4.3 Standard Tables.............................................................................................................................29
3.4.4 Grouping Tables............................................................................................................................31
3.4.5 Form Elements.............................................................................................................................33
3.5 REPORT DESCRIPTION...............................................................................................................................34
3.6 MESSAGE DIALOG BOXES.........................................................................................................................34
3.7 COLLAPSIBLE SECTIONS............................................................................................................................36
3.8 REPORT FOOTER.......................................................................................................................................36
3.9 SAMPLE REPORTS LAYOUTS........................................................................................................................37
SECTION 4 CREATING REPORTS AND REPORT PACKAGES ...................................................40
4.1 INTRODUCTION..........................................................................................................................................40
4.2 TIVOLI COMMON REPORTING STYLE PACKAGE.............................................................................................40
4.2.1 Style Package Description...........................................................................................................40
4.2.2 Importing Style Package into BIRT..............................................................................................42
4.2.3 Creating your BIRT Project.........................................................................................................42
4.2.4 Modify the BIRT settings for resources and templates.................................................................43
4.2.5 Report Naming Convention...........................................................................................................43
4.3 TIVOLI COMMON REPORTING LIBRARY .......................................................................................................44
Copyright IBM Corp. 2007, 2009
4.3.1 TCR Theme....................................................................................................................................46

4.3.2 Report Parameters........................................................................................................................47
4.3.3 Report Items..................................................................................................................................47
4.3.4 TCR Master Page..........................................................................................................................47
4.4 REPORT TEMPLATES..................................................................................................................................48
4.4.1 Using TCR Templates...................................................................................................................49
4.4.2 Using the Table Template.............................................................................................................52
4.4.3 Using the Group Table Templates................................................................................................55
4.4.4 Using the Chart Template ............................................................................................................58
4.4.5 Using the Chart Table Combo Template ......................................................................................64
4.5 SAMPLE REPORTS......................................................................................................................................65
4.5.1 TableWithDrillthrough Sample Report.........................................................................................65
4.5.2 ChartsWithDrillthrough Sample Report.......................................................................................67
4.5.3 DynamicColumnSort Sample Report............................................................................................70
4.5.4 DynamicChartDimensions Sample Report....................................................................................70
4.5.5 ExpandCollapseSections Sample Report......................................................................................72
4.5.6 DynamicQuery Sample Report......................................................................................................75
4.5.7 DynamicTableColumnsAndVisibilityControl Sample Report.......................................................76
4.5.8 MessageDialogs Sample Report....................................................................................................76
4.5.9 QuickLinks Sample Report............................................................................................................77
4.5.10 ParameterValidation Sample......................................................................................................77
4.5.11 StatusBasedColoringChart Sample.............................................................................................78
4.5.12 TableFooterWithTotals Sample Report.......................................................................................79
4.5.13 DateRangeParameters Sample Report........................................................................................81
4.5.14 CascadingParameters Report.....................................................................................................84
4.5.15 DependentDatasets Sample Report.............................................................................................86
4.5.16 TableUsingStatusIcons Sample Report.......................................................................................87
4.5.17 MultipleSelectListBoxParameter Report.....................................................................................88
4.6 SCRIPTS...................................................................................................................................................89
4.6.1 ReportUtils.js.................................................................................................................................89
4.6.2 DateTime.js...................................................................................................................................89
4.6.3 ModifyQuery.js..............................................................................................................................90
4.6.4 Logger.js........................................................................................................................................90
SECTION 5 BEST PRACTICES...............................................................................................................91
5.1 PROJECTS AND LIBRARIES ...........................................................................................................................91
5.2 GENERAL REPORT PROPERTIES....................................................................................................................92
5.3 GLOBALIZATION / LOCALIZATION................................................................................................................92
5.3.1 Setting Up Basic Globalization.....................................................................................................93
5.3.2 Globalizing Strings Embedded in HTML Text..............................................................................93
5.3.3 Globalizing Report Title and Description.....................................................................................94
5.3.4 Globalizing Report Element Names..............................................................................................94
5.4 DATA SOURCES........................................................................................................................................95
5.4.1 JNDI Naming Convention.............................................................................................................95
5.5 DATA SETS..............................................................................................................................................96
5.6 TIMESTAMPS............................................................................................................................................97
5.6.1 Timestamps in Charts ...................................................................................................................97
5.6.2 Timestamps in Tables and Parameters.........................................................................................98
5.6.3 Timestamp in Footer.....................................................................................................................98
5.7 CHARTS...................................................................................................................................................99
5.8 USEFUL HINTS AND TIPS...........................................................................................................................99
5.8.1 BIRT Designer...............................................................................................................................99
5.8.2 Tables............................................................................................................................................99
5.8.3 Charts............................................................................................................................................99
APPENDIX A TERMINOLOGY ..........................................................................................................101
Section 1Tivoli
1Tivoli Common Reporting Overview
1.1 Getting Started With Tivoli Common Reporting
The purpose of this guide is to provide assistance on how to create reports that
meet the Tivoli Common Reporting (TCR) guidelines and integrate well into the
Tivoli Common Reporting software.
TCR provides a software component, report definition guidelines, and report
templates that can be used by Tivoli products, business partners, and customers.
These guidelines enable consistency in report styles and report generation,
providing a common look and feel, as well as quicker and easier report creation.
Using product supplied reports as the starting point, customers and business
partners can easily create customized extensions that fit into the overall reporting
system, yet meet their individualized needs.
The following is a quick overview of the steps necessary to develop reports that
smoothly integrate into Tivoli Common Reporting.
1. Obtain all prerequisite tools required for building your reports.
2. Decide how to deploy your reports within Tivoli Common Reporting.
3. Determine what reports your customers need, based on your product,
customer expertise or customer interviews.
4. Learn the templates and libraries in the TCR style package.
5. Using the templates and libraries, design and test your reports using the
BIRT report designer.
6. Install and test your reports in Tivoli Common Reporting.
1.2 Report Content Is Key

Producing high-value, consistent reports for Tivoli products requires user
interaction, design analysis and innovation, and development discipline.
High Value: Each report should provide information that is important to

running the business, improving productivity, or showing the return on
investment made in products and processes that use those products. In
order to achieve this value, you must have a deep understanding of how
your customers processes work, and what drives the cost and service
delivery and support structures. To achieve this value requires:
o
Outside-In Design work to identify and validate reporting content that

users will find valuable and useful in their environments.
Analysis of the visual display of the information and innovation of

techniques to get the message across quickly and effectively.
Integration of design across products and processes to fully

understand how to obtain the proper metrics and performance
indicators and ensure high quality of the data being produced.
Consistent: As users look at the reports produced from different Tivoli

products, reports written by business partners, and reports developed inhouse, there should be leverage gained from understanding the previous
reports and quickly identifying related information. This leverage can
only be obtained when reports are visually consistent in their

appearance, layout, function, and especially terminology and semantics
of the data. Achieving this consistency means:
o
Visual-appearance standards for features such as graphics

splashes, titles, fonts, and color schemes.
Layout standards for features such as chart sizes and locations, and
templates for combining information on a single page.
Algorithmic and analytical standards, such as statistical process

control charts with mean and standard deviation consistency, and
consistent use of aggregations (sums, averages, and counts).
Consistency in the underlying data used to produce reports. This

consistency means that individual data objects must be semantically
equivalent and labeled in the same way. Timestamps must be
represented syntactically in the same way, and when compared,
must represent the same context.
This document assists in achieving the consistency and high value goals by
providing a standardized set of report styles and samples upon which visually
effective, easy to read reports can be developed. Tivoli Common Reporting also
provides a set of tools that enable consistency in report access, viewing and
management , thereby improving the overall investment in reporting. Consistent
use of these report styles, samples and tools across multiple product, business
partner and customer-written reports provides the basis for achieving the goals in
this section.
Section 2Tools
2Tools
2.1 Overview
The standard development tool for all reports created for Tivoli Common
Reporting is Business Intelligence and Reporting Tools (BIRT).
BIRT is an open source tool based on the popular Eclipse development platform,
which is also open source. Both are written in Java and rely on a Java runtime
environment.
2.2 Educational Materials

The Tivoli Common Reporting Web page at IBM developerWorks
(http://www.ibm.com/developerworks) is a reference source for many useful
reporting hints and tips. The developersWorks page contains forums on report
development topics, hints and tips sections on useful reporting techniques, and
pointers to the reports that are available for Tivoli products.
The Eclipse Web site at eclipse.org has a number of articles and tutorials on
BIRT. A number of forums are also available on the Internet for users of BIRT to
exchange hints, tips and problems.
The Creating reports and report packages section in this Guide describes how to
start building reports using BIRT with the Tivoli Common Reporting templates.
This section includes the Sample Reports sub-section describing TCR supplied
sample reports showing optional features that highlight usability or design
features that can be included in reports.
The Best Practices section in this Guide describes techniques such as
globalization, naming standards, and similar guidelines for defining your report.
The Tivoli Common Reporting Users Guide, supplied with Tivoli Common
Reporting V1.1.1, contains detailed information on installing and using the Tivoli
Common Reporting V1.1.1 software.
Two useful reference books provide detailed information how to use BIRT:
BIRT: A Field Guide to Reporting, by Diana Peh, Alethea Hannemann

and Nola Hague. Addison-Wesley, 2006. ISBN 0-321-44529-8.
Integrating and Extending BIRT, by Jason Weathersby, Don French,

Tom Bondur, Jane Tatchell and Iana Chatalbasheva. Addison-Wesley,
2006. ISBN 0-321-44385-3.
These books can be purchased from any technical book supplier.
2.3 Java
A Java Runtime Environment (JRE) is required to run the Eclipse/BIRT SDK.
The minimum level of Java required is JRE 1.5.
2.4 Eclipse and BIRT

Eclipse is a general-purpose software development platform designed for
developing Web applications conforming to Java 2 Platform, Enterprise Edition
(J2EE) standards. The minimum level of Eclipse required is 3.3.1.
Business Intelligence and Reporting Tools (BIRT) is a plug-in for Eclipse. BIRT
2.2.1 is the base reporting engine for products that use Tivoli Common Reporting
version 1.1.1
If you do not already have Eclipse and BIRT, you must install the appropriate
version of Eclipse with the BIRT 2.2.1 report designer. This tool is not included
with Tivoli Common Reporting, but is available for download. See the Tivoli
Common Reporting Web page on IBM developerWorks for more information; you
can also download appropriate versions from the Eclipse Web site (or other
appropriate open source sites).
Note: Make sure you download a version of the BIRT report designer that is
compatible the BIRT 2.2.1 version used by the Tivoli Common Reporting server.
Using incompatible versions of the report designer and the report engine can
cause problems when importing and running reports.
The BIRT report designer is available in several different installation packages:
All-in-One: A complete Eclipse installation along with the BIRT Designer.

This is the recommended package to use with Tivoli Common
Reporting.
Framework: The BIRT plug-in by itself. You can use this package if you
already have an appropriate Eclipse environment installed.
Rich Client Platform (RCP): The stand-alone BIRT report designer

without the Eclipse framework. A JRE is still required for this package.
The files for the BIRT runtime engine are already included in the Tivoli Common
Reporting installation CD and do not need to be separately obtained or installed.
2.5 Database Drivers

BIRT reports can be generated for a wide variety of data sources, including log
files, CSV files, and XML files. The most common data source is a relational
database, accessed using a Java ODBC (JDBC) driver.
BIRT supports JDBC 3.0. In order to design a production report, you must have
the proper database driver already installed.
The BIRT Manage JDBC Drivers dialog in the Report Designer lets you add
JDBC drivers to the designer. You can obtain the drivers directly from the
database vendor.
The following sections describe common JDBC drivers available from the major
DBMS vendors.
2.5.1
IBM DB2
The DB2 Universal JDBC driver is a Type 4 driver that can connect directly to a
DB2 server. No DB2 client software is required on the platform where the driver
is installed. The Universal JDBC driver class name is:
com.ibm.db2.jcc.DB2Driver
Download the DB2 v9 JDBC Type 4 driver here:
https://www14.software.ibm.com/webapp/iwm/web/preLogin.do?
lang=en_US&source=swg-dm-db2jdbcdriver
The driver files are as follows:
10
db2jcc.jar
db2jcc_license_cu.jar
General information about DB2 and JDBC can be found here:

http://www.ibm.com/software/data/db2/ad/v8/java.html
Information on DB2 v8 compatible driver levels can be found here:
http://www-1.ibm.com/support/docview.wss?rs=71&uid=swg21251460
DB2 v8 drivers can be downloaded here:
http://www-1.ibm.com/support/docview.wss?rs=71&uid=swg21256235
2.5.2
Microsoft SQL Server

Download the SQL Server 2000 SP3 JDBC Type 4 Driver here:
http://www.microsoft.com/downloads/details.aspx?FamilyID=07287B110502-461A-B138-2AA54BFDC03A&displaylang=en
Download the SQL Server 2005 JDBC Type 4 Driver here:
http://www.microsoft.com/downloads/details.aspx?familyid=6D483869816A-44CB-9787-A866235EFC7C&displaylang=en
2.5.3
Oracle
Download the JDBC 3.0 drivers for Oracle 8, 9, and 10 here:
http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html
2.5.4
How to Add a JDBC Driver and Configure a JDBC Datasource

To add a JDBC driver to the Eclipse/BIRT IDE, you must define a data source.
After the data source is defined, double-click on it in the Data Explorer tab of the
IDE. The following sample window opens:
11
Click on the Manage Drivers button to display the Manage JDBC Drivers
window:
Click the Add button to add a new driver. This opens a file selection window
where you can specify the location of the .jar or .zip file containing the driver you
want to use. For example, IBM DB2 JDBC drivers are typically found in
<DB2_Install_Dir>\SQLLIB\java12\db2java.zip. Or, if you have downloaded more
recent JDBC driver JAR files from the IBM DB2 web site, you would specify
these files in the file selection window. Once you select the appropriate driver
files, the Manage JDBC Drivers window shows the new files added:
12
To see which JDBC drivers are included in these .jar files, click the Drivers tab:
Click OK to return to the Edit Data Source window. In the Driver Class field,
select the appropriate driver for your report:
13
For DB2, select the Universal JDBC driver class:

com.ibm.db2.jcc.DB2Driver
For a DB2 database URL, enter a URL such as the following:
jdbc:db2://server:port/database[:property=value;]
where:
server
The domain name or IP address of the database server.
port
The TCP/IP server port number assigned to the database server. This is
an integer between 0 and 65535. The default is 50000.
database
A name for the database server.
property=value;
A property for the JDBC connection. For the definitions of these
properties, see Properties for the DB2 Universal JDBC Driver. One
common property is currentSchema which defines the default schema for
all unqualified table names used in the JDBC connection.
Tivoli Common Reporting best practices strongly recommend that a JNDI name
be used to define the database definition for production implementations, rather
than coding the URL, name and password as noted above. See the section on
JNDI Naming Convention for further information about using a JNDI name.
.
14
Section 3Style
3Style Guidelines
The Style Guidelines section covers the basic visual aspects used when creating
a report, such as font size, font style, spacing, and color. The reason to define
these styles is to create a similar look and feel for all of the reports that use these
style guidelines. This enables the layout of different reports (including productspecific reports, business partner reports, and customer-defined reports) to have
a consistent look. Consistency makes reviewing and understanding the
information within the reports easier for users, especially for new or infrequently
used reports.
For a report developer, it is also useful to understand the basic visual layout to
use before developing a new report. This section describes that layout, and
through fonts, colors and spacing, how that look can be achieved.
The easiest way to implement these guidelines is to first read this chapter to
understand the overall guidelines, and then use the following chapter, Creating
reports and report packages, to create reports using the supplied TCR style
package. The styles described in this section are provided within a library in the
TCR style package, and the templates and sample reports in the style package
are all designed using the TCR recommend report layout.
15
3.1 Document Layout
A report contains the following sections:
3.1.1
A header for company branding
A primary report title
Optional secondary titles to separate sets of parameters
Parameters used to generate the report
Information sections, which contain the content of the report
An optional description
A footer containing the generation date and time of the report and a
page number
Overall Document Style

The font-size specification is represented as a percentage. This allows the viewer
to increase or decrease the font size in the browser, with the report automatically
adjusting. Font sizes are based on the report document font.
Report document format:
Font: Verdana 70% (11pt)
Top margin: 0 inches
16
Right, left and bottom margin: 0.5 inch
When choosing page orientations for your report, consider the following:
3.1.2
Design for the Web first, with no page orientation, and a printing view
second. Web browsers offer a print feature which allows users to
adjust page orientation. The Web browser dynamically scales the
content to fit within the chosen page orientation.
Use a portrait page orientation for a report containing tables with a

small number of columns and a large number of rows. For example, a
typical 7-column, 500-row table consisting of a name, some numbers,
and a brief description fits well in this page orientation.
Use a landscape page orientation for a report containing tables with a

large number of columns, or when the data in the columns is
extremely long. For example, a 20-column, 100-row table consisting
of long titles, customer addresses, numbers, and descriptions fits well
in this page orientation. Remember that a table with a larger number
of rows requires more pages to print.
Overall Document Color Pallet

This chart shows the colors used for various report elements:
The primary accent color for report titles and table headers is dark blue
(#444E68). Table rows contain an alternating highlight color, which is a muted
grey (#F0F0F0). Table borders are black, which prints consistently on most laser
printers.
BIRT provides a feature to easily group information in a table. Background colors
separate group sections, and table group colors provide colors for as many as
three group levels. Background colors apply only to borders and header text. See
the grouping table section for more information on usage.
17
The table background that displays the data uses a white background, in order to
keep the focus on the data rather than on the sections. The order of the group
colors were chosen so that grayscale printing shows a sharp contrast in grays for
each section.
Color numbers are provided in both hexadecimal and RGB values. BIRT uses
the system color picker to choose new colors; therefore, on Windows systems,
you must enter the RGB values.
3.2 Report Header

The purpose of this section is to provide a space for customer logos. Company
branding is kept simple for reports, because the focus of the report should be the
content rather than the branding. By default, a small Tivoli logo appears flush
with the left margin, and an IBM logo appears flush with the right margin. These
two logos should align at the top of the header section; no additional text (such
as product names) should appear in this section. The report header is a part of
the TCR master page present in the TCR library.
3.3 Report Introduction

3.3.1
Report Title
The report title section displays the primary title of the report.
Primary report title format:
Font style: Bold
Font size: 150% (14pt)
Color: Dark blue (#444E68)
Border: 3 pixel bottom border in dark blue (#444E68), extending from

margin to margin
Justification: Left justification
Padding: 10 pixel top padding
3.3.2
Report Sub-Title
The report sub-title is an optional title used to further define the purpose of the
report. The sub-title is displayed directly underneath the border used to separate
the main title from the report.
Report sub-title format:
Font style: Normal
18
3.3.3
Secondary Title
Secondary titles are used to separate parameter sets. A secondary report title is
optional. The secondary title might provide a machine name or a work order
number. Not all reports need a secondary title; this space can be used by other
elements in the report.
Secondary title format:
3.3.4
Font size: Base font size (11pt)
Border: 15 pixel top, Bottom, dotted, 1 pixel
Indentation: 15 pixel left indentation
Parameters
The parameters section provides a place to show the parameter values the user
entered to generate the report. The parameter list is displayed using a simple
table layout using a four-cell grid by default. The first and third columns contain
parameter names, and the second and fourth columns show the corresponding
parameter values.
This section should be kept concise. Try to limit parameter inputs for a given
report to 10 or fewer. If more than 10 parameters are necessary, try to find
alternative display formats (for example, a comma-separated list, or categorized
parameter tables with titles using the secondary-title format).
Consider using the following methods to keep this section concise:
Display Boolean filters in a comma-separated list, rather than using icons

or text stating yes or no
Display dates in m d, yyyy format by default, adjusting for country

preference. E.g.,Aug 16, 2007
Display times in hh:mm AM/PM format by default, adjusting for country

preference. E.g, 10:45 AM
Include seconds in time values only when necessary
Do not use time-selection parameters that include seconds
Use a four-column parameter table layout for 10 parameters or fewer

(parameter, value, parameter, value)
Use a six-column layout when the total number of rows in the parameter
table exceeds 5 (a total of 10 parameters).
Allow parameters to span cells if necessary. Keep parameters that span

cells at the bottom of the table. Use this technique when displaying a
long string or a comma-separated list.
19
3.3.4.1
Parameter Section Style
The parameter section is padded by 15 pixels on the top and bottom of the table.
This provides some visual separation from the heading that surrounds the
parameter list. The table is also indented 15 pixels from the left margin. This
indentation creates an association with the report title, indicating that the
parameters are for the entire report.
Parameter name format:
Font: Base font (Verdana)
Font style: Bold
Cell padding: 5 pixel right cell padding; 3 pixel top and bottom cell
padding
Parameter value format:
3.3.4.2
Color: Black
Cell padding: 3 pixel top and bottom cell padding
Parameter Subsection Style

Some products might need to introduce subsections to the parameter area to
group a collection of parameters (for example, to provide vendor information on a
work-order report). Use parameter subsections only when necessary; an
alternative is to create a new information section with a title. The parameter
subsection contains a second parameter table following the same style as the
first parameter table.
20
Subsection format:
Border: 1 pixel bottom dotted border in dark blue (#444E68),

extending from left indent to right margin
Padding: 10 pixel top padding from previous table of parameters
Cell padding: 3 pixel padding is part of the cell padding in the second
parameter table
Indentation: 15 pixel indentation from the left margin
3.4 Information Sections

Information sections are the main part of the report document. Information
sections contain one or more of the following elements:
3.4.1
Section title
Charts such as line, bar, or pie charts
Standard tables of data
Grouping tables
Form elements
Section Title
The section title introduces the section. The title is optional on reports with only
one section.
Section title format:
Border: 1 pixel bottom border in dark blue (#444E68) extending from

margin to margin
21
3.4.2
Top padding: 20 pixel top padding if not provided from previous

section bottom padding
Bottom padding: 10 pixel bottom padding to the section content
Indentation: 15 pixel indentation for section content
Charts
Charts convey information about the data in a simplified format. Charts should
always precede any supporting table data.
BIRT generates a raster-based image of the chart when generating the report;
most Web browsers do not provide native scalar vector graphics (SVG). (Mozilla
Firefox is currently the only Web browser with some SVG support.) The highestquality format BIRT supports is the portable network graphic (PNG) image
format, which allows for maximum color depth. Selecting a JPEG may cause the
image to be fuzzy, depending on the quality setting used for conversion. Because
charts are graphics in the final reports and cannot be dynamically resized, the
font size for charts is a fixed point size.
Follow these general guidelines for charts:
Numbers should never be rotated.
Do not title charts; use section titles instead.
Include an axis title or legend to indicate what the data stands for, in
case the section heading does not convey that information.
Whenever possible, avoid rotated axis labels for either the X or Y

axis.
Avoid redundant information. For example, place numbers on a bar

chart either above the bar or in the legend, but not in both places.
Common chart format:
Font: SansSerif
Font size: 10pt
Font color: Black (#00000) black
Axis marker and rules color: Black (#00000) black
Legend placement: To the right of the chart, aligned with the top
(top-left alignment in BIRT) of the chart image
Axis label rotation: Long axis labels (15 characters or more) should
be rotated to a 45-degree angle on the vertical axis (normally the Yaxis) , and a negative 45-degree angle on the horizontal axis
(normally the X axis).
Indentation: Indent 20 pixels from the left margin to align with other
pieces in the section
Chart date formats:
All date formats should adjust to the country locale. To achieve this in
BIRT, any date field in a report should have the Data Type property of
the Data Item set to Date Time, and the Format DateTime property set
to one of the predefined values such as Unformatted, short date:
6/15/07 or any other selection except for Custom. All non-Custom
formats automatically format the date according to the country locale.
22
Dates spanning weeks in a single month should use the dd format and
axis labels that indicate the month (if it is not present in the section title).
Dates for a single week should use the day of the week (for example,
Monday or Tuesday) and an axis label to indicate the week (if it is not
present in the section title).
Chart time formats:
3.4.2.1
All time formats should adjust to the country locale.
Typically, times should be displayed in hh:mm AM/PM format. This is the

preferred time format when combining a date and time together as an
axis marker. Some countries use a 24-hour clock; the AM/PM indicator is
not required in those countries.
Hourly intervals spanning an entire day can use the hh format and an
axis marker to indicate the day in the locale-specific date format (for
example, April 4, 2007), if the day is not present in the section title.
Include seconds in a time only when necessary.
Include an indication of the time zone for all times (using the base font
style) below the chart or in the description section of the report.
Chart Colors
The following chart shows the colors to use for report charts:
23
For charts depicting status, assign to each status value the appropriate color
from the Status Charting Colors.
For charts not depicting status information, use the Normal Charting Colors.
When using these colors, start from the top and move down the palette. The
sequencing of colors is intended to maintain contrast between colors in a pie
chart even when printing in grayscale.
Note that these colors are not the standard colors provided by BIRT. The color
values are provided in hexadecimal and RGB values. BIRT uses the system
color picker to choose new colors; therefore, on Windows systems, you must
enter the RGB values.
Heat Chart Colors Palette:
Heat charts are generated to show patterns in data over a period of time. Heat
chart colors are slightly different from the status colors shown above. The Heat
Chart color palette is shown below:
24
3.4.2.2
Pie Chart
Additional pie chart formatting:
Use a 1 pixel white border between pie sections
One slice of the pie can fly out to emphasize a section
Section markers are optional. This information can also be provided in

the legend.
25
3.4.2.3
Bar Chart
Additional bar chart formatting:
3.4.2.4
Make bars as wide as possible.
Axis markers and grids are optional. Avoid using both in the same chart.
The axis marker border color is #959595 (r149 g149 b149).
The background color is #F0F0F0 (r240 g240 b240).
Instead of axis markers, a bar chart can use a grid in the light grey
(#F0F0F0) color.
Status Bar
Status bar charts may be horizontal. Status bars show the complete
status of a group of items, like schedule results for the last 24 hours..
The status colors should conform to the palette referred to in Section
3.4.2.1
Do not combine status bars into a chart. A status bar is good summary
of a collection of status for a single object type.
The legend can be placed below the chart plot instead of placing it on the
right.
Legend layout details:
Orientation: Horizontal
Position: Below
Anchor: Middle
Stretch: Horizontal
Direction: Left Right
26
3.4.2.5
Line Chart
Additional line chart formatting:
Axis markers and grids are optional. Avoid using both in the same
chart.
The axis marker border color is #959595 (r149 g149 b149).
The background color is #F0F0F0 (r240 g240 b240).
Instead of axis markers, a line chart can use a grid in the light grey
(#F0F0F0) color.
Series labels are optional, but required for accessibility. Use a thin
rectangle series marker with labels.
For line charts with too many data points, remove the markers and
series labels. Show the values in a tooltip.
27
3.4.2.6
Use legends for charts with multiple lines. Avoid using a legend for a
single-line chart; instead, use a section title, as shown in the above
example.
Area Chart
Additional area chart formatting:

There are two types of area charts, stacked and grouped. A stacked area chart
combines stacks the data series as shown in figure above. The combination
gives the user a third data point, a total. Stacked area charts are great ways to
express data throughput because it shows the user input rates, output rates, and
a total in one graph. Group area charts represent the data series with a zero
base line. Grouped area charts dont accurately reflect the data series for the
following reasons:
Data series typically get hidden behind each other
Users think they are looking at a stacked area chart
BIRT does not support staggering of the tails of the data series which
would indicate the base line of each series to the user,
For the above reasons, do not use grouped area charts. In cases where grouped
area charts are necessary, use a single (one chart, multiple lines) or multiple line
graphs (multiple charts, single lines) to summarize the data series.
Limit the number of data series in a stacked area graph. Too many
data series will compress the allotted spaces for each series.
Remember, the there is always an additional value being presented,
the total of the two areas. A good rule of thumb is nor more than 4
data series.
The color of the line is the same as that of the series taken from the
series palette.
28
3.4.3
Axis markers are recommended.
Do not use grid lines in area charts because the area chart will hide
the background grid lines from the user.
Do not use series labels.
Tooltips are recommended to show values at key points in the data

series.
For long legend entries, place the legend below the chart instead of
placing it on the right.
Standard Tables
Table format:
Borders: 2 pixel top and bottom border in black (#000000), extending

the entire width of the table
Margins: 20 pixels top and bottom margin on the table from previous
part of section. The section title provides a 10 pixel bottom padding
which results in a top padding of 0. The goal of this padding is to
provide white space between multiple elements in a section.
Table header format:
Font style: Bold
Font color: Dark blue (#444E68)
Cell Padding: 3 pixel cell padding
Borders: 1 pixel bottom border in black (#000000), extending the

entire width of the table
Alignment: Left alignment
Table data format:
Font color: Black
Padding: 3 pixel cell padding
Alignment: Right alignment for floats and integers based on the

decimal separator; left alignment for all other data types
29
Use status icons and a text string to describe the status, examples
shown below:
Do not use background colors for status.
Icons have a risk of unintended cultural meanings, as they are not

typically a translated element. Review any icons in your reports to
make sure their use is culturally appropriate for all users.
Avoid indicating units of measurement (such as MB or KB) on every

cell of the column. Instead, choose a common unit of measurement
for the entire column, and place the indicator in the header.
Highlight alternative rows of the data section of the table with grey
(#F0F0F0).
Table footer format:
Font style: Bold
Padding: 3 pixel cell padding top and bottom cell padding
Border: 1 pixel dark blue (#444E68) top border
Footer label should be left justified
Summary value should appear in the column as the information.
Multi Column Header format:
Use the table header format for the primary header label.
Font style: Italics
Padding: 3 pixel cell padding top and bottom cell padding
Borders: No border for first header row. 1 pixel bottom border in

black (#000000), extending the entire width of the table for the second
header row.
30
3.4.4
Alignment: First header row has top left alignment. Second header
row has left alignment.
Grouping Tables
BIRT allows grouping rows of data by attribute. For example, you can group a set
of switch ports on an Ethernet switch by company, product name, and router
name. These groupings appear as a forced hierarchy in the table of information;
in this example, the groupings are based on country, region, and then city.
Each group is accented with a different background color. The background color
wraps around the side of the table, providing a visual indicator of the hierarchy.
The colors provide a strong grayscale contrast between groups, preserving the
grouping in printed output.
The group table style is similar to the table style. Instead of the two-pixel black
border on the top and bottom of the table, there is a one-pixel black right-hand
31
border. The group background colors provide the necessary separation from
other elements in the report.
Avoid deep nesting of groups in a table. Consider other approaches, such as
using a section title or multiple tables to decrease the number of groups.
This diagram shows the measurements for group tables:
BIRT provides a header and footer row for each group. The visual border is
created by adding more empty cells to the table, specifying a background color.
The wrap-around effect is caused by adding 5-pixel cells to the table for each
group. The bottom wrap is caused by setting the group footer height to 3 pixels.
(See the template discussion for more information on creating the effect.)
The group heading is approximately 20 pixels in height; this is mainly based on
the height of the font, which slightly varies for each group. This goal is to keep
the height of the groups consistent; however, in some languages this area might
grow or shrink because of font substitution to produce the necessary glyphs.
The group title aligns with the next level group indentation. For example, the first
group title is indented 5 pixels from the left-hand side of the table to match the
next level. The table area is considered part of the last group, so no indentation
is required on the table.
Nesting too deep or only one group?
When the nesting of groups gets too deep, consider converting the first group
into a section title. Switch the format from the group 1 format below to the report
section format on the first group. You will also need to add a 15-pixel indentation
into the next group in the table. Using this method reduces the overall complexity
of the report and can provide clean separation between the groups.
This kind of format change also works well with only one group. Using BIRT
grouping tables in this manner helps to break the tables out into sections. In this
case, follow the table style on the nested data section by adding the top and
bottom 2-pixel line to the header and data section. This simplifies the overall
design of the report and produces a consistent layout for the report content.
Group level 1 format:
Font: Verdana
Font style: Bold
Font color: White
Background color: Dark medium blue (#7E90BF)
32
Indentation: Text indents 5 pixels from the left-hand side of the table
Footer height: 3 pixels
Footer background color: Dark blue (#7E90BF)
Font: Verdana
Font style: Bold
Font color: dark blue (#444E68)
Background color: Light blue-grey (#ABC3FF)
3.4.5
Font: Verdana
Font style: Bold
Font color: white
Background color: Medium blue (#94ABE0)
Form Elements
Some reports become invoices or other printed contract documents. This type of
document typically requires a signature, and possibly a place for recording the
progress of an order. Form elements are optional. This example shows two form
elements, one without a title and one with a title:
Section format:
Border: 1 pixel black border on all sides
Padding: 10 pixel internal padding on all sides
Indentation: 15 pixel indent from the left-hand document margin
Width: Section extends from indent to right hand document margin
33
Margin: 20 pixel top margin from previous section if not provided by

previous section
Section title format:
Font style: Bold
Padding: 10 pixel bottom padding
Entry field format:
Font color: Black
Border: Black 1 pixel bottom border on the entry space
Label: Use initial caps, ending with a colon
Padding: 10 pixel top and bottom padding on the cell
Remember that handwriting always takes more space than the label;
leave as much room as possible.
In grid layout, the first column is the label, and the second column is the
entry space.
Avoid using more than two entry fields in the same row.
3.5 Report Description

Report descriptions are optional and should be used only when necessary to
explain the content of a complex report.
Description format:
Font color: Black
Width: Text section extends to the left and right margin of the document
3.6 Message Dialog Boxes

A dialog box is used to indicate that the generation of the report failed. BIRT
handles many of these error cases by generating some red text with an
explanation of the problem at the bottom of the report, but it often is a stack trace
34
and a technical error message. You can use a dialog box to present users with
information about problems in a more nontechnical fashion.
A common use of the message dialog box, used within the templates, is to
provide a message dialog box when no data was returned for the report, rather
than generating an empty report.
Another example of a dialog box is in the Tivoli Storage Manager Express Daily
Status report. This daily status report is sent by e-mail to the administrator, giving
a daily summary of backup operations. If the product is about to reach its
maximum database size, a dialog box appears with a message. This dialog box
also suggests actions to take, (such as upgrading to the enterprise product or
creating another TSM Express server). This gives the user a clear indication of
the problem and what actions might correct the issue.
This illustration shows warning and error message dialog boxes:
For information messages in a report, follow the description format. Critical error
messages should display an error message number in addition to the error text
so users can look up more information about the message. The message should
suggest corrective actions for the user to take; remember that these messages
appear in a report which might be sent via e-mail or posted on an internal Web
site, so the reader may not be logged in to an administrative console. (The
corrective action could be as simple as logging in to the administrative console to
view the event.)
Message Box Format:
Layout: Two-column format, with the status icon representing the

severity of the message on the left and message text on the right
Background color: Light blue grey (#F0F0FF)
Border: 1 pixel border in medium blue (#7E90BF)
Padding: Internal top and bottom padding is 3 pixels
Width: 95%
Indentation: Left margin is an additional 20 pixels from the section

indentation (40 pixels from the left margin)
Placement: Dialog box should appear right after the report title
Close dialog link: The link style should follow the user settings. This
link causes the message dialog box to close; the link should not appear
in PDF output.
Status Icon Format:

35
Padding: Left and right padding is 10 pixels
Icon: Error status icon for error (message number ending in E), severe
(message numbers ending in S), and diagnostic (message number
ending in S) error messages; Warning status icon for warning messages
(messages number ending in W)
Message Number Format:
Font style: Bold
Message Text:
3.7 Collapsible Sections
Details can be important, but some details might not add much to the
presentation of a report to upper management. Often, tables in a report provide
very detailed information mainly used by technical personnel, administrators, or
individual workers, while the manager or executives are looking primarily at
summary information. To create a single report that includes both summaries and
details, consider using collapsible sections.
A collapsible section should not be used in a small report with a single section
and chart. However, when displaying multiple charts in multiple sections,
collapsible sections can help with navigation and display of the report on the
Web. (Collapsible sections should always be expanded in PDF output, or when
printed.)
Collapsible Section Format:
Expanding/collapsing control: Twisty icon to the left of the text
3.8 Report Footer

The report footer is as simple as the header. The footer contains the report
generation time aligned with the left margin of the document. The time field
should use a locale-sensitive format which includes year, month, day, hour,
minute and 3-character time zone. The page number (out of the total number of
36
pages) is aligned with the right margin of the document. Both text elements use
the base font and font size of the document (Verdana 11pt). The report footer is
also a part of the TCR master page in the TCR library.
3.9 Sample Reports Layouts

This sample shows a report with parameters and grouping tables:
This sample shows a report using a parameters subsection and forms:
37
This sample shows a report with table footers and a message dialog box:
38
39
Section 4Creating
4Creating reports and report packages
4.1 Introduction
This section covers how to create a report using TCR templates and styles and
how to create a file structure, generally in a BIRT project, that can easily be
imported into Tivoli Common Reporting. The file structure, containing report
designs and their associated resources, is referred to as a report design package
in the Tivoli Common Reporting Users Guide. (A report design package is one of
two types of report package.)
4.2 Tivoli Common Reporting Style Package

Included with the TCR component is the TCR style package which contains
templates, libraries and samples used to create TCR reports.
4.2.1
Style Package Description

The structure of the TCR style package is shown below:
Resources: The resources folder contains images, libraries, .properties

files and scripts to be used in the reports. The tcr_common directory in
resources contains the following directories:
o
images: The images folder contains the images used by the

templates, such as logos and status icons. Guidelines for using
these images are explained in the sections below.
lib: The lib folder contains the TCR library:

TivoliCommonReporting_v<number>.rptlibrary. The library
stores themes (collections of styles), reusable report items, and
the master page.
properties: The properties folder contains the .properties files

used for globalization. Each report can be associated with a
single .properties file. This folder contains .properties files used
to globalize the templates.
scripts: The scripts folder contains JavaScript scripts used by

the report templates and samples. These scripts contain
reusable functions that can be used by any report.
.
40
Templates: The templates directory contains the Tivoli Common

Reporting templates. A template provides the structure for a
standard report layout, containing visual report items that appear in
the report layout, data sources, and data sets, and a master page
layout. A template uses one or more libraries. A template is a static
framework on which a new report design is built; a report design can
therefore be derived from only one template. When changes are
made to a template, report designs that are based on that template
do not automatically reflect the changes to the template. The
templates provided in Tivoli Common Reporting style package are:
TCR_Table
TCR_Chart
TCR_ChartTableCombo
TCR_GroupTable(1_group)
TCR_GroupTable(2_groups)
TCR_GroupTable(3_groups)
Samples: The samples directory contains sample report designs

to demonstrate basic design features and best practices that can be
used in reports. The samples provided with the Tivoli Common
Reporting style package are as follows:
CascadingParameters
ChartsWithDrillthrough
DateRangeParameters
DynamicChartDimensions
DynamicColumnSort
DynamicQuery
DynamicTableColumnsAndVisibilityControl
ExpandCollapseSections
MessageDialogs
ParameterValidation
QuickLinks
StatusBasedColoringOfCharts
TableFooterWithTotals
TableUsingStatusIcons
TableWithDrillthrough
41
4.2.2
Importing Style Package into BIRT
Unzip the Tivoli Common Reporting style package

(TCRStylePackage_V<n>.zip) in a working directory.
Create a new TCR project:

1. File -> New -> Project.
2. In the New Project window, expand Business Intelligent and
Reporting Tools and select Report Project under it. Click Next.
3. Type TCRStylePackage_V<n> in the Project Name field. Click
Finish.
Import the TCR style package into the project:

1. In the navigator view, right-click on the project you created in the
previous step. Select Import from the menu.
2. In the Import window, expand General and select File System.
Click Next.
3. Browse to select the folder in which you have unzipped the TCR
style package. Click Finish.
4. In the navigator view, expand your project folder. You should see the
resources, templates and samples folders.
4.2.3
Creating your BIRT Project
Create a new project for your products reports. This project will be the
basis for your report package.
1. File -> New -> Project
2. In the New Project window, expand Business Intelligent and
Reporting Tools and select Report Project under it. Click Next.
3. Type <product name> Reports in the Project Name field. Click
Finish. For example, TBSM Reports, ITM Reports.
4. Copy the resources folder from the TCR project to the product
reports project.
5. Within the resources folder, create another folder named according
to your product name. This folder will have the same structure as the
tcr_common directory. Use this folder for your product-specific
resources such as status icon images, a library to store your data
source information, .properties file for your reports, and scripts used
in your reports. An example is shown in the figure below.
6. In the lib folder in <product name> Reports/resources/<product
name>/lib, create a library called <product name>.rptlibrary. In this
library, under data sources, create the primary data source that your
report will use. The datasets created in the report designs will access
this data source. Other reusable report items specific to your product
reports will also be created in the library.
42
4.2.4
Modify the BIRT settings for resources and templates

1.
Go to Window -> Preferences.
2.
Expand Report Design.
Select Resource and enter the location of the resources

folder in the project: <workspace>/ <product name> Reports/
resources.
Select Template and enter the location of the templates

folder in the project:
<workspace>/TCRStylePackage_V<n>.\templates. This makes
the templates in the TCR project available in the New Report
wizard so that report designs can be created based on these
templates from anywhere in the workspace.
4.2.5
Report Naming Convention

All reports are created directly under your product directory. The recommended
naming convention for .rptdesign files is as follows:
43
<product name>_<category>_<report name>

Replace <product name> with the abbreviated name of your product, and
<category> with the category under which the report type falls. The category is
optional; valid categories are:
Availability
Assets
Utilization
Events
Summary(Daily, Weekly,Monthly)
Provisioning
Comparisons
Compliancy
Status
Trouble Shooting
Forecasts/Prediction
Replace <report name> with the name of the report that will be displayed as
your report title.
The following are examples of report names following this convention:
itm_utilization_cpu.rptdesign
tbsm_availability_summary_chart.rptdesign
4.3 Tivoli Common Reporting Library

The Tivoli Common Reporting library stores reusable report components. The
library is contained in the TivoliCommonReporting_v1.0.rptlibrary file, in the
resources/tcr_common/lib folder.
The library is a dynamic component of a report; if the library changes, report
designs are automatically synchronized with the changed library. Therefore,
these changes can be propagated easily to all report designs that use that library.
Libraries may contain data sources, data sets, report parameters, report items,
master pages and styles (organized in themes). A report may use more than one
library.
The Tivoli Common Reporting library currently contains report parameters, report
items and a single theme composed of all the recommended formatting styles.
The structure of the library can be viewed in the Outline view or Library Explorer
view of the Eclipse/BIRT designer.
In the Eclipse/BIRT designer, report components can be dragged from the
Library Explorer view directly into a report design layout. The effect of this
operation is to create a reference to the library object in the report design. Some
properties of the report component can be customized in the report design. If the
underlying object changes in the library, you should ensure that the change is
applied to your report design by clicking in the Layout view of the report and
selecting Refresh Library from the context menu.
44
45
4.3.1
TCR Theme
A theme is a collection of styles. A style is used to customize the appearance of
report elements, specifying formatting properties such as alignment, color, font,
size, background colors, and borders. BIRTs formatting properties follow the
CSS specification.
One theme is currently defined in the Tivoli Common Reporting library:
TCRTheme_v1. This theme contains all of the Tivoli Common Reporting
recommended formatting styles. The list of available styles is visible in the
Outline view of the library:
Some examples of styles used in the TCR Theme are report, main-title, tableheader-cell, parameter-table etc. All styles are described in Section 5.
For the TCR Theme to be available to a report design, it must be referenced as a
general property of the report. If you create a report based on one of the TCR
templates, it will include a reference to the TCR Theme. If you must add it
manually, you can do so in the report general properties editor:
Note that the theme reference includes the library name prefix.
46
4.3.2
Report Parameters
The Tivoli Common Reporting library contains a reusable report parameter
group, called Date Range. Within this parameter group, there are 3 individual
parameters, Begin Date, End Date and Report Period. The Date Range
parameter group is designed to allow the user to quickly select a standard report
period, for example, the last 7 days, or to enter a specific begin and end date for
the report. The Begin Date and End Date are DateTime parameters. The Report
Period parameter contains a predefined selection list of date ranges for a report.
The selection list allows choosing user-friendly date ranges such as Last week
or Last 90 days. It is possible to use the parameters without using the entire
Date Range parameter group, and DateRangeParameters sample report
provides such an example by only using the Report Period parameter..
4.3.3
Report Items
The Tivoli Common Reporting library contains the following reusable report
items:
4.3.4
Report Title: Text item implementing the main-title style.
Secondary Title: Text item implementing the secondary-title style.
Section Heading: Text item implementing the section-title style.
Report Period, Begin Date, End Date: Text and Data items that
implement 3 fields to display date ranges in the Parameters section of a
report. Report Period displays the same text that is presented to the
user in the Report Period report parameter, described above. Begin
Date and End Date format the actual start and end dates for the Report
Period date range. All 3 fields are globalized to enable country
localization. The globalized keys and values in the
DateRangeParameters.properties file must be copied into a .properties
file for a report to provide the globalized values for the report period.
Description: Grid that can be inserted into a report to display a

description of the report. The grid contains a Text item that implements
description-text style.
Error, Information and Warning Message Dialog: Grids containing an

icon for the type of message and text describing the error, information, or
warning. The information message is used in every report when no data
is returned by the result set.
Images: All images present in the tcr_common/images folder are report

image items that can be dragged and dropped onto a report design.
TCR Master Page

The master page in the TCR library is called the TCR Master Page. Any changes
to the logos in the header are reflected through all the report designs using that
library.
The master page contains the header and the footer. The header contains the
Tivoli banner and the IBM logo. The footer contains the timestamp of report
generation and the page number.
The recommended way to use master pages is make a copy of the TCR Master
Page and name it <product> Master Page in your library. You can then refer to
this copy from your report design. In order to do this, open your report design in
47
the layout editor. Open the library explorer, Select

<product>lib/<product>.rptlibrary/MasterPages/<product> Master Page and drag
it to the MasterPages folder in the Outline View of the report design. Remove the
existing master page from the MasterPages folder.
4.4 Report Templates

A report template has the following layout, as described in section 5.1. See
Chapter 5 for description of styles used in our library.
In order to understand the structure of a template, open any template in the
Layout editor and look at the items in the Body of the report design from the
Outline view.
Header: The topmost portion of the report is the header. It contains the
Tivoli banner and the IBM logo. This is visible in the master page.
Report introduction: The report introduction is a mandatory section that

contains the following elements:
o
Report Title: The main title of the report.
Secondary Title or Parameter Group Heading (optional)
Parameter Table: A grid containing parameter names and values

which are passed to the report at run time. The parameter values
are required for report generation.
A report can have more than one parameter table, with each additional
parameter table placed below the previous table. To add a second
parameter table, select the second row of the report introduction grid that
contains the parameter table. Right-click and select Insert -> Row ->
Below. Copy the contents of the second row into this new third row, and
modify the data accordingly.
Sections: Report content is placed in information sections. Each section

is a grid in which the first row contains the Section Heading or Sub-title
and the second row contains the report content. The content might be a
table, a chart, or a combination of both, with related data.
Report description: This is a text area providing a brief description of

the purpose of the report.
Footer: This contains the date and time when the report was generated,
as well as the page number. This is visible in the Master Page.
48
Header
Report
Introduction
Section 1
Section 2
G
ri
Report
Description
Footer
4.4.1
Using TCR Templates

1. Right-click on the <product-name> Reports project in the navigator
view. Then click File -> New -> Report.
2. Enter the report name and then click Next.
3. Select one of the TCR templates listed (for example, TCR_Table
template). Then click Finish.
4. Bind a .properties file to your report:
a. Create a new .properties file in
resources/<your_productname>/properties directory called
<your_report_properties_filename>.properties. Alternately, you
can make a copy of the .properties file associated with the
template (e.g., TCR_Chart.properties) in
resources/tcr_common/properties directory, put it in your
properties directory, and rename it to
<your_report_properties_filename>.properties.
b. Change the .properties file setting to use your newly defined
.properties file. In order to do this, go to the Properties Editor
view, select the Resource entry and change the name of the
resources file from tcr_common/properties/<template>.properties
49
to <your_productname>/properties/<your report .properties file

name>.
5. Go to the layout view. You should see three or four grids.
o
Grid 1 contains the Report Introduction:
Row 1 contains the report title. The report title is a text

element using the main-title style.
Row 2 contains the parameter table with an optional

secondary title.
The parameter table is a grid using the paramtable style. It contains name-value pairs. The
parameter names are text elements using
param-name style and parameter value are
data elements using the param-value style.
The secondary title is a text element using the

secondary-title style.
In order to add more parameter tables, select Insert ->

Row -> Below from the pop-up menu and copy the
contents of Row 2 to Row 3.
Grid 2 is the first section of the template, which contains the

following:
Row 1 contains the section subtitle. This is a text

element using the section-title style.
Row 2 contains report elements representing the data or

the main content of the report. This can be a chart or a
table. The details of the different types of charts and
tables and how to use them will be described in the
following sections. It also contains a message dialog that
is displayed when no result is returned by the query.
Grid 3 in templates that have 4 grids will contain another section

similar in structure to grid 2
Grid 3 or 4 (the last grid in the report) contains the Report

Description. This is a text element using description-text style.
6. Click any text element in the report layout to change its contents. In the
Properties Editor, select the Localization option, then click on the
button next to the Content Key textbox. This will open up the Select Key
dialog. Choose a key in the list or add a new key-value pair. Click OK.
The text will show up on the text element.
7. Select and delete elements that you do not wish to use. For example, all
the reports contain an optional report description at the bottom of the
report. If you do not want a report description, select the grid and delete
it.
8. To modify the report description:
a. Double-click on the text element in Row1 of the last grid.
b. Enter the report description text.
9. To add parameters, follow these steps for each parameter:
50
a. Add the parameter to Report Parameters in the outline view or

modify the existing parameters (Param1, Param2 and Param3
which are present in all templates by default)
b. Click on the text element that contains the param-name, and
select the localization option in the property editor to set the
value that is displayed. Optionally, the localization can be done
by directly entering the parameter key and its tooltip in an HTML
format containing a title field for the tooltip. This format requires
using the getNLS function in the ReportUtils script to localize the
value. The chart template shows a parameter with this format of
entry.
c.
Double-click the data element that contains the param-value,

and then click the button with three dots beside the text box.
Select the report parameter you want to point to under Report
Parameters -> All or the sub-category that you may have
created. Alternately, you can delete the existing param-value and
drag and drop your new report parameter from the Outline view
to the layout view.
10. To add data sources and data sets:

a. Create your primary data sources in resources/<product
name>/lib/<product name>.lib. Configure your JDBC data source
using the information provided in Section 2.5.4. More information
on data sources can be obtained from the BIRT site.
b. Create your datasets in the report design. Under dataset, click
New Data Set. Enter an appropriate data set name and select
the data source you wish to use.
c.
On clicking Next, the Data Set Editor opens up, where SQL
queries can be entered. All the tables under the connected data
source show up. You can select column and table names by
clicking on them in the tree view of the data source. To create
dynamic queries refer to the DynamicQuery sample report.
Queries can be bound to parameters defined in the reports.
51
11. Double-click on any report element to open the element editor for that
object. To modify tables and charts follow the instructions in the following
sections.
4.4.2
Using the Table Template

The table template contains two sections. The first section contains a simple
table without any grouping. The second section contails a table with multi-column
headers. The template looks like this:
52
Follow the instructions in the previous section, Using TCR Templates, to modify
the Report Introduction, Section Heading and Report Description. If you are not
using multi-column headers, delete Section 2. Else delete Section 1.
The second row of Grid 2 of this template contains a table that uses the tablewithout-group style. The header cells uses the table-header-cell style. The
details row uses the table-details style. If you want to use a footer for the table,
use the table-footer-cell style.
The second row of Grid 3 of this template contains a table that uses the tablewithout-group style. The first header cells use the table-header-cell style. The
second header cells use multi-column-heading-secondary-header style. The
53
font has been forced to disable bold inherited from the default table-header-cell
style. Also a bottom border of color white (#FFFFFF) is added to the first header
row cells. The details row uses the table-details style. If you want to use a
footer for the table, use the table-footer-cell style.
To modify any of the table contents:
1. Add your data source and data set to the report design. If you are using
scripts to retrieve your data, continue to do so. Copy and paste your
scripts from your existing reports. In the TCR templates, the data source
is in a common library called the product library. It is recommended to
put your products main data source in a common library so that changes
can be made at one place.
2. If you have parameters that alter the database query for your report, link
them to the query. First, double-click your dataset. Then go to
Parameters, select a parameter, and link it to the report parameter by
clicking on the Link to Report Parameter column and entering the name
of the parameter to link to.
3. Select the table. In the property editor select the Binding tab. In the Data
Set field, select the dataset with which you want to associate your table.
When prompted about clearing existing data field information, click Yes.
4. Delete the existing data information from the details cell in the table. Go
to the Outline view. Select the column in the data set that you want to
display in the table. Drag and drop that data to the column.
5. Change the text in the table header to match your new column heading.
You can provide a tooltip for each column heading to explain what data
each column contains by using the title attribute in the div tag. Use the
property editor localization option to set the value.
6. Insert or delete columns to the right or left as needed. For a new column,
insert a text element in the column header. To do this, click on the cell,
click on Text in the Palette view on the left and click on the cell again.
Enter the column header name using the property editor localization
option to set the value. Optionally, you can add a tooltip and text directly
into the field, using the getNLS script function to localize the value, in a
similar format as for parameters above. (See the parameters in the chart
template for an example.) Make sure your new column cells use the
correct styles: the header should use TCRTheme_v<n>.table-headercell, and the details use TCRTheme_v<n>.table-details style.
If you have created a table from scratch, follow these steps to apply the correct
styles:
1. Apply the table-without-group style to the table
2. Select all cells in the table header by clicking on one cell and then
dragging the + sign across the other cells in the header. Note that if you
select the entire header row by clicking on the table outline, it will select
the header row as a whole and will not apply the style to individual cells.
Right-click and select Style -> Apply Style -> TCRTheme_v<n>.tableheader-cell.
3. Select all cells in the table details by clicking on one cell and then
dragging the + sign across the other cells in the details row. Note that if
you select the entire details row by clicking on the table outline, it will
select the details row as a whole and will not apply the style to individual
54
cells. Right click and select Style -> Apply Style ->
TCRTheme_v<n>.table-details.
4.4.3
Using the Group Table Templates

There are three group table templates, one for each level of grouping. Grouped
tables can be formatted either with or without sections. If you use sections, the
topmost group looks like a section, and the lower groups is a table. If you do not
use sections, all groups are visible in the same table.
The decision to use sections or not depends on the scenario; examples of both
approaches are shown below. In these examples, the customer information is
grouped in three levels: country, state, and city.
In the first figure (a grouped table with sections), the country grouping looks like a
section. The rest of the table appears as is with appropriate TCR styles.
In the second figure (a grouped table without sections), the country grouping also
appears as a part of the table with appropriate style.
55
the Report Introduction, Section Heading and Report Description.
The second row of Grid 2 contains a group table with up to 3 levels

of grouping, depending on which template you chose to start with.
o
The table uses the group-table-with-section style
The first group of the table uses section style. The header
text for this group uses section-title style.
The second group uses table-group-1 style
The third group uses table-group-2 style (and so on).
The table-group-<n> style is applied to header cells, footer

cells, and margin column cells.
The group-data style is applied to the details row.
Grid 3 is the second section of the template, which contains the

following:
56
The grid contains a group table with up to 3 levels of

grouping, depending on which template you chose to start
with. The table uses the group-table-without-section style.
The first group of the table uses table-group-1 style.
The second group uses table-group-2 style
The third group uses table-group-3 style (and so on).
The table-group-<n> style is applied to header cells, footer

cells and margin column cells.
The group-data style is applied to the details row.
To modify the table contents, follow these steps:

scripts from your existing reports.
2. If you have parameters that alter the DB query for your report, you need
to link them to the query. First, double-click your dataset. Go to
Parameters, select a parameter, and link it to report parameter by
clicking on the Link to Report Parameter column and entering the name
of the parameter to link to.
3. Select the table. In the property editor select the Binding tab. In the Data
Set field, select the dataset with which you want to associate your table.
When prompted about clearing existing data field information, click Yes.
4. Delete the existing data information from the details cells in the table. Go
to the outline view. Select the column in the data set that you would like
to display in the table. Drag and drop that data to the column.
5. Change the text in the table header to match your new column heading.
Provide title for all column headings to explain what data each column
contains.
6. Grouping: select the table, right-click on the group header and select
Edit Group. Enter grouping information here.
7. In the layout for a group-table-without-section, style table-group-<n> is
applied to a header of level n (for example, if there is one level of
grouping, table-group-1 style is applied). There is a column on the left
hand side of width 5 px. This provides the required indentation for the
group. Style table-group-<n> is also applied to all of the cells in this
column. The column is selected in the table; in the General section of the
property editor, its width is fixed at 5 pixels. The footer is 3 pixels in
height. The footer row is selected, and in the General section of the
property editor, the height of 3 pixels is specified. Style table-group-<n>
is applied to it.
8. For every subsequent grouping, use the same method. An extra column
is added to the left, and all the cells after the last column belonging to the
previous group header are merged. For example, to create level 3 of
grouping, the third column of the table is applied the table-group-3 style
and the width of the entire column is fixed at 5 pixels. The cells in the
header row starting from column 3 are merged if there is only one
heading.
9. Insert or delete columns to the right or left as needed. For a new column,
insert a text element in the column header. To do this, click on the cell,
57
click on Text in the Palette view on the left, and click on the cell again.
Enter the column header name using the property editor localization
option to set the value. Optionally, you can add a tooltip and text directly
into the field, using the getNLS script function to localize the value, in a
similar format as for parameters above. See the parameters in the chart
template for an example to do this..
4.4.4
Using the Chart Template

The Chart template contains four charts in the first section of the report. All of
the charts are in a single cell of the table; you can choose which chart format you
want to use and delete the other three. The four provided chart formats are pie
chart, bar chart line chart and area chart.
58
the Report Introduction, Section Heading and Report Description.
Row 2 of Grid 2 contains a single cell, containing all four chart formats with the
cell. Choose which chart format you want to use. Click on the other charts in the
editor to select them, and then press the Delete key to delete them.
If you chose to use a Pie Chart, modify the chart contents as follows:
2. Double-click on the chart to open the Chart editor. Go to the Select Data
tab. Select the data set you want to use by clicking on the Use Data Set
radio button and selecting the data set from the drop down box. The
data you selected is available for preview.
3. Drag the column header you want in the value to the Slice size
definition on the left.
4. Drag the column header you want as the category to the Category
Definition.
5. You can set an optional grouping in the Optional Grouping section on
the right.
6. The slice outline is white in color and 1 pixel by distance. This
information is available in Format Chart tab -> Series -> Value Series.
59
7. Add interactivity to your chart data. Click on the interactivity button on

the value series, choose event Mouse Over and action Show Tooltip.
Enter the tooltip text that you want to show.
8. Do not change the colors on the series palette. For status based
coloring refer the the StatusBasedColoringOfChart sample.
9. All text on the chart should use the default chart font. Only axis titles are
bold. Use the localization options in the chart editor to change the fixed
text information.
If you chose a Line Chart, modify the chart contents as follows:
2. Double-click on the chart to open the Chart editor. Go to the Select Data
tab. Select the data set you want to use by clicking on the Use Data Set
radio button and then selecting the data set from the drop down box.
The data you selected is available for preview.
3. Drag the column header you want in the value to the Value (Y) Series
on the left.
4. Drag the column header you want as the category to the Category (X)
Series.
5. You can set an optional grouping in the Optional Y Series Grouping
section in the right.
6. All labels along the X axis and Y axis should use the chart default font. If
the strings are longer than 10 characters, they should be rotated to an
angle of 45 degrees. To rotate a label, go to the Format Chart tab ->
Chart Area -> X-Axis or Y-Axis. Click the Text Format button. In the
Label section, click the button with the 3 dots next to the Font text box.
In the rotation area, turn the needle to -45 degrees for the horizontal
axis (normally the X-Axis) and 45 degrees for the vertical axis (normally
the Y-Axis). This will result in the text being aligned at the correct angle.
7. Adding axis markers: Add markers to denote the acceptable range for
the data. Go to Format Chart tab -> Chart Area -> Y-Axis. Click the
Markers button. A range is already added for in the template. In the
Marker Properties section, enter the start value and end value of the
range to specify your acceptable limits.
8. To add interactivity to your chart data, click on the Interactivity button
on the value series; choose event Mouse Over and action Show
Tooltip. Enter the tooltip text that you want to show.
9. Do not change the colors on the series palette. For status based
coloring refer the the StatusBasedColoringOfChart sample
text information.
If you chose a Bar Chart, modify the chart contents as follows:
60
2. Double click on the chart to open the Chart editor. Go to the Select
Data tab. Select the data set you want to use by clicking on the Use
Data Set radio button and then selecting the data set from the drop-down
box. The data you selected is available for preview.
on the left.
Series.
6. All labels along the X axis and Y axis should use the default chart font. If
In the rotation area, turn the needle to -45 degrees for the horizontal axis
(normally the X-Axis) and 45 degrees for the vertical axis (normally the
Y-Axis). This will result in the text being aligned at correct angle..
7. To add interactivity to your chart data, click on the Interactivity button on
the value series, choose event Mouse Over and action Show Tooltip.
Markers button. A range is already added for demonstration purposes. In
the Marker Properties section, enter the start value and end value of the
9. Do not change the colors on the series palette. Refer to Chapter 5 for
series palette. For status based coloring refer to the
StatusBasedColoringOfChart sample.
text information.
If you chose a Area Chart, modify the chart contents as follows:
12. Double-click on the chart to open the Chart editor. In Select Chart
Type section, Select Sub-type is stacked by default. You can change
that for your needs. Go to the Select Data tab. Select the data set you
want to use by clicking on the Use Data Set radio button and then
selecting the data set from the drop down box. The data you selected is
available for preview.
on the left. You can add multiple series by adding new Series from the
drop down list and then dragging the column header over to the series
text box.
Series.
61
In the rotation area, turn the needle to -45 degrees for the horizontal
axis (normally the X-Axis) and 45 degrees for the vertical axis (normally
the Y-Axis). This will result in the text being aligned at the correct angle.
17. To add interactivity to your chart data, click on the Interactivity button
on the value series; choose event Mouse Over and action Show
Tooltip. Enter the tooltip text that you want to show.
18. Do not change the colors on the series palette.
19. Go to Format Chart -> Series. Rename the series.
20. Click on each individual series. Select the color of the line to match the
corresponding color in series palette representing the series.
text information.
If you chose any other chart type supported by BIRT (other than line chart, bar
chart, or pie chart), do the following:
1. Add your data source and data set to the report design
2. Copy one of the TCR charts (bar chart) to your cell.
3. Double-click on the chart to open the Chart editor. Go to Select Chart
Type tab. Select the chart type you wish to use.
4. Go to the Select Data tab. Select the data set you want to use by clicking
on the Use Data Set radio button and then selecting the data set from
the drop down box. The data you selected is available for preview.
on the left. Add multiple value series as required by your chart type or
add appropriate data.
Series.
In the rotation area, turn the needle to -45 degrees for the horizontal axis
(normally the X-axis) and 45 degrees for the vertical axis (normally the Yaxis) . This will result in the text being aligned at correct angle..
62
Markers button. A range is already added for in the template. In the

Marker Properties section, enter the start value and end value of the
10. To add interactivity to your chart data, click on the Interactivity button on
the value series; choose event Mouse Over and action Show Tooltip.
11. Do not change the colors on the series palette. If your chart color has
changed go to the XML source of the report design, look for <series
palette> and replace the contents of that tag by:
<SeriesPalette>
<Entries xsi:type="attribute:ColorDefinition">
<Transparency>255</Transparency>
<Red>34</Red>
<Green>89</Green>
<Blue>114</Blue>
</Entries>
<Red>72</Red>
<Green>153</Green>
<Blue>119</Blue>
</Entries>
<Red>221</Red>
<Green>205</Green>
<Blue>93</Blue>
</Entries>
<Red>199</Red>
<Green>134</Green>
<Blue>57</Blue>
</Entries>
<Red>152</Red>
<Green>96</Green>
<Blue>48</Blue>
</Entries>
<Red>141</Red>
<Green>134</Green>
<Blue>142</Blue>
</Entries>
<Red>131</Red>
<Green>162</Green>
<Blue>176</Blue>
</Entries>
<Red>187</Red>
63
<Green>217</Green>
<Blue>0</Blue>
</Entries>
</SeriesPalette>
For status-based coloring, refer to the StatusBasedColoringOfChart
sample.
text information.
4.4.5
Using the Chart Table Combo Template

The Chart Table Combo template contains three charts in the second row of the
first section of the report. All of the charts are in a single cell of the table.
Choose which chart format you want to use, and delete the other two. The three
provided chart formats are pie chart, bar chart and line chart.
The template also contains a table in the third row of the first section. Use this
template to show related data in chart and tabular format. However, if you are
trying to display unrelated data on a chart and a table in the same report, use
different sections.
The following layout contains a chart table combo template where the pie chart
was the selected chart type.
64
Row 2 of Grid 1 contains a single cell, containing all three chart formats with the
cell. Choose which chart format you want to use. Click on the other charts in the
editor to select them, and then press the Delete key. Row 3 contains the table.
To modify the chart contents, follow the instructions given in the Using the Chart
Template subsection.
To modify the table contents, please follow the instructions given in Using the
Table Template and Using the Group Table Templates subsections.
4.5 Sample Reports

4.5.1
TableWithDrillthrough Sample Report

This report contains an example of how a table can contain a link to a drillthrough report.
In this sample, the table drills through (links to) the
TableWithDrillthrough_subreport.
65
The drill-through link is performed on the CUSTOMERNAME field. By opening

the properties for the CUSTOMERNAME field and clicking on the Hyperlink
property, you can see how to set up a link to a drill-through report and pass the
CUSTOMERNAME value.
Click on the on the hyperlink to open the Hyperlink Options window.

66
In the drill-through report, the CUSTOMERNAME field must be defined as a

parameter and then used to modify the SQL query so that only the information
needed by the drill-through option is needed.
To understand how the CUSTOMERNAME field is used in the drill-through
report, open the Customer Details dataset in the drill-through report and look at
both the query string containing the "?" value, and the parameter value
associating the input parameter with the "?" value in the query.
4.5.2
ChartsWithDrillthrough Sample Report
67
The ChartsWithDrillthrough report contains a pie chart, line chart, and bar chart
(their visibility controlled by parameters), with the option to drill through to a subreport by clicking on values.
The master report looks like this:
Clicking on a pie-chart value drills through to the

ChartsWithDrillthrough_subreport report:
68
To see how interactive features are added to the chart, double-click the chart. Go
to the Format Chart -> Value (Y) Series. Click the Interactivity button.
Select Event Mouse Click and Action Hyperlink. Click Edit Base URL button.
Note that the Drill-through radio button has been selected. The details of the
sub-report are provided. In this report, the sub-report is
ChartsWithDrillthrough_subreport. The report parameter of the drill-through
report maps to a row value of the chart. The chart plots Total Orders grouped by
product line. On clicking on a product line, the Product Details report is
generated, which contains the orders for the different products in that product
line. In the Values column, enter the report parameter and the expression to pass
a value from the higher level report to the drill-through report.
This report sample also shows how you can present the same data in different
ways. The pie chart, bar chart, and line chart represent the same data. There is a
parameter to select the type of chart you want to show. For example, if you select
the pie chart, the bar chart and line chart are hidden. The visibility of the charts is
controlled by the Visibility option in the properties editor.
Follow the instructions in the sections above in order to create a report from a
template that contains a chart. Use the instructions below to add interactive
features.
69
4.5.3
DynamicColumnSort Sample Report

This sample report demonstrates how a table can be sorted dynamically. You
can resort the table by any column by clicking on the column name.
A hidden parameter, Sort By, is defined for this report. The sorting condition for
the table is: row[params["Sort By"]], direction ascending.
The labels on the column heading have drill-through links to the same report,
passing the column name to the parameter Sort By and opening the drill-through
report in the same window.
4.5.4
DynamicChartDimensions Sample Report

This sample demonstrates how the size of a chart can be dynamically modified
based on the number of data points.
The first figure shows a bar chart with several bars or data points. The size of the
chart can be reduced in area based on the number of data points. The second
figure shows the same chart with two data points, with the size of the chart
reduced accordingly.
70
71
A global variable called rowCount is defined. The rowCount variable is updated

to the total count of rows present in the chart data. This action is performed in the
visibility expression for the chart in this sample, using the setRowcount functions
in the ReportUtils.js is used. Then, before generation of the chart, the rowCount
is checked. If it is less than or equal to 2 , the chart height and width are reduced.
The code in the onRender method of the chart script is as follows:
function beforeGeneration(chart, icsc)
{
importPackage(
Packages.org.eclipse.birt.chart.model.type.impl);
var row= icsc.getExternalContext().
getScriptable().getPersistentGlobalVariable("rowCount"
);
if( parseInt(row) <= 2){
chart.getPlot().setWidthHint(200);
chart.getPlot().setHeightHint(200);
}
}
4.5.5
ExpandCollapseSections Sample Report

This report demonstrates how you can choose to show or hide any report item
while viewing the report in HTML format. In the figure below, note that the
72
parameter grid is hidden, with an option to expand Parameter Group 1. Below the
chart, there is a similar option to expand details.
Clicking either link causes the hidden grid or table to become visible, as shown in
the next figure.
The purpose of this behavior is to initially show the main data while hiding
unnecessary details until they are needed. However, this ability is supported only
in HTML versions of the report; in PDF output, all sections are visible.
73
In the report design, note the grid containing the optional images and text
elements.
In the property editor, the two images are bookmarked as follows:
(tcr_common/images/expand.gif): collapsePGImage_2
(tcr_common/images/collapse.gif): expandPGImage_2
The text elements Expand Details and Collapse Details have been
bookmarked as expandPGText_2 and collapsePGText_2 respectively.
The table or grid to be hidden is also bookmarked.
The link for expanding uses the following JavaScript script:
javascript:var currTab=document.getElementById('--<bookmark
of table/grid to be hidden>--');
currTab.style.display='block';
document.getElementById('expandPGText_2').style.display='no
ne';
document.getElementById('collapsePGText_2').style.display='
block'; void(0)
document.getElementById('collapsePGImage_2').style.display
= 'block';
74
document.getElementById('expandPGImage_2').style.display =
'none';
The link for collapsing uses the following script:
javascript:var currTab=document.getElementById('--<bookmark
of table/grid to be hidden>--');
currTab.style.display='none';
document.getElementById('expandPGText_2').style.display='bl
ock';
document.getElementById('collapsePGText_2').style.display='
none';
document.getElementById('collapsePGImage_2').style.display
= 'none';
document.getElementById('expandPGImage_2').style.display =
'block'; void(0)
The expand and collapse images are hidden in PDF output. This can be seen
in the visibility of the property editor.
To hide the table or grid when the report is initially viewed in HTML, this code
snippet in the OnCreate method of the table or grid is used:
if (reportContext.getOutputFormat() == "html" )
this.getStyle().display="none";
4.5.6
DynamicQuery Sample Report

The DynamicQuery sample demonstrates how queries can be dynamically built
based on parameter values.
There are two ways of generating dynamic queries:
1. By Property Binding of Dataset Editor:
Double click the DynamicQueryByPropertyBinding dataset. A basic query is
entered in the Query section which retrieves all customer name, phone and state
data from the customer table. In this sample, we want to filter the data based on
the value specified for the State parameter. However, if the State parameter is
blank or null, then all the data is included.
Go to "Property Binding" in the dataset editor. The "Query Text" field contains the
dynamic query that is dependent on the State parameter. If the State parameter
is null or empty, the query retrieves the name, phone number and state data for
all of the customers in the customer table. If the State parameter exists, the
query is modified to retrieve only those customer records matching the specified
value.
2. By Scripts
75
The tcr_common/scripts/ModifyQuery.js script contains functions for adding filters

to a query. This function is called in the beforeOpen method of the dataset.
Double-click to open the DynamicQueryByScripts dataset. Go to the scripts tab.
In the beforeOpen method you will see the expression for modifying the query
based on the state parameter. If the state is not blank or null, then the
appropriate filter is set. Otherwise, the original query in the dataset editor is used
to retrieve all of the records.
To switch between these two datasets, select the table, go to Binding in the
Properties view, and change the binding of the table to the other dataset.
The use of visibility control is also demonstrated in this sample. The State
column in the table appears only when the State parameter is blank and all
states are retrieved. Click on the State column and select "Visibility" in the
Property Editor. Note that the column is hidden, in case the State parameter is
not blank.
4.5.7
DynamicTableColumnsAndVisibilityControl Sample Report

This report demonstrates how visibility can be controlled for tables and columns
using report parameters.
The report contains two sections. The first section displays customer data while
the second one presents employee data. The visibility of each section depends
on the value of the Table Choice parameter.
To view how a section is dropped from the report select the Script tab from the
main report layout, and then choose the BeforeFactory script.
Columns in each table are hidden based on the selected value of the Column
Choice parameter.
To view the visibility settings and to see how the parameters determine the
visibility select a column in either of the tables, and then select Visibility in the
Properties Editor.
4.5.8
MessageDialogs Sample Report

This sample report shows the styles to use for message dialogs, such as
information, error, or warning messages.
Each message dialog is a grid with message-box-style applied to it. The icons
are 32 pixels in size (corresponding to tcr_common/images/<status_name>2.gif).
76
4.5.9
QuickLinks Sample Report

The Quick Links sample report shows how a table of contents can be created for
HTML report output. The QuickLinks section is a collapsible section containing
links to different bookmarks in the report. Back To Top links are provided to
return to the Quick Links section. This is useful in case of very long reports with
multiple sections.
The displayed values for the Quick Links can be collapsed or expanded in a
similar manner to the previously discussed ExpandCollapseSection sample
report.
4.5.10 ParameterValidation Sample

This sample demonstrates how report parameters can be validated. If a user
enters invalid report parameters, an error message is displayed. The BIRT
engine validates parameter types; for additional validation (such as allowed
ranges), use this example.
77
The tcr_common/scripts/ReportUtils.js script contains the

setParameterValidity(str) and isParamValid() methods.
A global variable "param_validity" is defined as a blank string. During initialization
of the report, parameters are validated. If the parameters are not valid, the
parameter validity is set to a string with the appropriate message.
An error message item is added to the third row of the report introduction. The
message is shown when the isParamValid() method returns a false value. The
chart is consequently hidden.
To test how this works, enter a parameter value that is not valid (for example, -1
for the minimum number of orders, or a maximum number of orders that is less
than the minimum number of orders).
4.5.11 StatusBasedColoringChart Sample

This sample demonstrates how data points and legends on a chart can be
colored based on value or series grouping. Additionally it also shows how
horizontal bar charts are used.
The chart displays number of active orders per product line, grouped by status.
The different status values are Resolved, Disputed, In Process, and On Hold.
The status colors are the colors that are defined in the style guidelines.
Select the chart and go to the Scripts tab. The beforeDrawLegendItem and
beforeDrawDataPoint methods contain the code that affects the color to be used.
function beforeDrawLegendItem(lerh, bounds, icsc)
{
val = lerh.getLabel().getCaption().getValue();
fill = lerh.getFill();
if (val == "Disputed")
fill.set(183,68, 61);
else if(val == "Resolved")
fill.set(144, 213, 0);
else if(val == "In Process")
fill.set(182, 146, 182);
else if(val == "On Hold")
fill.set(229,237,129);
}
function beforeDrawDataPoint(dph, fill, icsc)
{
78
// val = dph.getOrthogonalValue();//-- based on value

of the datapoint
val = dph.getSeriesValue();//--- based on the series
value
if (val == "Disputed")
fill.set(183,68, 61);
else if(val == "Resolved")
fill.set(144, 213, 0);
else if(val == "In Process")
fill.set(182, 146, 182);
else if(val == "On Hold")
fill.set(229,237,129);
}
4.5.12 TableFooterWithTotals Sample Report

This report demonstrates how to create summary totals in the footer row of a
table.
79
The table footer consists of 2 rows. The first row contains a total count of product
lines and a total number of orders; the second row contains a calculated average
number of orders for each product line. Each footer row uses the table-footercell style from the Tivoli Common Reporting library.
In the Eclipse/BIRT designer, the layout for this report is as follows:
80
The data items for Total and Average use built-in BIRT JavaScript functions
accessible from the Expression Builder:
4.5.13 DateRangeParameters Sample Report

This report is an example of how to filter a report based on the predefined Date
Range group included in the TCR library. When querying a database, it is usually
useful to limit the rows returned by specifying a date range. This is accomplished
with a WHERE condition in the SQL SELECT statement. For example:
SELECT PAYMENTDATE, CHECKNUMBER, AMOUNT
FROM PAYMENTS WHERE PAYMENTDATE between 3/23/07 and
6/21/07
This SQL query in the BIRT Data Set could be coded using a ? parameter
marker for the start and end dates, with these markers bound to report
parameters. Using this method, the query above would be coded:
SELECT PAYMENTDATE, CHECKNUMBER, AMOUNT
FROM PAYMENTS WHERE PAYMENTDATE between ? and ?
The report design would include two date parameters, requiring the user to
specify two dates each time the report is run. However, this requirement could
become tedious to users for a frequently used report.
Instead, the sample report uses a Date Range parameter group from the Tivoli
Common Reporting library to display a Report Period parameter containing a
user-friendly selection list of predefined date ranges, and optional beginning and
81
end dates. The user can choose from the predefined list of date ranges or enter
a specific set of dates.
The user-friendly report period selection, such as Last 90 Days, is translated by

JavaScript utilities into start and end dates. The SQL query is then modified to
add the beginning and end dates as filter conditions. The output of the report
looks like the following:
82
Note that the Report Period is displayed in the report output in the same format
used in the parameter selection list, and also as the calculated Start Date and
End Date. (This sample output shows no displayed records because none
matched the specified date range.) If both a beginning date and an end date are
entered on the parameter prompt, the reporting period is ignored, and the
specified beginning and end dates are used.
The scripting that implements this feature is in the beforeOpen() method of the
CustomerPayments data set:
// Filter on Report Period
var report_period =
reportContext.getParameterValue("Report Period");
if ((report_period != null) && (report_period != ""))
{
ModifyQueryAddDateRangeFromGroupValues (this,
"pay.PAYMENTDATE", report_period, dateToString,
params[Begin Date].value, params[End
Date].value);
}
The ModifyQueryAddDateRangeFromGroupValues() method is defined in
the ModifyQuery.js script library file. The this object refers to the data set and
is required in order to provide the context for the data set query within the
ModifyQueryAddDateRangeFromGroupValues() method.
This script changes the original query from:
SELECT cus.CUSTOMERNAME,
pay.PAYMENTDATE,pay.CHECKNUMBER,pay.AMOUNT
FROM CUSTOMERS cus, PAYMENTS pay
WHERE cus.CUSTOMERNAME = 'AV Stores, Co.' AND
cus.CUSTOMERNUMBER = pay.CUSTOMERNUMBER
ORDER BY cus.CUSTOMERNAME,
pay.PAYMENTDATE,pay.CHECKNUMBER
83
To:
SELECT cus.CUSTOMERNAME,
pay.PAYMENTDATE,pay.CHECKNUMBER,pay.AMOUNT
FROM CUSTOMERS cus, PAYMENTS pay
WHERE pay.PAYMENTDATE between '3/24/2007' and
'6/22/2007' AND cus.CUSTOMERNAME = 'AV Stores, Co.'
AND cus.CUSTOMERNUMBER = pay.CUSTOMERNUMBER
ORDER BY cus.CUSTOMERNAME,
pay.PAYMENTDATE,pay.CHECKNUMBER
In addition, the report output uses JavaScript to display the beginning and end
dates in the report parameter section. The easiest way to use these elements is
to drag and drop the Begin Date and End Date parameter data items from the
Report Items in the TCR library to the layout view of the report design. The
parameter names are also included as text elements in the TCR library and can
be dragged onto the layout view of the report design.
The Begin Date data item (typically dragged from the TCR library into the report)
contains the following expression, which calculates the date from the entered
parameters:
getStartDateFromGroupNames(Report Period, Begin Date,
End Date);
The End Date field is calculated in a similar fashion from the
getEndDateFromGroupNames() method.
4.5.14 CascadingParameters Report

This sample demonstrates the use of cascading parameters wherein one
parameter list is updated based on the selection in the previous parameter list.
Limitation: The cascading parameters which are defined as Combo Box are not
supported by the Tivoli Common Reporting Web UI.
BIRT designer enables you to choose between the following display
types for each parameter in a cascade - List Box or Combo Box. Combo
box returns a list of selection options just like list boxes do, and allow for
manual input of specific value into the parameter filed. With a combo box
in a cascade it is possible to select a value form the list or input a value
manually, and in turn the next set of values in the cascade is narrowed
according to the previous choice. This behavior works fine in the BIRT
designer but it is not supported by the Tivoli Common Reporting portlet.
The Common Reporting UI does not handle parameters that are
combination of combo box and cascading. Therefore, all parameters in
the cascade should be defined as List Box for the display type.
There are two cascading parameter groups in this sample. One is the Customer
Location parameter, which uses multiple datasets; the other is the Employee
Location parameter group, which uses a single dataset. The results are filtered
by the choice of location.
The figures below show the parameter prompt. When Country or Territory is
selected, the city is filtered based on the selection. Double-click to open the
parameter groups and see how the parameters are specified.
84
The Customer Location group is based on two datasets:
Customer Country selects all countries from the customer table.
Customer City selects customer cities, where the country matches the
value of the country parameter.
The Employee Location group is based on a single dataset. This dataset selects
both territory and city from the customer table. In the parameter group, you can
specify the columns to cascade.
85
4.5.15 DependentDatasets Sample Report
This sample demonstrates how a value from one dataset can be used in another
dataset.
The ProductlineSales dataset computes the total sales for a particular product
line (specified using a parameter). This value is stored in the hidden parameter
ProductlineTotalSales.
The ProductSales dataset retrieves the total sales for each product under a
specific product line. This dataset also contains a computed column called
PRODUCTSALESPERCENT, which is product sales as a percentage of the total
sales of the product line.
This computed column is calculated as
TOTALSALES/param["ProductLineTotalSales"]*100.
Thus a value computed by one dataset can be used in another. For the first
dataset to compute the value, it must be bound to a report element and be called
before the second dataset. In this sample, the first dataset is called when the
Total Sales data shown below the section subtitle is used.
86
In addition to calculating a computed column, the hidden parameter could also be

used to filter the second dataset, or to be a part of the WHERE clause in the
query of the second dataset. For the latter approach, you must modify the query
in the beforeOpen method of the second dataset.
4.5.16 TableUsingStatusIcons Sample Report

This report design provides an example of how status icons can be used in a
table listing to convey information, and also provides an example of how status
icons and coloring should not be used. The report also shows several different
techniques for accessing and displaying data.
In this report design, note that the status icons all occupy a single cell in the
table. The icons use visibility attributes to determine when each icon should be
displayed. By opening the properties of each image and selecting the visibility
option, you can see how each image is selected.
87
The background color to highlight the cells is handled by setting the color in an
"onCreate" script action on the report cell containing both the icon and the text
value. You can access this "onCreate" method by selecting the cell in the outline
view and then clicking on the Scripts tab in the editor space. You can also set
the cell color on the Highlight tab of the cell properties editor, rather than using a
script.
To show accessing the icons in a different way, the second time the icons are
shown in the report, they are displayed using a dynamic text value. The dynamic
text value calls a global script, defined in the report "initialize" method, that
returns the properly formatted HTML image tag.
4.5.17 MultipleSelectListBoxParameter Report

This report demonstrates the use of a list box parameter that allows the user to
select multiple values by using the CTRL or SHIFT keys.
In the Customers data set, a filter is put on the query to limit the data to the
countries the user selects. In the Filter tab of the Data Set Editor, the following
syntax is used: row[COUNTRY] In params[Country].value, where
the row name is the expression, In is the operator, and the parameter value is
the first value.
88
To display the Country parameters value(s), a simple JavaScript function is used

in the Data Expression Builder.
var array = params["Country"].value;
var string = "";
for( var x=0; x<array.length; x++ ) {
string = string.concat( array[x] + ", " );
}
string.substring(0,string.length-2)
4.6 Scripts
The tcr_common/scripts folder contains collections of Javascript functions which
can be used in report designs. These scripts can be called from the Expression
Builder and used with almost any Text or Data item in a report. In addition, they
can be called from customizable methods of the report, such as beforeFactory(),
beforeRender(), or beforeOpen() of a data set.
To make the scripts available to a report, one or more includeScripts properties
must be included in the report design file. These cannot be added using the
Eclipse/BIRT designer; you must add them manually. To do this, use the XML
view of the Eclipse Report Design editor. The property elements should be
added near the beginning of the .rptdesign file, before any parameter elements:
<list-property name="includeScripts">
<property>tcr_common/scripts/ReportUtils.js</property>
<property>tcr_common/scripts/DateTime.js</property>
<property>tcr_common/scripts/ModifyQuery.js</property>
</list-property>
Note that the path to each script is based on the resources directory defined for
the project in the Eclipse/BIRT environment.
Most of the Tivoli Common Reporting templates and sample reports contain the
includeScripts property list. Include only those scripts required by the report.
Scripts are organized into .js files. The script files currently included with the
TCR style package are:
4.6.1
ReportUtils.js
General purpose methods such as trimString(), getNLS(), setReportTitle(), and
setRowCount().
4.6.2
DateTime.js
Date and time conversion and formatting functions. Use these methods to
convert between Java dates and times (used in BIRT) and Candle Data
Warehouse date and time strings. This script also implements conversion of
standard Report Period parameters to start and end date or time values.
89
4.6.3
ModifyQuery.js
Methods to modify a data set SQL query by adding or modifying a WHERE
clause. The generic ModifyQueryAddFilter() method can be used to add any
conditional expression to an existing query. The ModifyQueryAddDateRange()
method adds a date range condition to a query, the
ModifyQueryCandleDateRange() method modifies an existing filter condition that
uses Candle date or time string format and the
ModifyQueryCandleDateRangeFromGroupValues() modifies an existing filter
condition that uses Candle date or time string format with the values from the
DateRange parameter group.
4.6.4
Logger.js
Methods to log from anywhere within a report design. The
DateRangeParameters sample demonstrates the use of the logger script.
90
Section 5Best
5Best Practices
5.1 Projects and Libraries
To enable smooth integration into the Tivoli Common Reporting software, you
must use a consistent directory structure for your project. For each product,
create a separate directory structure starting with your product name. This
directory will prevent name collisions for .properties files or images used by
different products sharing a Tivoli Common Reporting server.
Each project should have a folder structure as shown below:
Directly underneath the project directory are the report design files (*.rptdesign),
a resources folder, and an optional templates folder.
Underneath the resources folder are two additional folders: a product-specific
resource folder, and the tcr_common folder, containing the Tivoli Common
Reporting style package files. The tcr_common folder can be created from
within the Eclipse SDK by copying the folder with that name from the TCR project
folder you created when you imported the TCR files.
Within each resources sub-folder are additional folders, as needed:
lib
BIRT libraries (.rptlibrary files)
images
Image files used by templates and libraries
properties
Java .properties files for localizing report content
91
scripts
JavaScript files called from reports
When working in a BIRT project in Eclipse, set the default resources folder (via
Window -> Preferences -> Report Design -> Resource) to the resources folder
immediately underneath the project folder. This way, your report designs will
have access to both product-specific and TCR resources.
5.2 General Report Properties
Report Title: The title of the report appears in the browser title bar when viewed as
HTML. The report title is usually entered in the Title field of the properties editor.
However, the text entered here is static.
Report Description: The description is useful for explaining the purpose of the report.
This is optional. The descriptions in the sample reports and templates show how the
description might be used.
5.3 Globalization / Localization

The Tivoli Common Reporting style package contains templates that have
already been globalized. These templates provide an example of how a product
should enable translation of the report text.
It is a design decision whether to have one report .properties file for all reports
(which can help to minimize translation and duplication of labels), a single
.properties file for each report, or some combination of shared and separate
.properties files.
The sample reports in the style package are not globalized. Only the templates
are globalized.
92
5.3.1
Setting Up Basic Globalization

To set up for globalization, first make sure you have established the resources
directory path. Typically, this points to the resources folder in your project. This
procedure assumes that you have copied the resources file from the TCR
Common Reporting v<n> project into your products project.
Go to Window -> Preferences. Expand Report Design.

Change Resource folder: Select Resource and enter the location of the
resources folder in the project: <workspace>/
<your_product_project>/resources. This makes the library and
.properties files public, allowing them to be used by any report design in
the workspace
How to globalize a report is described in detail in Chapter 24: Localizing Text in

the BIRT A Field Guide to Reporting book. These steps can be summarized as
follows:
1. Make sure you have set the resource directory as noted above.
2. Create the directory structure and resource .properties file that you want
to use for the report. Right-click on the resources directory then click
New->Folder to create the product-specific folder and folders for the
images, library (if needed), and .properties files. Create the starting
.properties file or copy one into the folder as your starting point.
3. Make sure Eclipse shows the Properties view on the Eclipse window. If
not shown, click Window->Show View->Other->General->Properties.
4. Set the resources .properties file for your report. To do this, after creating
the beginnings of a report or copying a template, select the Outline view
for your report, and then click the report element itself (the .rptdesign or
.rpttemplate element).
5. In the Properties view, navigate to the Resources tab. Use the Browse
menu to find a resources file that you created or defined in step 2.
6. For any element that you want to localize, such as the report title, click
on that element in the report editor or the outline view. A properties
sheet will be displayed for that element in the Properties view. Click on
the Localization tab in the view. From this view, you can either add a new
property key for the element and then select it, or select an existing
element. Once you have selected an element, click OK to save the
information.
There is no required format for naming keys in the .properties file. However,
it is recommended that you use the <report element name>_<your key>
format. For example,
chart_title_orders_by_productline, report_title_asset_list,
parameter_product_code etc.
5.3.2
Globalizing Strings Embedded in HTML Text

If you need to include globalized text in a dynamic text field that has multiple
strings defined in it, then you will need to define a globalization script. The
following is an example of where dynamic text may need to have two strings to
be globalized:
<div title="Some information about Parm1">Parameter 1</div>
93
In this example, a report parameter is defined in a parameter heading of the

report. If a user holds the mouse pointer over Parameter 1, a tooltip help
window appears, displaying the text Some information about Parm1. This field
is defined in a report text element, which allows HTML to be mixed with report
textual data.
To globalize this item, the code uses a getNLS script defined in the reportUtils.js
supplied with the TCR style package. This script is as follows:
function getNLS(key)
{
nlsText =
reportContext.getMessage(key,reportContext.getLocale());
if (nlsText != null)
{
return nlsText;
}
return "Key " + key + " missing";
}
To use the script to localize the string, replace this string:
<div title="Some information about Param1">Parameter 1<div>
with:
<div title="<VALUE-OF>getNLS("parameter1_tooltip");</VALUEOF>"><VALUE-OF>getNLS("parameter1");</VALUE-OF><div>
where the parameter1_tooltip and parameter1 strings are keys within your
resource .properties files. The <VALUE-OF> tags invoke the script environment,
calling the getNLS method defined in the initialize script.
5.3.3
Globalizing Report Title and Description

For globalizing the report title that appears in the browser title bar when viewing
the report as HTML, do the following:
Include tcr_common/scripts/ReportUtils.js in the report design as

explained in Section 6.5
Place this code snippet in the beforefactory of the report:
setReportTitle(---title key----);
5.3.4
Globalizing Report Element Names

Report element names are not typically viewed by users, because these names
are not part of the actual report. However, these names can appear in exported
report data, so if you expect your users to export the report to CSV format, report
element names should be globalized.
Select any report element except chart. Go to the Scripts tab. In the onPrepare
method, add the following code snippet:
94
this.name=getNLS("<report_element_key");
For charts, insert the following code snippet in the beforeFactory method of the
report:
this.getReportElement("Pie Chart").name =
getNLS("<pie_chart_key");
this.getReportElement("Bar Chart").name =
getNLS("bar_chart_key");
this.getReportElement("Line Chart").name =
getNLS("line_chart_key");
5.4 Data Sources

Typically, all reports in each product report set use the same data source. The
connection details for the data source used during development of reports is
typically different from the data source used by customers after the reports are
deployed. Therefore, this data source should be defined in a way that makes it
easy to change.
Recommendations:
1. Define all data sources in a product-specific report library
(.rptlibrary). When needed within a report design, the data source
can be dragged from the library into the design. When the
connection details change in the library, all designs based on the
data source are automatically updated.
2. Use a JNDI URL to reference the database. The advantage of
using JNDI is that security information (such as user ID and
password) is not stored in the report design or library, but in a secure
database accessible only from the JNDI implementation. Tivoli
Common Reporting first attempts to resolve the JNDI name for a
data source; if that attempt fails, TCR then uses the JDBC URL
information.
5.4.1
JNDI Naming Convention

BIRT uses the JNDI name to access the JDBC data source. Therefore, the JNDI
name for the data source should follow the general rule for JDBC data sources
and start with a subcontext of java:comp/env/jdbc.
The rest of the name should use the following format:
java:comp/env/jdbc/ibm/tivoli/<PRODUCT>/<VERSION>/<RELEASE>
where:
Qualifier
Required
Description
Example
PRODUCT
Yes
The identifier of the

product being used as
the data source.
tbsm
VERSION
No
The version of the

product being
accessed. The
v4
95
version should start

with a lower case v
followed by the
numeric version
identifier.
RELEASE
No
The release of the

product being
accessed. The
release should start
with a lower case r
followed by the
numeric release
identifier.
r2
Using this convention, the following are examples of valid JNDI names:
java:comp/env/jdbc/ibm/tivoli/tbsm
java:comp/env/jdbc/ibm/tivoli/itm/v6
java:comp/env/jdbc/ibm/tivoli/itm/v6/r2
The product version and release specification is labeled as optional. This is

meant to give flexibility across versions or releases of products; the data source
might not change between versions or releases of a given product, in which case
no change is required to the data source. However, care should be taken when
omitting the version identifier, because significant changes might occur between
product versions.
5.5 Data Sets

Recommendations:
1. For dynamic list report parameters, create a separate data set to
return the values to populate the parameter selection list. See the
DateRangeParameters sample report, which uses the Customers
data set only to populate a dynamic report parameter selection list.
2. Use optimized SQL queries instead of filters in the BIRT dataset
editor.
3. To modify a SQL query based on user parameters, use one of the
following three methods:
a. Use a prepared statement. Insert a parameter marker (?) in
the SQL query and bind it to a Data Set parameter.
b. Use a beforeOpen() script in the Data Set to adjust the SQL
query string. See the DateRangeParameters sample report.
c.
Use Property Binding in the Data Set. See the

DynamicQuery sample report.
96
5.6 Timestamps
5.6.1
Timestamps in Charts
The timestamps on charts should use the BIRT Short Date format:
MM/DD/YY hh:mm a
An example of this format is 08/30/07 12:33 PM.
To specify this format with the chart editor, go to Format Chart -> X-Axis.
Select Type as DateTime. Click the Format Editor button next to the type
field. Select Standard, Short in the Type field, and Date Time in the Details
field.. This timestamp format can be localized.
97
5.6.2
Timestamps in Tables and Parameters

Timestamps in tables should use the BIRT unformatted type:
M d yyyy hh:mm a
An example of this format is Aug 30, 2007 4:05 PM.
To specify this format, select the DateTime type data, go to the Properties View,
and select Format DateTime -> Format as: Unformatted. This timestamp
format can be localized.
5.6.3
Timestamp in Footer
Timestamps in footers should use the BIRT General Date format:
MMMM d, yyyy h:mm:ss a z
An example of this format is August 30, 2007 4:05:12 PM EDT
98
5.7 Charts
The following recommendations apply to charts:
1. Limit bar charts to 5-10 result rows to avoid the chart becoming too
crowded and difficult to read. Two strategies to achieve this are as
follows:
a. Show only Top 5 or Top 10 categories on the chart, even if you
show all data in an accompanying table.
b. Break down the result set into groups so that no group has more
than 10 result rows.
2. Add spacing between bars in a bar chart. To do this, double-click on the
chart in the BIRT designer, select the Format Chart tab, select Chart
Area, and then click General Properties. Change the Unit Spacing
value from 0 to a positive number such as 10, 20 or 30.
5.8 Useful Hints and Tips

5.8.1
BIRT Designer
1. Use the Outline View. You can use the Outline view to navigate to specific items in
a report design. This is often easier than trying to select the item from the Layout
view, especially when items are layered on top of one another. This can be
particularly difficult in tables, where a Data item might be inside a cell, row, or grid.
The structure of a report design is more apparent in the Outline view than in the
Layout view.
5.8.2
Tables
1. Create Grouped Tables from Templates: If you created a report with a nongrouped table, and now want to add grouping, start with a new report created from
the appropriate TCR grouped table template. Manually converting the styles and
indentation of a non-grouped report to a grouped one can be very time consuming.
5.8.3
Charts
Control Legend Wrap: Longer labels in a chart legend might be truncated because
of space limitations, with the final characters of the label replaced by ellipses. To
prevent this, set a wrapping width value. Select Edit Chart -> Format Chart ->
Legend -> Layout. Change the Wrapping width value to 100; experiment with
different values if 100 does not produce the desired result.
Remove Marker Area: In many of the bar chart templates and samples, a Marker
area appears as a grey rectangle over the chart area. In some cases, this rectangle
might cover some other information. To edit or remove the Marker area, select Edit
Chart -> Format Chart -> Y-Axis -> Markers. From the Axis Markers dialog, you
can change the Marker Properties or remove the marker altogether.
Color bar charts and line charts based on data or series value: TCR styles
provide pre-defined status colors as shown in Chart Colors.To use these colors, you
can use scripts. Select the chart, go to its Scripts tab and insert the following code.
Modify the values in the conditions based on your need. In this example, val is the
99
status of a server (up, down or unknown). To choose more status colors refer to
Chart Colors
function beforeDrawDataPoint( dph, fill, context )
{
var val = dph.getOrthogonalValue();
//var val = dph.getSeriesValue();
if (val == down) //status color for critical
fill.set(183,68, 61);
else if(val == up) //status color for normal
fill.set(144, 213, 0);
else //status color for unknown
fill.set(182,146,182);
}
100
Appendix A Terminology
BIRT
The Eclipse Business Intelligence and Reporting Tools project. This is an open
source Eclipse-based reporting tool written in Java. It has two main components:
a report designer and a runtime component. BIRT also offers a charting engine
for adding charts to your own application.
BIRT Report Designer
This is one of the two major components of BIRT. It is a graphical tool that is
used to create report libraries, report designs and report templates.
BIRT Rich Client Platform (RCP) Report Designer
A stand-alone version of the BIRT report designer, containing the minimal set of
Eclipse dependencies for the report designer.
Cascading style sheet (CSS)
A file that defines a hierarchical set of style rules for controlling the rendering of
HTML or XML files in browsers, viewers, or in print.
Chart
A graphical view of data.
Data Set
The definition in a report library that contains information about the raw data that
will be used by a report design or report template.
Data Source
The definition in a report library that contains location information for report data
retrieval.
Eclipse Platform
An open source, standard platform for building integrated development
environments (IDEs) that can be used to create applications, such as Web sites,
embedded Java programs, or Enterprise JavaBeans. The platform discovers,
integrates, and runs the integrated modules called plug-ins that exist within its
environment.
Eclipse Perspective
A set of Eclipse views, menus, toolbars, and editors that are useful for a
particular tool. A user can switch between perspectives.
Eclipse Rich Client Platform
A framework for building Java applications containing a minimal set of dynamic
plug-ins.
101
Eclipse view
A panel on the Eclipse Workbench. Some examples are the error view, the
console view, the outline view.
Eclipse Workbench
The user interface and integrated development environment (IDE) in Eclipse and
Eclipse-based tools such as IBM Rational Application Developer.
Eclipse workspace
The collection of projects and other resources that the user is currently
developing in the Eclipse workbench. Metadata about these resources resides in
a directory on the file system; the resources might reside in the same directory.
Expression
The report-specific logic to convert raw data into useful information for a user.
Globalization
The process of developing, manufacturing, and marketing software products that
are intended for worldwide distribution.
Grid
One of the available items on the BIRT report designer palette. A grid is used to
display information in a row-and-column format and contains other report
elements.
Grid Element
An element of a grid.
Group
A set of data rows with at least one shared column value.
Group report
A report that arranges data in groups.
Group key
The data set column that is used to group data for a report.
Hyperlink
A reference in a report that, when clicked, connects you to another area on the
same report, or to another report.
Image element
A graphic item in a report project that can be used in a report template or a report
design.
Internationalization
The process of designing and developing a software product to function in
multiple locales.
102
Java Database connectivity (JDBC)

An industry standard for database-independent connectivity between the Java
platform and a wide range of databases. The JDBC interface provides a call-level
API for SQL-based and XQuery-based database access.
Label element
One of the available items on the BIRT report designer palette. A label element
can be used to display text.
Library
A part of a report project. A library is a file with the extension .rptlibrary; it
contains definitions for data sources, data sets, report parameters, report items,
themes, and images that can be reused.
List element
One of the available items on the BIRT report designer palette. A list element can
be used to display all of the data rows of a data set.
Navigator
The Eclipse view that shows all resources in the workspace.
Outline
The Eclipse view that shows the outline of the resource.
Previewer
A component of the BIRT report designer that allows a report to be viewed from
within the report designer itself.
Properties
An Eclipse view that shows particular attributes of an item or a resource.
Property Editor
An Eclipse view that shows particular attributes of an item or a resource. A user
can use this view to modify the properties.
Report design
The primary file that a customer uses when running a report. A report design is
provided as input to the BIRT report viewer. It has a file extension of .rptdesign.
Report element
An element of a report design. It can be visual or nonvisual.
Report item
A report element that displays content in a report.
Report library
See Library.
103
Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the users responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not give you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785 U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE.
Some states do not allow disclaimer of express or implied warranties in certain
transactions, therefore, this statement might not apply to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.
A-1
IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
IBM Corporation
2Z4A/101
11400 Burnet Road
Austin, TX 78758 U.S.A.
Such information may be available, subject to appropriate terms and conditions,
including in some cases payment of a fee.
The licensed program described in this document and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement
between us.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
Trademarks
IBM, the IBM logo, ibm.com, DB2 and Tivoli are trademarks or registered
trademarks of International Business Machines Corporation in the United States,
other countries, or both.
Microsoft and Windows NT are registered trademarks of Microsoft Corporation in
the United States, other countries, or both.
Other company, product, and service names may be trademarks or service marks
of others.
A-2
Tivoli Common Reporting: Development and Style Guide

Printed in USA
SC23-8861-01
Report parameter
User input provided for a report, controlling the running and display of the report.
Report package
A collection of associated report designs and resource files that are organized
into a Tivoli recommended file structure for simplified importing into Tivoli
Common Reporting. A unique report package is usually created for each product.
Report style package
The report package provided by Tivoli Common Reporting containing Tivoli
recommended styles, templates and samples. These elements can be used as a
base in developing specific product or customer-focused reports.
Report template
A file containing a reusable report design. Templates are created and updated
with the BIRT report designer. The file extension for a template is .rptemplate.
Script editor
An Eclipse editor that allows the report designer to input JavaScript code for a
report element.
Style
A set of properties that control the appearance of report items.
Text element
A report item that displays user text.
Theme
A set of related styles.
104

TCR Style Guide

Transféré par

Informations du document

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

TCR Style Guide

Transféré par

Droits d'auteur :

Formats disponibles

Tivoli Tivoli Common Reporting

Development and Style Guide

Tivoli Tivoli Common Reporting

Development and Style Guide

Fourth Edition (September 2009)

Copyright IBM Corp. 2007, 2009

4.3.1 TCR Theme....................................................................................................................................46

Copyright IBM Corp. 2007, 2008

1.2 Report Content Is Key

High Value: Each report should provide information that is important to

Outside-In Design work to identify and validate reporting content that

Analysis of the visual display of the information and innovation of

Integration of design across products and processes to fully

Consistent: As users look at the reports produced from different Tivoli

Copyright IBM Corp. 2007, 2008

only be obtained when reports are visually consistent in their

Visual-appearance standards for features such as graphics

Algorithmic and analytical standards, such as statistical process

Consistency in the underlying data used to produce reports. This

Copyright IBM Corp. 2007, 2008

2.2 Educational Materials

BIRT: A Field Guide to Reporting, by Diana Peh, Alethea Hannemann

Integrating and Extending BIRT, by Jason Weathersby, Don French,

These books can be purchased from any technical book supplier.

2.4 Eclipse and BIRT

All-in-One: A complete Eclipse installation along with the BIRT Designer.

Rich Client Platform (RCP): The stand-alone BIRT report designer

2.5 Database Drivers

Copyright IBM Corp. 2007, 2008

General information about DB2 and JDBC can be found here:

Microsoft SQL Server

How to Add a JDBC Driver and Configure a JDBC Datasource

Copyright IBM Corp. 2007, 2008

Copyright IBM Corp. 2007, 2008

Copyright IBM Corp. 2007, 2008

For DB2, select the Universal JDBC driver class:

Copyright IBM Corp. 2007, 2008

3.1 Document Layout

A report contains the following sections:

A header for company branding

A primary report title

Optional secondary titles to separate sets of parameters

Parameters used to generate the report

Information sections, which contain the content of the report

Overall Document Style

Font: Verdana 70% (11pt)

Top margin: 0 inches

Copyright IBM Corp. 2007, 2008

Right, left and bottom margin: 0.5 inch

Use a portrait page orientation for a report containing tables with a

Use a landscape page orientation for a report containing tables with a

Overall Document Color Pallet

3.2 Report Header

3.3 Report Introduction

Font style: Bold

Font size: 150% (14pt)

Color: Dark blue (#444E68)

Border: 3 pixel bottom border in dark blue (#444E68), extending from

Justification: Left justification

Padding: 10 pixel top padding

Font style: Normal

Font size: 100% (11pt)

Color: Dark blue (#444E68)