Getting Started with BIRT

By Michael Williams

What Is Birt?

Eclipse Business Intelligence and Reporting Tools (BIRT) is an open-source, Eclipse-based reporting system that integrates with your Java EE application to produce compelling reports. BIRT is the only top-level Eclipse project focused on business intelligence. BIRT provides core reporting features such as report layout, data access, and scripting. This Refcard provides an overview of the BIRT components, focusing on a few key capabilities of the BIRT Designer, BIRT Runtime APIs, and BIRT Web Viewer. This information should be interesting to report designers as well as to developers or architects involved in integrating BIRT reports into applications.

Design and Runtime components

BIRT has two main components: a report designer based on Eclipse, and a runtime component that you can add to your application. The charting engine within BIRT can also be used by itself, allowing you to add charts to your application.

Getting birt

Open Source BIRT can be downloaded from http://download. eclipse.org/birt/downloads/ or http://www.birt-exchange. com. There are several different packages containing BIRT depending on your needs.

BIRT report designers

The BIRT report designers are easy-to-use, visual report development tools that meet a comprehensive range of reporting requirements. The report designers include taskspecific editors, builders, and wizards that make it easy to create reports that can be integrated into web applications. All BIRT report designers support:

• Component-based model for reuse
• Ease of use features
• Support for a wide range of reports, layouts and formatting
• Programmatic control
• Data access across multiple data sources

BIRT FILE TYPES

BIRT Data Sources

BIRT supports a variety of data sources and can be extended to support any data to which you have access. In addition to the list below, BIRT also ships with a connection to the ClassicModels sample database and can be easily extended to connect to your custom data source. BIRT also includes a Joint Data Set which allows you to join data across data sources.

Palette of report items

	Use to include static (or localized) text within a report. Typically for report titles, column headers or any other report text.
	Use to include richly formatted text to your report, including the ability to integrate HTML formatting with your dynamic data.
	Use to integrate your static text with dynamic or conditional data.
	Use to include data from your connection in the report.
	Use to include images from various embedded sources or dynamic locations.
	Use to define the layout of a report. Can be nested within other grids to support complex layouts.
	Use to display Data elements from your data source that repeat and creates a new report row for each daata set row. Can contain multiple levels of grouping.
	Use to display repeating data elements within your report and has support for multiple columns and multiple levels of grouping.
	Use to add rich, interactive charting to your BIRT report.
	Use to display grouped and dynamic data by both the row and column level.
	Use to build totals for tables and groups. Includes over 30 built-in functions like COUNT, SUM, MAX, MIN, AVE, RUNNINGSUM, COUNTDISTINCT, and RANK.
Additional Report Items	BIRT has been extended by both the open source community and within commercial products providing additional report items such as Google Translate item, HTML5 charts, Flash gadgets/objects, and interactive HTML buttons.

Chart types

Bar		Sub-Types: Side-by-Side Stacked Percent Stacked Dimensions: 2D, 2D w/depth, and 3D
Line		Sub-Types: Overlay Stacked Percent Stacked Dimentions: 2D and 3D
Area		Sub-Types: Overlay Stacked Percent Stacked Dimensions: 2D, 2D w/ Depth, and 3D
Pie		Sub Types: Pie Charts Dimensions: 2D and 2D w/ Depth
Meter		Sub-Types: Standard Superimposed Dimensions: 2D
Scatter		Sub-Types: Standard Dimensions: 2D
Stock		Sub-Types: Candlestick Bar-Stick Dimension 2D
Bubble		Sub-Types: Standard Dimensions: 2D
Difference		Sub-Types: Standard Dimensions: 2D
Gantt		Sub-Types: Standard Dimensions: 2D
Tube		Sub-Types: Side-by-Side Stacked Percent Stacked Dimensions: 2D, 2D w/ Depth, and 3D
Cone		Sub-Types: Side-by-Side Stacked Percent Stacked Dimensions: 2D , 2D w/ Depth, and 3D
Pyramid		Sub-Types: Side-by-Side Stacked Percent Stacked Dimensions: 2D , 2D w/ Depth, and 3D
Radar		Sub-Types: Standard Spider Bullseye Dimensions: 2D
Additional Chart Types		BIRT has been extended by both the open source community and within commercial products providing additional chart types such as heat maps, segment charts, HTML 5 charts, Flash Charts, and Flash Maps.

Localization

BIRT supports internationalization of report data including support for bidirectional text. BIRT also supports the localization of static report elements within a report allowing you to replace report labels, table headers, and chart titles with localized text. BIRT uses resources files with name/value pairs and a *.properties file extension. For example, a file called MyLocalizedText_de.properties can include a line that says "welcomeMessage=Willkommen". To use these files within a BIRT report:

Styles

