BIRT Report Prototype Development,
Deployment and Integration
Specification
Version 1.0
2/9/2006
Author: Tim Byrne
Abstract:
The purpose of this document is to describe how a prototype ‘usage’ report for the
‘Gratia’ project at Fermi National Accelerator Laboratory was developed, deployed and
integrated. It will assume a fundamental knowledge of the Eclipse IDE. This is not a design
document for the usage reports, and no details on the inner workings of said reports will be
provided.
Table of Contents
Revision History ......................................................................................................................... 3
Development ............................................................................................................................... 4
Eclipse ..................................................................................................................................... 4
BIRT ....................................................................................................................................... 4
Reporting Solution .................................................................................................................. 4
Deployment ................................................................................................................................. 9
BIRT WAR File (one-time deployment) ................................................................................ 9
Project WAR Files .................................................................................................................. 9
Tomcat Application Manager ................................................................................................. 9
Integration ................................................................................................................................. 10
Frameset Integration ............................................................................................................. 10
Web Integration .................................................................................................................... 10
Full Integration...................................................................................................................... 10
Revision History
Version Date
Author
1.0
02/09/2006 Tim Byrne
Notes
Initial Release
Development
Eclipse
Eclipse is an open source development suite that has the ability to implement ‘plugins’
that allow for graphical design and development of features outside of the initial Eclipse toolset.
Follow the directions outlined in the ‘Gratia Collector Web Service Development, Deployment
and Integration’ document to install and configure Eclipse.
BIRT
Business Intelligence and Reporting Tools (BIRT) is an open source plugin for Eclipse
that allows the user to graphically design and test reports within the Eclipse project framework.
To install BIRT, follow the step-by-step directions outlined here:
http://www.eclipse.org/birt/phoenix/build/
Reporting Solution
The Gratia reporting solution is actually made up of three distinct projects:
Configurator Project
The ‘Configurator’ project is a project of convenience. It is made up simply of two xml
files that will be different depending on the run-time environment. The reason these files were
disconnected from the other projects was simply so that the developer does not need to
reconfigure them each time a new version of the reporting project is deployed, these
configuration files can be deployed only once and independently of any other project builds. The
two XML files currently in this project are:
Reporting Config
Reporting Config is intended to be loaded once by the server (statically) for the
lifetime of the application. It contains values specific to the environment that are
required by the reporting engine. Specifically, this file contains the path to the report
design files, the default data source information, the path to the reporting engine itself
and the path to the Gratia Reporting project.
User Config
User Config is a sample configuration file that dictates what links appear on the
menu and what reports appear on the dashboard. The intent for the future is that each
user would have their own user config file specific to their needs, but for now all users
share this configuration. The user configuration would be loaded into session each time a
user logs into the application.
Reports Project
The ‘Reports’ project is designed to contain all of the report design files that might be
viewed within an application. Keeping them in their own project allows minor revisions to one
or more reports to be deployed without redeploying an entire application. The report design files
in this project are created using the BIRT tool within Eclipse, which is fairly straight forward to
use and its use will not be covered in this document (BIRT tutorials can be found on the BIRT
homepage at http://www.eclipse.org/birt/phoenix/tutorial). However, there are a view specific
development tricks used in BIRT for specific reporting capabilities, and those will be
documented here for future reference:
Dynamic Data Point Coloring
It is often necessary to change the color of a data point (a bar or pie slice) based on the
value of the data it represents. Achieving this functionality in the BIRT tool involves custom
scripting on a chart engine event which can be done by following these steps:

Open the report in the BIRT designer.

Select the chart that needs to custom functionality.

Beneath the report designer interface, select the ‘scripts’ tab.

All of the possible events that the selected chart can handle will appear commented
out in this screen. For this particular case, locate the ‘beforeDrawDataPoint’ handler
and code it like so:
function beforeDrawDataPoint( dph, fill, context )
{
val = dph.getOrthogonalValue();
if (val < 10)
fill.set(255, 0, 0); //yes - display in red
else
fill.set(0, 0, 255); //no - display in blue
}

Note that ‘val’ is the value of the data point and the ‘fill.set’ sets the color of the data
point to the given RGB value.
Drill Down Reports
Many charts and graphs require the ability to click a particular data point and ‘drill down’
into the details of that data. Follow these steps to achieve that functionality in BIRT:

Design two reports with a parent-child relationship (simply making a parameter of the
child report relate to a data point on the parent report is enough).

In the parent report, double click the chart that needs the drill down capability.

Navigate to the ‘Format Chart’ tab.

Click the ‘Series’ – ‘Value (Y) Series’ menu item.

Click the ‘Interactivity’ button.

In the dialog that appears, select ‘Mouse Click’ as the type and ‘URL Redirect’ as the
action.

Click the ‘Edit Base URL’ button.

In the dialog that appears, select the ‘Drill-through’ radio option. Then brows for the
child report in the ‘Report’ field.

In the report parameter section, map any related child parameter values to their
corresponding report parameter values. Do not set the value of the child report
parameter that is being driven by the parent report.

Set the target equal to ‘self’ and click ‘OK’.

In the ‘Category Series’ field, enter the name of the child parameter that relates the
parent report’s data.

Click ‘add’ to add this interactivity function, close the interactivity dialog and click
‘Finish’.
Dynamic Data Source
All BIRT reports are designed around a data source. While this data source is stored
within the report definition, it is possible to set it at run time in the form of report parameters.
To do so, follow these steps:

Open the report in the BIRT designer.

Add report parameters for the database URL and optionally parameters for the
username and password.

In the ‘Data Explorer’ window, drill down into ‘Data Sources’ and double click the
report’s data source.

In the resulting dialog, select the ‘Property Binding’ menu item.

For each property, use the ‘…’ button to map it to its corresponding report parameter
field.

Now, at runtime, it is possible to specify the data source to use by passing in values to
the database parameters.
Date Zooming
A useful feature of date-based reports is to have the ability to click a subset of data and
‘zoom’ to display only the selected data. For example, on a line graph showing a years worth
of data where each point is a month, it should be possible to display only October to
December by first clicking the ‘October’ axis label and then clicking ‘December’. To
achieve this functionality in BIRT perform the following steps:

Design a report with likely ‘zooming’ capabilities.

Make a copy of the report, and in the copy add a parameter for the ‘InitialSelection’.
The functionality here is that when a data point on the chart is clicked, it will drill
through to an identical report but pass the value of the clicked item through as the
‘InitialSelection’ parameter. This can be achieved by following the ‘Drill Down
Reports’ section.

In the report copy, everything must function the same besides for two key areas:

The InitialSelection must be highlighted via script. This is done by adding the
following code to the chart’s script, similar to the Dynamic Data Point Coloring
example:
function beforeDrawAxisLabel( axis, label, context )
{
rep = context.getExternalContext().getScriptable();
val = rep.getParameterValue("InitialSelection");
if(val == null)
val = "";
if(val.equals(label.getCaption().getValue()))
label.getOutline().setVisible(true);
else
label.getOutline().setVisible(false);
}

Secondly, the report copy must drill through back to the original report passing the
‘InitialSelection’ parameter as the start parameter and the clicked data point value as
the end parameter.
Gratia Reporting Project
The ‘Gratia Reporting’ project is a ‘Dynamic Web Project’ created in Eclipse 3.1 to
contain all the logic required to view a BIRT report, including handling parameter entry, drill
downs and custom menu and dashboard configurations.
To recreate this project in Eclipse, follow these steps:

Start the Eclipse 3.1 IDE.

From the menu, select ‘File’ – ‘New’ – ‘Project’.

In the ‘New Project Wizard’, select ‘web’ – ‘Dynamic Web Project’ and click ‘Next’.

Name the project ‘GratiaReporting’ and click ‘Finish’ to accept the rest of the default
settings.

The project ‘GratiaReporting’ should now appear in your package explorer, which should
appear on the left hand side of the screen. If it does not, ensure that the ‘Java’
perspective is open by selecting ‘Java’ in the upper right-hand corner of the screen.

Copy the structure of the GratiaReporting project (From CVS?) into the GratiaReporting
folder on your hard drive. Refresh the project in the Eclipse package explorer (right click
the project and select ‘Refresh’) and the source code will appear in the explorer.

Several BIRT jar files will need to be included in the build path in order for this project to
build correctly. To do so, right click the GratiaReporting project and select ‘properties’.
Select the ‘Java Build Path’ node, and then select the ‘Libraries’ tab on the right-hand
side. In this dialog, click the ‘Add External Jars’ button and select the following jar files
which should be located wherever you installed BIRT: chart-engine.jar, core.jar,
engine.jar, model.jar and dom4j-1.6.1.jar.
Deployment
BIRT WAR File (one-time deployment)
A current BIRT WAR file will be supplied (from CVS?) that contains all of the classes
and libraries required to view BIRT reports from a Tomcat server. This WAR file was created
following the procedure at http://www.eclipse.org/birt/phoenix/deploy/viewerSetup.php. This
WAR file needs to be deployed once via the Tomcat Application Manager as outlined below.
One special caveat to make a note of is that the jar files in this war file need to be copied from
their default installed location (tomcat/webapps/Birt/WEB-INF/lib) to tomcat/common/lib. The
reason for this is so that any reporting application that needs to display the reports can share the
reporting jar files from common/lib instead of having to include them within its own lib folder.
If Tomcat were to allow us to extend the ‘class path’ that it uses to find common jars, this
duplication would not be necessary.
Project WAR Files
A ‘Web Archive’ (WAR) file is simply a packaged webapp directory that many web servers
(Tomcat, in particular) use to install web applications. For the reporting project, this WAR file
will simply contain all of the reports that will be made visible to a user and using a WAR file
streamlines deployment to a Tomcat server. Creating a WAR file in Eclipse is simple. To do so,
follow these steps:

Start the Eclipse 3.1 IDE and ensure that the ‘GratiaServices’ project is open and built.

Right click the ‘Configurator’, ‘Reports’ or ‘GratiaReporting’ project and select ‘Export’.

In the ‘Export’ dialog, select ‘WAR File’ and click ‘Next’.

In the ‘WAR Export’ dialog, select the ‘Configurator’, ‘Reports’ or ‘GratiaReporting’
web module and for the destination of the WAR file be sure that the name is [project
name].war. Click ‘Finish’ and the WAR file will be created at the destination.
Tomcat Application Manager
Tomcat servers provide an easy to use interface for deploying WAR files. Follow these steps
to deploy a WAR file on a typical Tomcat server:

Browse to the Tomcat server’s home page, typically on port 8080.

Select ‘Tomcat Manager’ from the ‘Administration’ links on the left side of the screen.

Log in as a user with access to the ‘manager’ role

In the ‘WAR File to Deploy’ box, click ‘Browse’ and select the WAR file created.

Click ‘Deploy’ and the web service will be created.
Integration
Frameset Integration
The BIRT Viewer contains a fully web-enabled report viewer that allows for interactive
parameter entry, navigation and data export into a variety of formats. To access this view of a
report, simply enter the link into a web browser matching this format:
http://hostname:8080/birt/frameset?__report=../reports/reportname.rptdesign
Keep in mind that the portion of this link named ‘reports’ matches the name of the WAR file
used to deploy the report being accessed.
Web Integration
There is a lighter version of the viewer that contains no additional features other than
displaying the data in the report. This view of the report is accessed using the exact same link as
the Frameset Integration, except the ‘frameset’ portion is replaced by ‘run’. Parameters are
supplied to the report inline with the URL, which is not very user friendly and therefore would
have to have an interface built around it allowing the users to specify parameters. This solution
requires some development time, unlike the frameset integration, and should only be considered
if frameset integration is not flexible enough to account for all reporting options.
Full Integration
The Gratia Reporting project contains a custom implementation for viewing BIRT
reports. More information on this implementation can be found in the Gratia Reporting Design
Specification.