Tcr Style Guide

Tivoli® Tivoli Common Reporting

Development and Style Guide

Version 1.2.0.1

SC23-8861-01

��

NoteBefore 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 modificationsuntil 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 Contractwith IBM Corp.

Table of ContentsTable of Contents

WHAT’S 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

© Copyright IBM Corp. 2007, 2008 5

Section 1Section 1Tivoli Common Reporting OverviewTivoli Common Reporting Overview

1.11.1 Getting Started With Tivoli Common ReportingGetting Started With Tivoli Common ReportingThe 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.21.2 Report Content Is KeyReport Content Is KeyProducing 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.

o Analysis of the visual display of the information and innovation of techniques to “get the message across” quickly and effectively.

o 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 in-house, 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.

o Layout standards for features such as chart sizes and locations, and templates for combining information on a single page.

o 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).

o 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 2Section 2ToolsTools

2.12.1 OverviewOverviewThe 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.22.2 Educational Materials Educational MaterialsThe 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.32.3 JavaJavaA Java Runtime Environment (JRE) is required to run the Eclipse/BIRT SDK. The minimum level of Java required is JRE 1.5.

2.42.4 Eclipse and BIRTEclipse and BIRTEclipse 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.


http://www.ibm.com/developerworks

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.52.5 Database DriversDatabase DriversBIRT 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:




• 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:


2.5.2 Microsoft™ SQL ServerDownload the SQL Server 2000 SP3 JDBC Type 4 Driver here:

http://www.microsoft.com/downloads/details.aspx?FamilyID=07287B11-0502-461A-B138-2AA54BFDC03A&displaylang=en

Download the SQL Server 2005 JDBC Type 4 Driver here:

http://www.microsoft.com/downloads/details.aspx?familyid=6D483869-816A-44CB-9787-A866235EFC7C&displaylang=en

2.5.3 OracleDownload 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 DatasourceTo 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:


http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html







http://www.ibm.com/software/data/db2/ad/v8/java.html

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:


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:


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.

.


http://publib.boulder.ibm.com/infocenter/db2luw/v8/topic/com.ibm.db2.udb.doc/ad/rjvdsprp.htm

Section 3Section 3Style GuidelinesStyle 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 product-specific 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.


3.13.1 Document Layout 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

• An optional description

• A footer containing the generation date and time of the report and a page number

3.1.1 Overall Document StyleThe 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


• Right, left and bottom margin: 0.5 inch

When choosing page orientations for your report, consider the following:

• 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.

3.1.2 Overall Document Color PalletThis 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.


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.23.2 Report Header Report HeaderThe 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.33.3 Report Introduction Report Introduction

3.3.1 Report TitleThe 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-TitleThe 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





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:

• Font size: Base font size (11pt)


• Border: 15 pixel top, Bottom, dotted, 1 pixel

• Indentation: 15 pixel left indentation

3.3.4 ParametersThe 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.


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)





• Cell padding: 5 pixel right cell padding; 3 pixel top and bottom cell padding

Parameter value format:



• Color: Black


• Cell padding: 3 pixel top and bottom cell padding

3.3.4.2 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.


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.43.4 Information Sections Information SectionsInformation sections are the main part of the report document. Information sections contain one or more of the following elements:

• Section title

• Charts such as line, bar, or pie charts

• Standard tables of data

• Grouping tables

• Form elements

3.4.1 Section TitleThe 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



• 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

3.4.2 ChartsCharts 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 highest-quality 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 Y-axis) , 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.


• 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:

• 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.

3.4.2.1 Chart Colors

The following chart shows the colors to use for report charts:


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:


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.


3.4.2.3 Bar Chart

Additional bar chart formatting:

• 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.

3.4.2.4 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


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.


• 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.

3.4.2.6 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 don’t 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.


• 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.

3.4.3 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 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


• 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:





• 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.


• Alignment: First header row has top left alignment. Second header row has left alignment.

3.4.4 Grouping TablesBIRT 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


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 color: White