Reports designed with the BIRT report designer can be richly formatted with styles that match your existing web application

Below are some examples of CSS styles:

.table-header {
  background : #93BE95;
  border-bottom : double;
  border-top : solid;
  border-top-width : thin;
  border-color : #483D8B;
  font-family : sans-serif;
  font-size : x-small;
  font-weight : bold;
  color : #FFFFE0;
}
.table-detail {
  background : #DFECDF;
  font-family : sans-serif;
  font-size : x-small;
  color : #426E44;
}
.table-footer {
  background : #93BE95;
  border-top : double;
  border-bottom : solid
;  border-bottom-width : thin;
  border-color : #483D8B;
  font-family : sans-serif;
  font-size : x-small
;  font-weight : bold;
  color : #FFFFE0;
}
.crosstab-detail {
  background : #DFECDF;
  font-family : sans-serif;
  font-size : x-small;
  color : #426E44;
}
.crosstab-header {
  background : #5B975B;
  font-family : sans-serif;
  font-size : small;
  font-weight : bold;
  color : #FFFFE0;
}
.crosstab-cell {
  border-top : solid;
  border-top-width : thin;
  border-bottom : solid;
  border-bottom-width : thin;
  border-left : solid;
  border-left-width : thin;
  border-right : solid;
  border-right-width : thin;
  border-color : #294429;
}

To see style examples, visit http://www.birt-exchange.org/org/devshare and enter keyword “style”.

Customization with Expressions, Scripting and Events

BIRT includes out-of-the-box functionality that is available through drag-and-drop or by setting some properties,. BIRT also supports more advanced customizations through expressions, scripting, and events.  The expression builder in BIRT allows you to do conditional report processing just about anywhere you need to instead of hard coding values. For example, the expression below will display the shipped date for orders that have already shipped; otherwise, it will display the order date.

if (dataSetRow["STATUS"] == "Shipped") {
  dataSetRow["SHIPPEDDATE"];
} else {
  dataSetRow["ORDERDATE"];
}

Scripting of a BIRT report can be done in either JavaScript or Java depending on your skill set and needs. Scripting allows you to circumvent the traditional event processing of the BIRT report.  You can add scripting to report object, data source, and data element event types. Each of these event types has several events that you can overwrite.

For example, you can use scripting to navigate your Java objects and add them to a BIRT Data Set.

favoritesClass = new Packages.SimpleClass();
favorites = favoritesClass.readData();
…
var favrow = favorites.get(currentrow);
var Customer = favrow[0];
var Favorite = favrow[1];
var Color = favrow[2];

row["Customer"]=Customer;
row["Favorite"]=Favorite;
row["Color"]=Color;

Use scripting to change bar colors on a chart based on plotted data.

if (dph.getOrthogonalValue() < 1000) {
  fill.set(255,0,0); //red
} else if (dph.getOrthogonalValue() < 5000) {
  fill.set(255,255,0); //yellow
} else {
  fill.set(0,255,0); //green
}

Use scripting to add or drop a report table based on a user parameter.

if (params["showOrders"] == false){
reportContext.getDesignHandle().findElement("ordersTable").drop();
}

Or use scripting to include dynamic images that are based on the report data.

if (row["CREDITLIMIT"] <= 0) {
"down.jpeg"
} else {
"up.jpeg"
}

You can also use scripting within a text box using the <value-of> tag for generation time evaluation or with the <viewtime-value-of> tag for render time evaluation.

       <value-of>
if (row[“myField”] > 0) {
         “positive”
         } else {
         “negative”
         }
         </value-of>

         <viewtime-value-of>
         vars[“Group_Page”]
         </viewtime-value-of>

Or use html <script> tags to create client-side script, like creating a function to hide a certain table that will be called by an html button.

       <script>
function hidetable( tblbtn,tblname){
         var mytable=document.getElementById(tblname);
var hide=true;
         if(mytable.style.display == 'none'){
                  hide=false;
         }

         if( hide ){
                  document.getElementById(tblbtn).value="+";
                  mytable.style.display='none';
         }else{
                  document.getElementById(tblbtn).value="-";
                  mytable.style.display='';
         }
}
</script>

For more scripting examples, visit http://www.birt-exchange.org/org/devshare and enter keyword “scripting”.

Report deployment options

Once you create your report design, there are several different ways to generate the report output.  Obviously, you can run these reports directly from the BIRT Designer, but you can also run BIRT reports from the command line, generate BIRT reports from your Java application using the BIRT APIs, integrate and customize the example web viewer, or deploy your reports within commercial business intelligence servers.

APIs

BIRT supplies several APIs and an example Java EE application for generating and viewing reports. The major APIs are the Design Engine API(DE API), Report Engine API(RE API) and the Chart Engine API (CE API). In addition to the APIs, BIRT supports scripting using either Java or JavaScript within report designs..

