Getting Started with BIRT

  • submit to reddit

Getting Started with BIRT

By Virgil Dodson

13,334 Downloads · Refcard 49 of 199 (see them all)


The Essential BIRT Cheat Sheet

Eclipse Business Intelligence and Reporting Tools (BIRT) is an open source, Eclipse-based reporting system that integrates with your Java/J2EE application to produce compelling reports. BIRT is the only top-level Eclipse project focused on business intelligence.This DZone 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 Refcard should be interesting to report designers as well as developers or architects involved in integrating BIRT reports into applications.
HTML Preview

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.

Birt Components

Getting birt

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

BIRT All-In-One
The fastest way to get started designing BIRT reports on Windows.
Includes everything you need to start designing BIRT Reports,
including the full Eclipse SDK.
BIRT Framework This download allows you to add the BIRT plug-in to your existing
Eclipse environment. (Make sure you check the dependencies and
update those too.)
RCP Designer Simple to use rich client version of the BIRT Report Designer
dedicated to creating reports without the rest of the Eclipse
development environment.
BIRT Runtime Deployment components of the BIRT project including a command
line example, API examples, and example web viewer.
BIRT Web Tools Integration Contains the plug-ins required to use the BIRT Web Project Wizard
and the BIRT Viewer JSP tag library.

Hot Tip

You can also get BIRT into your existing Eclipse environment through the Eclipse Update Manager. Be sure to also select the Data Tools Project when using this approach.

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


Design File
An XML file that contains the data connection infromation, report layout and instructions. Created when making a report in the BIRT Designer.
Template File
Ensures all reports you create start with some common elements such as a company header or predefined syles. The starting point for a BIRT report.
Library File
Stores commonly used report elements, such as a company logo, so they are managed in one place for all reports.
Report Document
The completed report including layout instructions and data. Can be transformed into final report output, such as HTML, PDF, and XLS.

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.

Flat File Data Source Supports tab, comma, semicolon, and pipe delimited data
JDBC Data Source Supports connections to relational databases
Scripted Data Source Allows you to communicate with Java objects or to any data you can get from you application.
Web Services Data
Supports connections to a web service. A wizard helps you point at a service through a WSDL and select the data
XML Data Source Supports data from XML
Hive/Hadoop Data Source Allows access to Hadoop data through Hive using Hive Query Language (HQL)
Additional Data Sources BIRT has been extended by both the open source community and within commercial products allowing additional data connections to POJOs, Amazon RDS, LDAP, LinkedIn, Facebook, Excel, MongoDB, GitHub, and Spring Beans

Palette of report items

label Use to include static (or localized) text within a report. Typically for report titles, column headers or any other report text.
text Use to include richly formatted text to your report, including the ability to integrate HTML formatting with your dynamic data.
DynamicText Use to integrate your static text with dynamic or conditional data.
data Use to include data from your connection in the report.
image Use to include images from various embedded sources or dynamic locations.
grid Use to define the layout of a report. Can be nested within other grids to support complex layouts.
list 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.
table Use to display repeating data elements within your report and has support for multiple columns and multiple levels of grouping.
chart Use to add rich, interactive charting to your BIRT report.
Cross Tab Use to display grouped and dynamic data by both the row and column level.
aggregation 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 Chart1

Percent Stacked
2D, 2D w/depth, and 3D

Line Chart2 Sub-Types:
Percent Stacked
2D and 3D
Area Chart3 Sub-Types:
Percent Stacked
2D, 2D w/ Depth, and 3D
Pie Chart4 Sub Types:
Pie Charts
2D and 2D w/ Depth
Meter Chart5 Sub-Types:
Scatter Chart6 Sub-Types:
Stock Chart7 Sub-Types:
Bubble Chart8 Sub-Types:
Difference Chart9 Sub-Types:
Gantt Chart10 Sub-Types:
Tube Chart1 Sub-Types:
Percent Stacked
2D, 2D w/ Depth, and 3D
Cone Chart11 Sub-Types:
Percent Stacked
2D , 2D w/ Depth, and 3D
Pyramid Chart12 Sub-Types:
Percent Stacked
2D , 2D w/ Depth, and 3D
Radar Chart12 Sub-Types:
Additional Chart Types Chart12 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.

Hot Tip