• Background color: Dark medium blue (#7E90BF)


• 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 color: dark blue (#444E68)

• Background color: Light blue-grey (#ABC3FF)



• Font: Verdana



• Font color: white

• Background color: Medium blue (#94ABE0)


3.4.5 Form ElementsSome 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


• Margin: 20 pixel top margin from previous section if not provided by previous section

Section title format:





• Padding: 10 pixel bottom padding


Entry field format:





• 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.53.5 Report Description Report DescriptionReport descriptions are optional and should be used only when necessary to explain the content of a complex report.

Description format:





• Width: Text section extends to the left and right margin of the document

3.63.6 Message Dialog Boxes 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


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:


• 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:






Message Text:



Alignment: Left alignment

3.73.7 Collapsible Sections 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.83.8 Report FooterReport FooterThe 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


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.93.9 Sample Reports LayoutsSample Reports LayoutsThis sample shows a report with parameters and grouping tables:

This sample shows a report using a parameters subsection and forms:


This sample shows a report with table footers and a message dialog box:


Section 4Section 4Creating reports and report packages Creating reports and report packages

4.14.1 IntroductionIntroductionThis 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 User’s Guide. (A report design package is one of two types of report package.)

4.24.2 Tivoli Common Reporting Style Package Tivoli Common Reporting Style PackageIncluded 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 DescriptionThe 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.

o 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.

o 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.

o 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.

.


• 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

.


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 product’s 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.


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 ConventionAll reports are created directly under your product directory. The recommended naming convention for .rptdesign files is as follows:


<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.34.3 Tivoli Common Reporting Library Tivoli Common Reporting LibraryThe 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.


4.3.1 TCR ThemeA 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. BIRT’s 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, table-header-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.


4.3.2 Report ParametersThe 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 ItemsThe Tivoli Common Reporting library contains the following reusable report items:

• 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.

4.3.4 TCR Master PageThe 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


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.44.4 Report TemplatesReport TemplatesA 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.

o Secondary Title or Parameter Group Heading (optional)

o 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.


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

© Copyright IBM Corp. 2007, 2008

Header

Footer

Report Introduction

Section 2

GriGri

Report Description

Section 1

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 param-table 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.

o 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.

o Grid 3 in templates that have 4 grids will contain another section similar in structure to grid 2

o 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:


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.


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 TemplateThe 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:


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 “table-without-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 “table-without-group” style. The first header cells use the “table-header-cell” style. The second header cells use “multi-column-heading-secondary-header” style. The


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 product’s 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-header-cell, 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>.table-header-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


cells. Right click and select Style -> Apply Style -> TCRTheme_v<n>.table-details.

4.4.3 Using the Group Table TemplatesThere 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.


Follow the instructions in the previous section, Using TCR Templates, to modify 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

o The first group of the table uses “section” style. The header text for this group uses “section-title” style.

o The second group uses table-group-1 style

o The third group uses table-group-2 style (and so on).

o The table-group-<n> style is applied to header cells, footer cells, and margin column cells.

o The group-data style is applied to the details row.

• Grid 3 is the second section of the template, which contains the following:


o 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.

o The first group of the table uses “table-group-1” style.

o The second group uses table-group-2 style

o The third group uses table-group-3 style (and so on).

o The table-group-<n> style is applied to header cells, footer cells and margin column cells.

o The group-data style is applied to the details row.

To modify the table contents, follow these steps:

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.

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,


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.


Follow the instructions in the previous section, Using TCR Templates, to modify 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.


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


If you chose a Bar 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.



6. All labels along the X axis and Y axis should use the default chart 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 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.” Enter the tooltip text that you want to show.

8. 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 demonstration purposes. In the Marker Properties section, enter the start value and end value of the range to specify your acceptable limits.

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.


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.

13. Drag the column header you want in the value to the “Value (Y) Series” 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.




16. 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.


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.


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.

5. Drag the column header you want in the value to the “Value (Y) Series” on the left. Add multiple value series as required by your chart type or add appropriate data.



8. 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 correct angle..

9. 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.


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> <Entries xsi:type="attribute:ColorDefinition"> <Transparency>255</Transparency> <Red>72</Red> <Green>153</Green> <Blue>119</Blue> </Entries> <Entries xsi:type="attribute:ColorDefinition"> <Transparency>255</Transparency> <Red>221</Red> <Green>205</Green> <Blue>93</Blue> </Entries> <Entries xsi:type="attribute:ColorDefinition"> <Transparency>255</Transparency> <Red>199</Red> <Green>134</Green> <Blue>57</Blue> </Entries> <Entries xsi:type="attribute:ColorDefinition"> <Transparency>255</Transparency> <Red>152</Red> <Green>96</Green> <Blue>48</Blue> </Entries> <Entries xsi:type="attribute:ColorDefinition"> <Transparency>255</Transparency> <Red>141</Red> <Green>134</Green> <Blue>142</Blue> </Entries> <Entries xsi:type="attribute:ColorDefinition"> <Transparency>255</Transparency> <Red>131</Red> <Green>162</Green> <Blue>176</Blue> </Entries> <Entries xsi:type="attribute:ColorDefinition"> <Transparency>255</Transparency> <Red>187</Red>


<Green>217</Green> <Blue>0</Blue> </Entries> </SeriesPalette>

For status-based coloring, refer to the StatusBasedColoringOfChart

sample.


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.


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.54.5 Sample ReportsSample Reports

4.5.1 TableWithDrillthrough Sample Report

This report contains an example of how a table can contain a link to a drill-through report.

In this sample, the table drills through (links to) the TableWithDrillthrough_subreport.


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.


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


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 sub-report by clicking on values.

The master report looks like this:

Clicking on a pie-chart value drills through to the ChartsWithDrillthrough_subreport report:


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.


4.5.3 DynamicColumnSort Sample ReportThis 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 ReportThis 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.


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


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.


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='none';document.getElementById('collapsePGText_2').style.display='block'; void(0)document.getElementById('collapsePGImage_2').style.display = 'block';


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='block';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


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 ReportThis 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).


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 SampleThis 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.


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 SampleThis 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){


// 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 ReportThis report demonstrates how to create summary totals in the footer row of a table.


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-footer-cell style from the Tivoli Common Reporting library.

In the Eclipse/BIRT designer, the layout for this report is as follows:


The data items for Total and Average use built-in BIRT JavaScript functions accessible from the Expression Builder:

4.5.13 DateRangeParameters Sample ReportThis 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, AMOUNTFROM 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, AMOUNTFROM 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


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:


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.AMOUNTFROM CUSTOMERS cus, PAYMENTS payWHERE cus.CUSTOMERNAME = 'AV Stores, Co.' AND cus.CUSTOMERNUMBER = pay.CUSTOMERNUMBERORDER BY cus.CUSTOMERNAME, pay.PAYMENTDATE,pay.CHECKNUMBER


To:SELECT cus.CUSTOMERNAME, pay.PAYMENTDATE,pay.CHECKNUMBER,pay.AMOUNTFROM CUSTOMERS cus, PAYMENTS payWHERE pay.PAYMENTDATE between '3/24/2007' and '6/22/2007' AND cus.CUSTOMERNAME = 'AV Stores, Co.' AND cus.CUSTOMERNUMBER = pay.CUSTOMERNUMBERORDER 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 ReportThis 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.


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.


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.


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.


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.


To display the Country parameter’s 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.64.6 ScriptsScriptsThe 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.jsGeneral purpose methods such as trimString(), getNLS(), setReportTitle(), and setRowCount().

4.6.2 DateTime.jsDate 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.


4.6.3 ModifyQuery.jsMethods 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.jsMethods to log from anywhere within a report design. The DateRangeParameters sample demonstrates the use of the logger script.


Section 5Section 5Best PracticesBest Practices

5.15.1 Projects and LibrariesProjects 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


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.25.2 General Report PropertiesGeneral 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.35.3 Globalization / LocalizationGlobalization / LocalizationThe 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.


5.3.1 Setting Up Basic GlobalizationTo 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 product’s 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>


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");</VALUE-OF>"><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:


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.45.4 Data SourcesData SourcesTypically, 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 ConventionBIRT 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


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.55.5 Data SetsData SetsRecommendations:

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.


5.65.6 Timestamps 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.


5.6.2 Timestamps in Tables and ParametersTimestamps 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 FooterTimestamps in footers should use the BIRT General Date format:

MMMM d, yyyy h:mm:ss a zAn example of this format is August 30, 2007 4:05:12 PM EDT


5.75.7 ChartsChartsThe 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.85.8 Useful Hints and Tips 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 TablesTables1. Create Grouped Tables from Templates: If you created a report with a non-

grouped 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 ChartsChartsControl 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


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 unknownfill.set(182,146,182);

}


Appendix A Appendix A Terminology 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.


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.


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.


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 inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user’s responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not give youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785 U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia CorporationLicensing2-31 Roppongi 3-chome, Minato-kuTokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION ″AS IS″ WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE.

Some states do not allow disclaimer of express or implied warranties in certaintransactions, 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 beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct and use of those Web sites is at your own risk.

© Copyright IBM Corp. 2007, 2009 A-1

IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

IBM Corporation2Z4A/10111400 Burnet RoadAustin, 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 materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement or any equivalent agreementbetween us.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

Trademarks

IBM, the IBM logo, ibm.com, DB2 and Tivoli are trademarks or registeredtrademarks of International Business Machines Corporation in the United States,other countries, or both.

Microsoft and Windows NT are registered trademarks of Microsoft Corporation inthe United States, other countries, or both.

Other company, product, and service names may be trademarks or service marksof 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.


Tcr Style Guide

Documents

Transcript of Tcr Style Guide