To see API examples, visit http://www.birt-exchange.org/org/devshare and enter keyword “API”.

Birt report engine tasks

There are several tasks supplied by the Report Engine API that can be used to generate report output. A few key tasks are listed below.

Siple BIRT Engine Example

static void executeReport() throws EngineException
{
  IReportEngine engine=null;
  EngineConfig config = null;
try{
  // start up Platform
  config = new EngineConfig( );
  config.setBIRTHome("C:\\BIRT_231\\birt-runtime-2_3_1\\
  ReportEngine");
  config.setLogConfig("C:\\BIRT_231\\logs", java.util.logging.Level.
  FINEST);
  Platform.startup( config );
  // create new Report Engine
  IReportEngineFactory factory = (IReportEngineFactory) Platform
  .createFactoryObject( IReportEngineFactory.EXTENSION_REPORT_
  ENGINE_FACTORY );
  engine = factory.createReportEngine( config );
  // open the report design
  IReportRunnable design = null;
  design = engine.openReportDesign("C:\\BIRT_231\\designs\\param
  .rptdesign");
  // create RunandRender Task
  IRunAndRenderTask task = engine.createRunAndRenderTask(design);
  // pass necessary parameters
  task.setParameterValue("ordParam", (new Integer(10101)));
  task.validateParameters();
  // set render options including output type
  PDFRenderOption options = new PDFRenderOption();
  options.setOutputFileName("my_report.pdf");
  options.setOutputFormat("pdf");
  task.setRenderOption(options);
  // run task
  task.run();
  task.close();
  engine.destroy();
}catch( Exception ex){
	ex.printStackTrace();
}
finally
{
  Platform.shutdown( );
}

Web Viewer

The BIRT WebViewer is an example application that illustrates generating and rendering BIRT report output in a web application. This viewer demonstrates report pagination, an integrated table of contents, report export to several formats, and printing to local and server-side printers.

The BIRT Web Viewer can be used in a variety of ways:

The BIRT Web Viewer consists of two main Servlets, the ViewerServlet and the BirtEngineServlet. These Servlets handle three mappings: (/frameset, /run, and /preview).

Viewer URL Parameters

Below are a few of the key URL parameters available for the viewer. These parameters can be used along with the Servlet mappings, such as, run, frameset, and preview, listed in the Web Viewer section.

Viewer Web.xml settings

The BIRT Web Viewer has several configuration options. These settings can be configured by modifying the web.xml file located in the WebViewerExample/WEB-INF folder. Below are a few of the key settings available for the viewer.

Viewer JSP Tag library

The BIRT Web Viewer includes a set of tags to make it easy to integrate BIRT reports into browser pages. These tags are available from the BIRT Web Tools Integration download. Below are a few the key JSP tags and a description of their usage.

Simple viewer jsp tag example

<%@ taglib uri="/birt.tld" prefix="birt" %>
�
<birt:viewer
id="birtViewer" pattern="preview"
reportDesign="TopNPercent.rptdesign"
height="600" width="800"
format="html"
title="My Viewer Tag"
isHostPage="false"
showTitle="true" showToolBar="true"
showNavigationBar="true"
showParameterPage="true">
</birt:viewer> 

BIRT REPORT OUTPUT FORMATS

In addition to delivering paginated report content to a web browser, BIRT also supports several other output formats. These formats listed below are support by both the Report Engine API as well as the BIRT Web Viewer.

Birt extension points

The APIs in BIRT define extension points that let the developer add custom functionality to the BIRT framework. These extensions can be in the form of custom data sources, report items, chart types, output formats, and functions.  Once implemented, these custom extensions will show along with the built-in types.  For example, you can create a custom report item, like a rotated text label, that will show up in the BIRT Palette along with the existing items.  Below are some of the “more common” extension points..

Additional Birt resources

About The Author

Michael Williams

Michael Williams graduated from The University of Kansas with a degree in computer engineering.
Currently, he works as a BIRT Evangelist at Actuate, where he has been working with BIRT for the past 4 years. One of his roles is to provide technical content for the BIRT Exchange website, in the form of, DevShare articles, monitoring the forums, and maintaining a blog. Other roles include putting together the BIRT Report newsletter, attending software conferences as a technical presence at the BIRTExchange booth, and the occasional speaking session.
http://www.birt-exchange.org

Recommended Book

Topics Discussed Include: Installing and deploying BIRT Deploying a BIRT report to an application server Understanding BIRT architecture Scripting in a BIRT report design Integrating BIRT functionality in applications Working with the BIRT extension framework

---

BUY NOW

books.dzone.com/books/integrating-extending-birt