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
BIRT Report Prototype Development, Deployment and Integration Specification............................1 Table of Contents..............................................................................................................................2 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 reports 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 reports 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 charts 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 servers 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.