Creating your first report:
  • Create a new Report Project from the category of Business Intelligence of Reporting Tools. Change to the Report Design perspective.
  • File -> New ->Report. Select the template called "My First Report" which launches a cheat sheet containing a step-by-step tutorial assisting you with connecting to data sources, creating data sets, and laying out your report.


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 can include a line that says "welcomeMessage=Willkommen". To use these files within a BIRT report:

Assign Resource File to entire report Report -> Properties -> Resources -> Resource File
Assign individual keys to a label Label -> Properties -> Localization -> Text key


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

Built-in Styles Built-in styles can be shared in a report library for managing style across multiple reports.
CSS Style Sheet BIRT can import CSS files at design time or reference existing CSS files at run time.

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 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") {
else {

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];


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

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

if (row["CREDITLIMIT"] <= 0) {
else {

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.

if (row[“myField”] > 0) {
         } else {


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.

function hidetable( tblbtn,tblname){
         var mytable=document.getElementById(tblname);
var hide=true;
         if( == 'none'){


         if( hide ){


For more scripting examples, visit 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.


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

Design Engine API(DE API) Use the Design Engine API (DE API) to create a custom report designer tool, or to explore or modify BIRT report designs. The BIRT Designer uses this API. You can call this API within a BIRT script to modify the currently running report design.
Report Engine API(RE API) Use the Report Engine API to run BIRT reports directly from Java code or to create a custom web application front end for BIRT.
Chart Engine API(CE API) Use the Chart Engine API to create and render charts apart from BIRT.

To see API examples, visit 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.

IRunAndRenderTask Use this task to run a report and create the output directly to one of the supported output formats. This task does not create a report document.
IRunTask Use this task to run a report and generate a report document, which is saved to disk.
IGetParameterDefinitionTask Use this task to obtain information about parameters and their default values.
IDataExtractionTask Use this task to extract data from a report document. The BIRT viewer uses this class to extract report data into CSV format.

Siple BIRT Engine Example

static void executeReport() throws EngineException
  IReportEngine engine=null;
  EngineConfig config = null;
  // start up Platform
  config = new EngineConfig( );
  config.setLogConfig("C:\\BIRT_231\\logs", java.util.logging.Level.
  Platform.startup( config );
  // create new Report Engine
  IReportEngineFactory factory = (IReportEngineFactory) Platform
  .createFactoryObject( IReportEngineFactory.EXTENSION_REPORT_
  engine = factory.createReportEngine( config );
  // open the report design
  IReportRunnable design = null;
  design = engine.openReportDesign("C:\\BIRT_231\\designs\\param
  // create RunandRender Task
  IRunAndRenderTask task = engine.createRunAndRenderTask(design);
  // pass necessary parameters
  task.setParameterValue("ordParam", (new Integer(10101)));
  // set render options including output type
  PDFRenderOption options = new PDFRenderOption();
  // run task;
}catch( Exception ex){
  Platform.shutdown( );

Hot Tip

Platform startup and shutdown should only occur at the beginning and the end of the application, respectively.  Also, be sure to get the jars from the reportengine/lib directory in the runtime download added to the classpath/buildpath.

Web Viewer

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:

Stand-alone Use as a pre-built web application for running and viewing reports.
Modify Viewer Source Use as a starter web application that you can customize to your needs.
RCP Application Use as a plug-in for your existing RCP application.
Integrated with existing web application The viewer can be integrated with URLs or BIRT JSP tag library.

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

/frameset Renders the report in the full AJAX viewer, complete with toolbar, navigation bar
and table of contents features. This mapping also generates an intermediate
report document from the report design file to support the AJAX based features.
For example.
http://localhost:8080viewer/frameset?_report=myreport .rptdesign&parm1=value
/run Runs and renders the report but does not create a report document. This
mapping does not supply HTML pagination, TOC or toolbar features, but does
use the AJAX framework to collect parameters, support report cancelling and
retrieve the report output in HTML format. For example.
/preview Runs and renders the report but does not generate a report document, although
an existing report document can be used; in this case, just the render operation
occurs. The output from the run and render operation is sent directly to the
browser. For example

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.

Attribute Description
__id Unique identifier for the viewer.
__title Sets the report file.
__showtitle Determines if the report title is shown in the frameset viewer. Defaults to true. Valid values are true and false.
__toolbar Determines if the report toolbar is shown in the frameset viewer. Defaults to true. Valid values are true and false.
__navigationbar Determines if the navigation bar is shown in the framset viewer. Defaults to true. Valid values are true and false.
__parameterpage Determines if the parameter page is displayed. By default, the frameset, run, and preview mappings automatically determine if the parameter page is required. This setting overrides this behavior. Valid values are true and false.
__report Sets the name of the report design to process. This setting can be absolute path or relative to the working folder.
__document Sets the name for the rptdocument. The document is created when the report engine separates run and render tasks, and is used to support features like table of contents and pagination. This setting can be an absolute path or relative to the working folder.
__format Specifies the desired output format, such as pdf, html, doc, ppt, or xls.
__Locale Specifies the locale for the specific operation. Note that this setting overrides the default locale.
__page Specifies page to render.
__pagerange Specifies page range to render such as, 1-4, 7.
__bookmark Specifies a bookmark in the report to load. The viewer automatically loads the appropriate page.

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.

Attribute Description
This setting sets the default locale for the Web Viewer.
This is the default location for report designs. If the report design specified
in a URL parameter is relative, this path is pre-pended to the report name.
If the __document parameter is not used, a report document is generated
in this location. If this setting is left blank, the default value, webapp/
documents, is used. If the__document URL parameter is used and the value
is relative, the report document is created in the working folder.
Specifies the default location to store temporary images generated by the
report engine. If this setting is left blank, the default location of webapp/
report/images is used.
Specifies the default location to store report engine log files. If this setting
is left blank, the default location of webapp/logs is used.
Sets the report engine log level. Valid values are:
Specifies the default location to place JAR files used by the script engine
or JARs containing Java event handlers. These JARs are appended to the
classpath. If this setting is left blank the default value of webapp/scriptlib
will be used.
This setting specifies the resource path used by report engine. The
resource path is used to search for libraries, images, and properties files
used by a report. If this setting is left blank, resources are searched for in
Specifies the maximum number of rows to retrieve from a dataset
This setting specifies whether server side printing is supported. If
set to OFF the toolbar icon used for server side printing is removed
automatically. Valid values are ON and OFF.

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.

Tag Description
viewer Displays the complete Viewer inside an IFRAME. This tag allows you to use frameset and run Servlet mappings. The AJAX Framework is used.
report Displays the report inside an IFRAME or DIV tag without the Viewer. This tag allows you to use preview mapping and does not create an rptdocument. The AJAX Framework is not used.
param Used to set parameter values when using the viewer or report tags. This tag must be nested within the viewer or report tag.
value Used to specify multiple values for a given param tag.
parameterPage Used to launch the BIRT parameter dialog or to create a customized parameter entry page. This tag can be used with the frameset, run, or preview mappings to launch the viewer after the parameters are entered.
paramDef Used within a parameterPage tag to retrieve pre-generated HTML for specific parameter control types such as radio, checkbox, dynamic or cascaded parameters

Simple viewer jsp tag example

<%@ taglib uri="/birt.tld" prefix="birt" %>
id="birtViewer" pattern="preview"
height="600" width="800"
title="My Viewer Tag"
showTitle="true" showToolBar="true"


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.

Paginated web output An example web viewer is included with BIRT allowing for on demand paginated web output.
DOC Microsoft Word Document.
HTML Suitable for creating HTML pages of report data deployable to any server.
PDF Adobe PDF output suitable for emailing or printing.
Postscript Output can be directed to a printer that supports postscript.
Open Document Text, Spreadsheet, and Presentation

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

Data Sources BIRT supports the Open Data Access (ODA) architecture, which means it can be extended to support custom data sources.
Functions BIRT allows you to create custom functions that extend those available in BIRT Expressions.
Report Items Report Items can be extended, allowing you to create your own custom report item.
Chart Types Additional chart types can be added to BIRT as plug-ins.
Output Emitters BIRT can be extended to include your own custom output type. For example, a simple CSV emitter exists and can be added to BIRT.

Additional Birt resources

Eclipse BIRT Project Site
BIRT Exchange Community Site
Submitting/Searching BIRT Bugs
Online BIRT Documentation

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.

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

Share this Refcard with
your friends & followers...

DZone greatly appreciates your support.

Your download should begin immediately.
If it doesn't, click here.


lasib tanhir replied on Mon, 2009/10/19 - 10:37am

Thank you for the view of the BIRT components. straight BIRT Runtime APIs are very interesting for me.

Jams Jammy replied on Fri, 2014/02/07 - 5:53am in response to: lasib tanhir

 : A  toolkit for kickstarting HTML, CSS and JavaScript for websites and apps including base styles for typography, forms, buttons, tables, grids, navigation, alerts, and more.

licensed and insured Atlanta movers

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.