Date: 12/21/2017 Page: 1 - 17

BIRT Overview

Report Introduction

BIRT is an Eclipse-based open source reporting system for web applications, especially those based on Java and J2EE. BIRT has two
main components: a report designer based on Eclipse, and a runtime component that you can add to your app server. BIRT also offers
a charting engine that lets you add charts to your own application.

The current released version is 2.1.2. We encourage you to download BIRT, try it, and give us your feedback though the newsgroups
and Bugzilla.

With BIRT, you can add a rich variety of reports to your application.

 Lists - The simplest reports are lists of data. As the lists get longer, you can add grouping to organize related data together
(orders grouped by customer, products grouped by supplier). If your data is numeric, you can easily add totals, averages and
other summaries.
 Charts - Numeric data is much easier to understand when presented as a chart. BIRT provides pie charts, line & bar charts
and many more. BIRT charts can be rendered in SVG and support events to allow user interaction.
 Crosstabs - Crosstabs (also called a cross-tabulation or matrix) shows data in two dimensions: sales per quarter or hits per
web page. (Crosstabs are not yet in Release 2.1.2, but are planned for the 2.2 release.)
 Letters & Documents - Notices, form letters, and other textual documents are easy to create with BIRT. Documents can
include text, formatting, lists, charts and more.
 Compound Reports - Many reports need to combine the above into a single document. For example, a customer statement
may list the information for the customer, provide text about current promotions, and provide side-by-side lists of payments and
charges. A financial report may include disclaimers, charts, tables all with extensive formatting that matches corporate color
schemes.

The Anatomy of a Report

BIRT reports consist of four main parts: data, data transforms, business logic and presentation.

 Data - Databases, web services, Java objects all can supply data to your BIRT report. Release 2.1.2 provides JDBC and XML
support, as well as support for using code to get at other sources of data. BIRT's use of the Open Data Access (ODA)
framework allows anyone to build new UI and runtime support for any kind of tabular data. Further, a single report can include
data from any number of data sources. BIRT also supplies a feature that allows disparate data sources to be combined using
inner and outer joins.
 Data Transforms - Reports present data sorted, summarized, filtered and grouped to fit the user's needs. While databases can
do some of this work, BIRT must do it for "simple" data sources such as flat files or Java objects. BIRT allows sophisticated
operations such as grouping on sums, percentages of overall totals and more.
 Business Logic - Real-world data is seldom structured exactly as you'd like for a report. Many reports require business-specific
logic to convert raw data into information useful for the user. If the logic is just for the report, you can script it using BIRT's
JavaScript support. If your application already contains the logic, you can call into your existing Java code.
 Presentation - Once the data is ready, you have a wide range of options for presenting it to the user. Tables, charts, text and
more. A single data set can appear in multiple ways, and a single report can present data from multiple data sets.

Step-by-Step BIRT Tutorial We'll create a simple customer listing report, with the
customers grouped by state and city. For each customer, we'll
Step1 display a name and phone number.

 Introduction
Install BIRT
Introduction
If you have not yet done so, install Eclipse, GEF, EMF and
This brief tutorial walks you through building a simple report with BIRT. You'll find complete instructions for doing so on the BIRT
BIRT. It introduces the major UI features, and many of the BIRT Install page.
reporting elements. At the completion of this tutorial, you should be
able to start building your own reports using your own database.
Date: 12/21/2017
Open BIRT
BIRT is a perspective within Eclipse. To open it, use the Window
item on the Eclipse main menu. Choose Open Perspective, then
Report Design. If report Design does not appear directly in the
Open Perspective window, then choose Other... A list of
perspectives will appear. Choose Report Design.
Eclipse will switch to display the BIRT perspective.
Example Report
If you get stuck as you work through the tutorial, or if you want to
see the finished report right away, simply download it:
 Use your browser to download the report:
customers.rptdesign.
 Save the file into an Eclipse project directory. (See the
next page if you don't yet have a project.)
 Your browser may store this as an XML file. If so, rename
it back the the name above.
 Within Eclipse, select your project in the Navigator view
and choose Refresh from the right-click context menu.
 Double-click the report to open it in the BIRT report
designer.
Step2
 Create a Project
 Create a Report
 Choose a Template
Create a Project
Eclipse uses projects to organize your files. So, the first step is to
create a new project. For this demo, let's create a project called
"My Reports":
 Choose File→New→Project. The new project dialog
appears.
 Open the "Business Intelligence and Reporting Tools"
group and choose "Report Project".
 Click Next.
 Type "My Reports" (without the quotes) as the project
name.
 Click Finish.
 Click OK if asked to switch to the Report Design
perspective. (This occurs if you create a BIRT project
while in a perspective other than Report Design.)
Create a Report
We're now ready to create our first report:
 Choose File→New→Report. The new report dialog
appears.
 In the tree view, choose the project we just created: My
Reports.
 Enter the following in the file name field:
Customers.rptdesign.
Page: 2 - 17
 Click Next.
You can create a report in three ways: as a blank report, by
using a BIRT-defined template, or by copying one of your
report designs. In this tutorial we will use a Template descibed
in the next section.
Choose a Template
The next page of the New Report dialog presents a selection of
report templates. Before we choose the one we want, let's walk
though what's available.
 My First Report - Starts a report template that takes
you through a tutorial using on-line help. (That tutorial
will eventually replace this one.)
 Blank Report - Creates a blank report with no
predefined content.
 Simple Listing - A tabular listing with no grouping.
 Grouped Listing - A tabular listing with grouping.
Grouping shows repeated values just once. Grouping
also allows you to create subtotals.
 Dual Column Listing - Produces a listing with two
columns side-by-side.
 Chart & Listing - A tabular listing that adds a chart to
the top of the report.
 Dual Column Chart & Listing - Combines charts and
tables so you can display two sets of related data in a
single report.
 Side by Side Chart & Listing - Creates a grouped
report where each group contains a chart and a listing
side by side.
We're now ready to choose our template:
 Select the Grouped Listing.
 Click Finish.
BIRT opens your new report in the Eclipse workspace.
Step3
 Brief UI Tour
 Cheat Sheets
 Layout Editor
 Views
 Displaying Views
Brief UI Tour
Before we start work on the report, let's take a quick tour of the
UI. We'll be looking at most of the UI in detail as we build our
report.
Cheat Sheets
Notice at the right of your Eclipse workspace (for the default
configuration) is a view called "Cheat Sheets." This view walks
you though the process of building a report based on the
template you selected.
Date: 12/21/2017 Page: 3 - 17
For now, let's go ahead and close that view by clicking on the X  About Data Sources and Data Sets
(close) button in the upper left corner of the view, since we'll be  Build a Data Source
following the steps in this tutorial.
 Editing your Data Source

Layout Editor
About Data Sources and Data Sets

The central area is the Layout Editor. This is the place where you
BIRT reports use a data source element to connect to a
create your report design. The editor has five tabs:
database or other data provider. BIRT uses a data set element
to retrieve data from the data provider. Think of the data source
 Layout - Where you edit your report design. as a connection, and the data set as a query.
 Preview - Runs your report and shows the output.
 Script - Where you add JavaScript to your report to Build a Data Source
customize its behavior.
 XML Source - You can view and modify the XML source of Let's build our data source:
a report from here.
 Master Page - Used to format page data such as page
 Open the Data Explorer View, if it is not already
headers.
visible.
 Select the Data Sources node within the tree view.
Views
 Right-click to open the context menu.
 Choose New Data Source. The New Data Source
Around the editor are a number of views: The views below can be dialog appears.
arranged to the left, right or bottom of the Layout Editor
 Choose Classic Models Inc. Sample Database.
 In the Data Source Name field, enter "Sample".
 Palette - BIRT View that shows the standard report items  Click Next.
you can add to your report using drag & drop.
 Click Finish.
 Outline - BIRT View that shows the structure of your report
as a tree view.
 Navigator - Standard Eclipse view that shows your Your new data source appears within the Data Sources node in
the Data Explorer.
projects, and the reports within your projects.
 Data Explorer - BIRT View that shows your data sources
(connections), data sets (queries) and report parameters. Editing your Data Source
You also use this view to add data set columns to your
report layout. For future reference, let's review how you would go about
 Property Editor - BIRT View that displays properties for changing the data source:
many report items. It has tabs and groupings that organize
properties into categories.  Find or open the Data Explorer View.
 Properties View - Standard Eclipse view that shows all  Open the Data Sources node.
properties for a report item as a simple list. This view is
optional, and we will not use it in this tutorial.  Double-click the data source.
 Library Explorer View - BIRT allows the reuse of report  The Data Source editor opens. You can make any
objects, such as tables, data sources and styles. Objects needed changes.
created for reuse are stored in a library file. The Library  Click OK to save your changes.
Explorer will display Libraries that exist in the resource
folder. Developed libraries can be added to the resource Step5
folder by selecting File→Publish Library to Resource
Folder or by right clicking in Library Explorer and selecting
add. The resource folder location can be configured at:  Build a Data Set
Window→Preferences→Report Design→Resource.  Data Set Editor Pages
 Database Browser
Displaying Views  Create the Query
 Test the Query
You can arrange your views any way you like. You can also hide  Edit a Data Set
them by clicking the "X" button next to the view tab. If you
accidentally hide a view, you can display it again by using the Build a Data Set
Window→Show View menu item.
Now we're ready to build and test our data set.
Many people find that a convenient layout is to have the Palette,
Navigator, Outline and Data Explorer docked at the left edge of
your workspace, and the Property Editor and Properties view  Find or open the Data Explorer view.
docked at the bottom of the workspace.  Select the Data Sets node in the tree view.
 Right-click to open the context menu. (We'll just say
Step4 "open the context menu" or "choose x from the
context menu" from now on.)
Date: 12/21/2017
 Select New Data Set. The New Data Set dialog will
appear.
 Enter "Customers" for the Data Set Name field.
 Ensure that the Data Source field shows the Sample data
source created above.
 Ensure that the Data Set Type field shows "SQL Select
Query".
 Click Next.
 Enter the following Query:
SELECT *
FROM CUSTOMERS
WHERE COUNTRY = 'USA'
 Click Finish.
Data Set Editor Pages
The data set editor now opens. Let's take a look at the pages within
this editor. The data set editor provides the following pages:
 Query - Displays your SQL SELECT statement. This is
where you create and change your SQL query. Once you
have the basic query, you can add a WHERE clause,
adjust the set of selected columns, and more. Use the
SQL editor to add computed columns that are to be
calculated by the database engine. Give such columns a
name using the SQL ALIAS clause.
 Data Source - Displays the name of the data source for
this data set so you can view or change it.
 Preview Results - Lets you test your query and see the
output. Very handy to make sure that the data is right
before you proceed with report design.
 Computed Columns - Computed columns are calculated
by BIRT and appear to the rest of the report just like any
other column. You can use JavaScript expressions, and
even call into Java for advanced business logic.
 Parameters - SQL SELECT statements can include input
parameters that pass data into the query. They are marked
using the SQL "?" symbol in the query. This page lets you
give the parameters a name, a default value, and so on.
There must be a one-to-one correspondence between
entries on this page and the "?" symbols in your query.
 Filters - Additional filters that BIRT applies to your data.
Filters restrict the data passed to the report. The WHERE
clause is also a filter: one executed by the database. This
tab lets you define additional filters using BIRT
(JavaScript) scripting.
 Output Columns - Shows the columns within the query,
and lets you define a column alias for use in the report.
Note that this view shows the columns as the report will
see them. The Query page shows the columns as
selected from the database.
Database Browser
Switch to the Query page if you're not already there. This page
provides a simple database browser.
 Expand the Sample data source to see the schemas
within this database. There is only one:
"CLASSICMODELS".
 Expand "CLASSICMODELS" to see the list of tables in the
database.
 Expand a table to see its columns.
Page: 4 - 17
 This editor support drag and drop.
Test the Query
With the data set editor open, do the following:
 Click on the Preview Results item.
The preview page appears. This page shows the columns
selected in your query listed across the top. The actual rows in
your query appear down the page.
 Verify that the list of customers appears.
 Click OK to close the data set editor.
If an error dialog appears, check the following:
 Your Eclipse is installed in a directory without spaces.
 You have typed the SQL statement as shown above.
 You have not put a semi-colon at the end of your
statement.
Edit a Data Set
Your new data set appears in the Data Explorer along with your
data source. We can use the data set editor to change the data
set, and to test it to make sure it returns the correct data.
 Find or open the Data Explorer.
 Open the Data Sets node.
 Double-click the Customers data set. The Data Set
editor opens.
Step6
 Report Layout
 Report Items
 Create the Table Detail
 Create the State Group
 Create the City Group
 Add a Table Column
 Create Column Headings
Report Layout
Our customer listing report will display customer information in
the form of a table: just like an HTML table, with the added
ability to iterate over report data. The Grouped Listing template
we chose earlier created the table for us, we just need to fill in
the details. Before we do, let's introduce the various BIRT
report items.
Report Items (Elements)
BIRT provides a variety of report items or Elements for use
when creating your report. Report items appear in the Palette
view. Report items include:
Date: 12/21/2017
 Label - Displays a simple piece of text such as "Customer
Name".
 Text - Text that can include HTML formatting and
computed values. Used to create headings, form letters,
"mail-merge" effects, etc.
 Dynamic Text - Displays a database column that can
contain HTML formatted (CLOB) data. Allows for
advanced CLOB data manipulation through expressions.
 Data - Displays a database column or a computed value.
Provides formatting.
 Image - Any kind of image supported by a web browser.
Images can be embedded in the report, referenced
through a URI, read from the resource folder or retrieved
from a BLOB field in a data set.
 Grid - Provides a tabular arrangement of report items,
much like an HTML table. This element doesnt iterate over
data sets like a List or a Table.
 List - Presents data from a data set in any kind of format.
Used when the layout for each row is more sophisticated
than a simple table row. This Element will iterate over a
bound Data Set.
 Table - Presents data from a data set in the form of a
table. Can contain grouping levels. Like an HTML table
that has a table row for each data set row. This Element,
like a list will iterate over a bound Data Set.
 Chart - Displays a business chart such as a pie chart, line
chart, etc.
This tutorial will use all the elements except for List, Chart and
Dynamic Text.
Create the Table Detail
The New Report dialog created a starter report that contains a table
item with one level of grouping. If we'd chosen a blank report, we
could create the table simply by dragging it from the palette.
The next step is to add content to the table. We'll start with the
detail band which repeats to display each row from our data set.
Here's how:
 Display the Data Explorer if it's not already visible.
 Expand the Data Sets node of the tree.
 Expand the entry for the Customers data set that we
created. This will display the columns available from the
data set.
 Select the CUSTOMERNAME column.
 Locate the detail band within the table. (It is has a gray
"Detail Row" label.)
 Drag the CUSTOMERNAME column into the detail band
cell second from the left. This operation adds a Data
Element and a Label Element to the Table Element. The
Binding Editor maps the Data Element to the Data Set row
column CUSTOMERNAME. The Binding Editor is
available by selecting the Binding tab in the Property
Editor for the Table. You can change this value by
selecting the ellipse next to the expression within the
Binding Editor. You will now see that the Table Element
contains the new Label Element and the new Data
Element.
 Drag the PHONE column into the rightmost cell of the
detail band.
Page: 5 - 17
Create the State Group
We want our customer listing to be grouped by state, then city.
Using a group causes all rows within the same state to appear
together. Let's create the group header for states:
 Locate the group header row in your table. It has a
light gray "Group Header Row" label.
 Drag the STATE column into the leftmost cell within
the Group Header row.
Creating Groups on your Own
We are using the group created for us by the New Report
dialog. If we'd started by dragging the table from the palette,
we'd create this first group as we'll explain in the next section.
You must bind (associate) the table to a data set before you
can create a group. The binding happened automatically when
we dropped the first data set column into the table. However, if
you build a table on your own, you can use the Binding tab in
the Property Editor to bind the table to a data set.
Create the City Group
Next, we'll create a city group within the state. This groups
customers first by state, then by city.
 Hover the cursor over the table and a Table tab will be
displayed.
 Click on the Table tab to display the table scaffolding.
 Select the Property Editor→Binding Tab. You will see
that the Table is bound to the Customers Data Set.
Under Data Column Binding you will notice the three
Table columns that have already been created.
 Select Add. Then Data Binding dialog will be
displayed.
 Enter City in the Name field and select ellipse next to
Expression. The BIRT Expression Builder will be
displayed.
 Select Available Data Sets under Category,
Customers under Sub-Category and then double-click
on the CITY column.
 Select OK and change the Binding name from New
Binding to CITY. The Data Set Row column CITY is
now available to be used within the Table.
 Right-click on the row header for the state group
header and a context menu will be displayed.
 From the context menu choose Insert Group→Below.
The Group Details dialog appears.
 Chose the CITY column in the Group On field and
type City in the Name field.
 Click OK.
Notice that BIRT automatically inserted a Data element for the
city group.
Add a Table Column
We need another table column to display our group heading:
Date: 12/21/2017
 Ensure the table scaffolding appears. Right-click on the
shaded column header for the first column.
 Choose Insert→Column to the Right from the context
menu. A new column appears.
 Move the CITY Data Element (the Element in the first
column of the second group header) to the second column
of the second group header by dragging it.
Create Column Headings
We're almost done with the basic setup of our table. We just need
to refine our column headings. BIRT added headings for us for
each column we added to the table.
 Double-click on the first column header text to change it.
Type "State" and press Enter.
 Drag a label from the palette into the second column
heading, type "City" and press Enter.
 Change the third column header to "Name".
 Change the last column header to "Phone".
Step7
 Test your Report
 Preview as HTML
 Preview as PDF
Test your Report
We're now ready to test the report layout. We verified the data set
earlier, so now we want to verify that the report is presenting the
data as we expect.
We preview the report by clicking on the Preview tab in the lower
left corner of the report editor. This report has no parameters, but if
it did, they could be modified by selecting the Show Report
Parameters button.
The window that appears is an embedded web browser, which
displays the report in HTML format. The report appears as a single
page. This works best for smaller data sets. Since the sample
database has quite a bit of data, we used a WHERE clause to limit
the results. We could also use a report parameter or a data set filter
to limit the amount of data displayed at any one time.
There are a number of ways we can improve the report's
appearance:
 Add a title to the top of the report.
 Add some color to enhance the column headings.
 Shrink the size of the city and state columns.
 Add some color to make the state and city group headers
stand out.
 Format the phone numbers.
 Sort customers by name.
Before we apply these aesthetic enhancements, let's look at other
ways to preview the report.
Preview as HTML
Page: 6 - 17
The Preview tab is handy for a quick review of your report.
BIRT runs the report each time you switch to Preview.
However, you can have either the Layout or the Preview tab
open, but not both.
Instead, we can preview the report in a separate window. Find
the Preview button in the toolbar. Use the little arrow next to it
to open the pull-down. You can then Preview as HTML in a
separate window. This allows you to switch back and forth
between your layout editor and your preview without rerunning
the report.
Preview in Web Viewer
This option is similar to the one above. It allows the report to
be previewed as HTML in a separate browser window using
the BIRT Web Viewer. The viewer provides powerful navigation
capabilities such as TOC, Previous Page, Next Page, Goto
Page as well as search and export capabilities.
To preview the report in the Web Viewer use the toolbar
Preview button and select the Web Viewer option or
alternatively invoke File->Preview in Web Viewer.
Preview as PDF
You can also choose Preview as PDF. This converts the layout
to a multi-page PDF format.
Step8
 Resizing Table Columns
 Setting the Background Color
 Setting the Font
 Formatting Data
 Setting a Border
 More on Properties
Resizing Table Columns
Let's adjust the size of the table columns. Tables & columns
can be sized using absolute sizes (inches, centimeters), or
relative sizes (percentage of the width of the page.) Here, we'll
adjust the column widths by directly changing them in the
report layout. To do this:
 Click the Layout tab to switch back to the report
layout.
 Display, then click on the table tab to display the
"scaffolding."
 Find the black line that separates the "City" and
"State" column headings.
 With the cursor over this line, hold down the left
mouse button and resize the column to be about big
enough to hold the two-letter state code and label.
 Repeat the above to resize the city column.
Setting the Background Color
Let's dress up the state heading by setting the row's
background color. To do this:
Date: 12/21/2017
 Select the state group header row (first group header) by
clicking on the shaded box to the left of the row.
(Remember to display, then click on the table tab to
display the scaffolding.)
 Locate or open the Property Editor.
 A list of property types appears at the left of the view. Click
on the General group.
 Find the Background color field. Click on the empty gray
button to display the color picker.
 Pick the blue color third from the right in the top row. This
is a standard color, but is a bit too dark for our needs.
 Click on the "Define Custom Colors" button.
 Take the right-most slider (saturation) and move it up to
produce a very light blue.
 Click OK.
Setting the Font
Now, let's give the state a bold font. We'll also dress up the city
group heading by giving it a dark blue, bold, larger font. To do this:
 Select the state Data Element. (it’s located below the state
label.)
 Switch to the General property group in the Property
Editor.
 Find the Font size field. Change the size to "Large".
 Click the [B] (bold) button to make the font bold.
 Select the city Data Element.
 Again, switch to the General property group.
 Set the font size to Large.
 Click on the Font Color button.
 The color chooser again opens. Again choose the blue
that is third from the right in the top row.
 Click OK.
Formatting Data
We want to format the phone numbers so that they have correct
North American format: (123) 555-1212. We do this by applying a
string format to the phone number field. Formats are also available
for dates and numbers.
 Select the phone number Data Element.
 Switch to the Format String page in the Property Editor.
 Choose Custom for Format String as.
 Choose Phone Number from the list.
 In the Format Code field, add a space after the closing
parenthesis to produce the following:
(@@@) @@@-@@@@
Setting a Border
Next, let's put a "drop shadow" border around our table.
 Click on the table tab.
 Select the Borders page in the Property Editor.
 Set the Style field to a solid line. (This is the default.)
Page: 7 - 17
 Set the Color field to a black. (Use the color name
pull-down, or choose the bottom left color in the color
picker.) (This is the default.)
 Set the Width property to the thinnest line.
 Click the top, bottom, left and right border buttons. A
thin border appears around the table.
 Switch to the Properties view (Window->Show View-
>Properties) to specify that a wider border should be
used for the bottom and right sides.
 Click on the table tab to initialize the Properties view
with the table’s properties.
 Expand the Box node in the Properties View and set
the Border bottom width and Border left width fields to
medium.
More on Properties
BIRT provides a wide variety of properties for formatting report
items. The properties are based on the W3C CSS (Cascading
Style Sheet) standard. If you've ever used CSS to format
HTML, you are well on your way to understanding formatting in
BIRT.
Step9
 About Data Properties
 Setting the Detail Sort
About Data Properties
In addition to the visual properties we just saw, BIRT provides
a set of data-related properties for each report item. We'll use
these to control the sort order of the customers within our
report.
Data sets in BIRT are reusable: you can use the same data set
multiple times. For example, suppose you want to show year-
to-date (YTD) sales three ways: by month, by sales rep, and as
a chart. With BIRT, you define the data set once, but present it
three times. Each use of the data set can provide data
properties that customize the data set to that particular use.
Data properties include:
 Data set binding: lets you specify the data set to use
with any given report item.
 Parameter binding: you can pass data into the data
set. For example, you can create a "master/detail"
subreport by using data set parameters to pass data
from the current row in the master report to the detail
for the subreport. Or as another example, you can
obtain a list of customers from one database, then
have the subreport display orders from a different
database.
 Filters: provide filter conditions unique to a given
presentation. For example, a list of transactions might
list all transactions, but then use filters to display
sales in one chart, returns in another.
 Groups: provide ability to create subtotals as we have
already seen.
 Sorting: controls the order of the detail rows within a
table. This is the property we'll use.
Date: 12/21/2017
Setting the Detail Sort
We're ready to specify the sort order for customers within our
report.
 Select the table. (by clicking on the table tab in the Layout
Editor.)
 Choose the Sorting tab within the Property Editor. (Note:
Sorting is a tab on the top of the Property Editor and not a
page on the left as we've used thus far.)
 Click the Add button to add a new sort condition.
 Use the pull-down under Sort Key to choose
"CUSTOMERNAME".
 Leave the Sort Direction at Ascending.
Step10
 About Styles
 Creating a Style
 Applying a Style
 Editing a Style
About Styles
We mentioned that BIRT uses CSS to define the styles for report
items. BIRT also allows you to define the properties in a style sheet,
then to apply the style to a report item, just as in HTML. The result
is that you create the style once and use it multiple times. If you
need to change the look of a report, you can change the style in
one place rather then in many different report items. If you've
defined your own styles when creating HTML pages, you're well on
your way to understanding the BIRT style system. Styles can also
be placed into BIRT libraries (Using Themes) and shared across
reports.
Creating a Style
Let's use the style feature to format the table header. Let's make
the table header a blue bar with contrasting text. Instead of
formatting each label one-by-one, we'll define a style, then apply it.
To do this:
 Select the first label (State label) in the Table Header
band.
 Right-click and select Style→New Style from the context
menu.
 The Style Properties dialog appears.
 Enter "Header" in the Custom Style (Name) field on the
General page and make sure that the Custom Style radio
button is selected.
 Switch to the Background page from the left most column
of the New Style dialog.
 Click the Background color button and choose the same
blue: third from the right in the top row.
 Switch to the Font page.
 Set the Color to white.
 Set the Weight to Bold.
 Click OK.
Notice that the new style has been applied to the label.
Page: 8 - 17
Applying a Style
Next, let's apply the style to the other three header labels. (We
could have done this in a single step by selecting all four when
we defined the style. We're doing it in two steps just to show
how it's done.)
 Select the other three labels: click on the City label,
then use Ctrl+click to add the other two to the
selection.
 Choose Style→Apply Style→Header from the context
menu.
The other three cells are now also formatted.
Editing a Style
Suppose we wanted to change the style we just created.
Here's how we find and change it.
 Find or open the Outline view.
 Scroll down to the bottom and find the Styles node.
 Open the Styles node to reveal our styles.
 Double-click the style you want to edit.
 You can also edit a style by selecting Style→Edit
Style→Style Name from the context menu when a
report item is selected.
Step11
 About Style Cascade
 Setting Report-Wide Properties
 Other Default Styles
 Check the Report
About Style Cascade
We've mentioned that BIRT uses CSS to define the styles for
report items, and we saw how to define and apply our own
style. BIRT also follows the "cascade" part of Cascading Style
Sheets: you can set a property once for the report, or a
container, and have that value cascade down through the
contents of the container.
In BIRT, Grid, List and Table items are containers: they can
hold other report items. The report itself is the ultimate
container for all report items.
Setting Report-Wide Properties
Our report currently uses the default font: a serif style.
(Actually, by default BIRT uses the font set in your browser.
Many browsers use a serif style by default, but if you've
changed your default browser font, that is how the report will
appear.)
Let's use a sans-serif style instead. We do this by using a pre-
defined BIRT style called report, which specifies the default
style for report items. If you are familiar with CSS, this is like
defining a style that selects the HTML body tag.
Date: 12/21/2017
 Open or locate the Outline view.
 Scroll down to the bottom to find the Styles node.
 Open the Styles node.
 Right-click and select New Style.
 From the General page, check the Predefined Style radio
button and select “report” from the associated drop down
list.
 Click OK
 Go to the Styles node in the Outline view and find the style
named "report". Double-click it to open the Style editor.
 In the Font page, choose "sans serif" as the font type.
 Click OK.
All items in your report will change to sans-serif font.
The names "serif" and "sans-serif" are defined by CSS: they are
generic font styles that don't depend on the specific fonts installed
on a machine. CSS generic font names avoid dependencies on
specific fonts installed on the browser machine; something that is
important if your reports will be appear as part of a public web site.
You can also use font lists as in CSS. For example: "Helvetica,
Arial, sans-serif".
Other Default Styles
BIRT defines default styles for most report items and for list and
table bands. See the ROM Styles Specification for the complete list.
The Styles node displays the styles that apply to each of the report
items. However, there are additional styles that apply to grouping
levels and other contexts. If you wish to use one of these, simply
create a style with the required name.
Check the Report
Let's click the preview tab to see how our report looks after the
formatting. Not bad, but we still need a better report heading.
Step12
 Create a Grid
 Row Properties
 Column Properties
 Insert an Image
 Insert the Run Date
Create a Grid
Let's add a suitable heading to our report. It will use the classic
"left/center/right" layout: a logo on the left, the report title in the
center, and the run date on the right. Before you do this you may
want to remove the current basic heading, which simply says
“Report Header”. To do this:
 Select the Grid item containing the “Report Header”which
is located above your table.
 Delete it by right-clicking on it and selecting the delete
option from the context menu.
The easiest way to create such a layout is to use a grid. A grid is
like an HTML table, it tells BIRT the desired layout, and BIRT does
Page: 9 - 17
the work to make it happen. In this case, we want a one-row
grid with three columns each 1/3 the width of the page.
 Drag a Grid item from the palette into your report
above your table. The Insert Grid dialog appears.
 Choose 3 columns and 2 rows.
 Click OK.
Row Properties
We want the contents of the header to be top-aligned. And we'll
use the second row as a spacer between the header proper
and the report body:
 Select the entire first row of the Grid that you just
added.
 In the General page of the Property Editor, set the
vertical alignment to Top.
 Select the second row.
 In the General page of the Property Editor, set the
height to 0.25 in.
Column Properties
We want each of the three columns to be 1/3 the width of the
page, and we want them to be left, center and right aligned:
 Select the first column header.
 Switch to the General tab in the Property Editor.
Notice that the width is unset. As in HTML, if the
column width is not set, BIRT will size the column to
its content.
 Set the column widths to 33%. Do this by typing "33"
in the width field, then selecting "%" from the adjacent
pull-down.
 Select the middle column.
 Repeat the step above to set the width to 33%.
 In the General page of the Property Editor, set the text
alignment to Center.
 Select the rightmost column.
 Repeat the step above to set the width to 33%.
 In the General page of the Property Editor, set the text
alignment to Right.
Insert an Image
Let's click the preview tab to see how our report looks after the
formatting. Not bad, but we still need the report heading. To do
this:
 Drag an Image item from the palette into the left-most
cell of your grid.
 The Image Builder dialog appears.
 Ensure that the URL radio button is selected.
 Enter the following URL:
"http://www.eclipse.org/birt/phoenix/tutorial/basic/multi
chip-4.jpg". (don’t forget to add the quotes.)
 Click the Preview button to ensure that the URL is
correct.
 Click Insert to add the image to your report.
Date: 12/21/2017 Page: 10 - 17
You can also embed an image from your local disk. Embedding the  From the list near the top of the dialog, insert a
image copies the image into the report design. Using a URL is more <FONT> element.
efficient.  In the attributes provided, set the size to 6 and the
color to blue. Erase the face attribute. The text should
Insert a Run Date now look like this:

Next, let's display the current date in the right-most cell in the <CENTER>
heading. To do this: <FONT size="6" color=blue>

</FONT>
 Drag a Data item from the Palette into the right-most cell
</CENTER>
of your grid.
 Continue using the editor to create the text below:
 The New Data Item dialog will be displayed. Change the
name to current_date.
 Set the Data Type column to Date Time. Select the ellipse <CENTER>
next to the Expression. The expression builder will appear. <FONT size="6" color=blue>
Customer Listing
 Type "new Date( )" (without the quotes) to display the
</FONT>
current date.
<BR>
 Click OK. <I>For internal use only</I>
 Set the date format. Select the Format DateTime page </CENTER>
within the Property Editor.  Click OK and save your changes.
 Choose the date format that looks like this: May 12, 2005.
(The actual date will be today's date.) This is the BIRT
Dynamic Text
"Medium Date" date format.

While we won't use it in this tutorial, there is one other feature

BIRT uses Java formatting for dates, numbers and strings. In
of Text Elements to note. Select the Dynamic Text category
addition, BIRT adds a number of specialized, locale-aware date
and you'll see a tag. This allows you to insert expressions
formats described in the ROM Styles Specification.
directly into your HTML. For example, to display an address
line in US format, we could type:
Step13
<value-of>row["city"]</value-of>,
 About Text Items <value-of>row["state"]</value-of>
 Create a Text Item <value-of format="@@@@@-@@@@">row["zip"]<value-of>
 Dynamic Text
 Final Test The row values correspond to the name column within the
Binding Editor for the given report container element. So for
example if we added a Text Element to our Table, we could use
About Text Items row["CUSTOMERNAME"] within the value-of tag.

The final step in our report is to create the actual header text. We Final Test
want it to look something like this:
We're now ready to give the report a final test. Click the
Customer Listing Preview tab to see the report with formatting applied.
For internal use only
Step14
We could create this with two labels. But, we'll take this opportunity
to try out the Text element which allows us to use HTML formatting
within the text.  Wrap Up
 Next Steps
Create a Text Item  More Information

Let's create our text item. To do this: Wrap Up

 Drag a Text Element from the palette and drop it into the
center cell within our grid.
 The Edit Text Item dialog appears.
 In the top combo box, choose HTML/Dynamic Text. The
dialog displays a variety of HTML tags we can insert.
 Using the button next to Formatting, pull down the list and
choose Layout.
 Click the <CENTER> tag to add it.
In this tutorial we created a simple listing that touched on many
of the features of the BIRT Report Designer and Report Object
Model (ROM). Now that you are familiar with BIRT, you're
ready to learn more about it.
Next Steps
Additional BIRT topics include:
Date: 12/21/2017 Page: 11 - 17
 Charting with interactivity  Payments: Payments made by customers against
 Scripting and Expressions using JavaScript their account
 Custom data access extensions  Products: The list of scale model cars
 Advanced formatting  Product Lines: The list of product line classifcation
 Advanced queries
 Multi-part reports (multiple lists, side-by-side lists, master- This ER-diagram shows the table structure and relationships.
detail reports, etc.) (PDF version)
 Conditional formatting
 Extended data items Install
 Dynamic and cascaded parameters
 Joined Data Sets The sample database is available in two forms:

More Information  Apache Derby database, which is included in the

BIRT download
A number of resources are available to help you learn more:  Scripts to load a MySQL database

 The extensive online help included within BIRT. Select The scripts to load a MySQL database are contained in the
Help→Help Contents from the Eclipse menu and then sample database zip file. This zip also has documentation and
click on the BIRT Developer Guide. logos for the sample database.
 Reference material, including ROM (Report Object Model)
specifications. MySQL Version
 Additional example reports.
 BIRT newsgroup To install the MySQL version of the sample database, you must
 How to get help on using BIRT. have MySQL installed. See mysql.com for instructions.

Install the MySQL JDBC driver into BIRT:

 Download and unzip MySQL Connector/J 3.1 JDBC
driver located at: http://dev.mysql.com/downloads/
BIRT Sample Database
 Install the JDBC driver using the instructions on the
install page. Enter the following for the URL template:
 Introduction
 Schema jdbc:mysql://[host][,failoverhost...][:port]/[database]…
 Install
 Usage You are now ready to create the Classic Models database:

Introduction  Download the zip file containing the MySQL database

The BIRT sample database provides a simple set of tables and
data that form the basis for BIRT sample reports. The schema is for
Classic Models, a retailer of scale models of classic cars. The
database contains typical business data such as customers, orders,
order line items, products and so on. It was designed to illustrate
many of the features of the BIRT report designer.
scripts.
 Expand the zip file into a convenient location.
 Expanding the zip file created the
ClassicModels/mysql directory with some MySQL
scripts. From the command line, move to the this
directory:

% cd /ClassicModels/mysql
The sample database is open source; you are free to use it for your
own use to experiment with other tools; to create samples for other
tools, etc. The sample database is provided under the terms  Start the mysql utility, giving the name (and password,
Eclipse.org Software User Agreement. if needed) of a user permission to create databases.
For example, to use the default root user:
Schema
% mysql --user=root
The database consists of eight tables:
 Create the ClassicModels database and load the
 Offices: sales offices schema. (Loading the schema the schema the first
time will give error messages as it attemps to empty
 Employees: All employees, including sales reps who work any existing tables, just ignore these.)
with customers.
 Customers
mysql> create database ClassicModels; mysql> use
 Orders: Orders placed by customers ClassicModels; mysql> source
 Order Details: Line items within an order. create_classicmodels.sql;
Date: 12/21/2017
 Load the table contents:
mysql> source load_classicmodels.sql;
 Exit from mysql:
mysql> quit;
Localized Version of the Sample Database
Following is the Derby Database localized into French, German,
Spanish, Japanese, Korean, and Simplified Chinese.
 Localized Derby Sample Database
Usage
You can now use the sample database within BIRT to create
reports. The key information you need to get started is how to
create a data source for the database. The details vary depending
on the database system you selected.
Apache Derby
The Apache Derby version of the database is included in the BIRT
download as a built-in data source. To access it, simply select the
"Classic Models Inc. Sample Database" entry in the new data
source dialog.
MySQL
Data source properties for the MySQL sample database:
Driver Class: com.mysql.jdbc.Driver
URL: jdbc:mysql://localhost/classicmodels
User Name: root
Password:
BIRT Examples
 Introduction
 BIRT Demo
 Examples
Introduction
Weclome to the examples section of the BIRT site.
Here you will find examples that illustrate some of the features of
BIRT. This section will be changed frequently to add new examples.
The example types are classified below. Feel free to make
comments within the news group. Let us know what examples you
would like to see.
BIRT Demo
BIRT Demo – This demonstration is a Flash presentation of BIRT
that showcases some of its powerful features including summary
Page: 12 - 17
and line graphs, JavaScript for dynamic images, style usage,
highlighting, grouping and detail drill down..
Examples
 Solution Reports – This section contains several
example solution reports, such as Business Forms.
 Reporting Feature Examples – This section
demonstrates features and functions of the BIRT
Report Designer.
 Scripting – This section contains examples of
scripting within the BIRT Designer
 Integrating BIRT – This section demonstrates several
examples of deploying and using the APIs of BIRT
 Extending BIRT – This section covers extending the
feature set of BIRT, such as Open Data Access
(ODA), Report Items, etc
BIRT Solution Reports
 Introduction
 Listing
 Business Forms
Introduction
The example reports here show just a few of the things you
can do with BIRT. Unless otherwise noted, the reports are
meant to be run against the "Classic Models Inc." sample
database that is included in the BIRT download.
Preview a report by clicking on the title link. To try a report for
yourself, click on the rptdesign link to display the ROM file,
save it to disk and then use File-->Import to bring the file into
your Eclipse workspace. If the report uses the Classic Models
database, you should be able to run the report immediately. If
the report uses another database, follow the instructions
provided in the "Other Notes" section of its description.
Listing
 Product Catalog (rptdesign)
Prints the Classic Models product catalog, grouped by
product category. Provides product name, cost and
description. Demonstrates one level grouping and
using a grid within a table row to structure spacing.
Also shows image inclusion and use of the <value-of>
tag in text item to include the content of a database
column. Finally, the report makes use of styles to
simplify maintenance and achieve a consistent look.
 Top Selling Products (rptdesign)
Displays a pie chart showing revenue by product line.
Lists the top selling products, sorted by revenue.
Demonstrates use of a chart and sorting a result set.
Also shows image inclusion and use of grid and
tables to organize report content. Finally, the report
makes use of styles to simplify maintenance and
achieve a consistent look.
 Top N / Top M% Customers (rptdesign)
Making use of the top n and top precent filter
capabilities added in BIRT 2.0, this report shows a bar
chart with the top N customers by revenue, followed
by a listing of the top M% customers by revenue
Date: 12/21/2017
sorted by customer name. This requires multiple passes
over the data, but it is all done "under the covers" by the
BIRT report engine. N and M are passed into the report as
parameters to allow report users to select the number and
percentage at run time.
 Annual Sales By Product Lines (rptdesign)
This example illustrates building a static crosstab report
using the BIRT Total function. The report presents annual
sales revenue by quarter for each of the product lines that
Classic Models Inc currently sales. In addition totals are
aggregated across horizontal and vertical dimensions. The
BIRT Total function can accept a second parameter that
filters the aggregate data. In this example this feature is
used to only display values that pertain to a product
offering, such as Trains. The first parameter in the Total
function is the value to aggregate, and in this example it is
set to quantity sold multiplied by price each. The second
parameter is the filter. So if the filter where specified as
dataSetRow["Products::PRODUCTLINE"]=="Motorcycles",
only the Motorcycles product line would be aggregated.
Page: 13 - 17
 Drill to Details – Example used to demonstrate linking
a Master report to a Detail report.
 Report Elements – This example demonstrates using
Label, Text, Dynamic Text, Data, and Image Report
elements.
 Sub Reports – This example demonstrates building
sub reports using nested tables.
 Mapping and Sorting – This example demonstrates
using the Mapping and Sorting features of BIRT.
 Parallel Report – This example demonstrates how to
build a report with parallel sections.
 Highlighting and Conditional Formatting – This
example demonstrates how to add highlighting and
conditional formatting to a BIRT report.
 Grouping – This example demonstrates building a
grouped report in BIRT.

Business Forms
BIRT Integration

 Sales Invoice (rptdesign)

 Integration Points
Prints an invoice for the selected order, including customer
and invoice details and products ordered. Demonstrates  Runtime Integration
use of a parameter to select the order to invoice and  Design-Time Integration
expressions for several calculated fields, including  Extending BIRT
discount and order total. Uses expression to build  Report Viewer
customer address string and illustrates suppression of  Report Engine API
nulls in database fields with javascript function replace.
Also shows image inclusion and sophisticated use of grids
 Design Engine API
and tables to organize report content. Finally, the report
makes use of styles to simplify maintenance and achieve Integration Points
a consistent look.
BIRT reporting provides a variety of integration points to
accomplish various tasks:

BIRT Example Reports  Runtime integration

 Design-time integration
 Introduction  Extensions to BIRT

Introduction BIRT charting APIs are described elsewhere. (Not yet

available.)
This section of Examples focuses on the feature set within BIRT.
Simple reports are used to illustrate a function within BIRT. Most Runtime Integration
examples will have a before and after report that can be
downloaded. In addition, the example is illustrated in a Flash Your application can integrate the BIRT web and engine
presentation. runtimes:

BIRT 2.1 Examples  BIRT Report Web App

 XML Data Source – This example demonstrates creating a
report using the XML Datasource.
 Libraries – This example demonstrates creating and using
BIRT libraries.
 Combination Chart – This example demonstrates building
a Combinatio Chart with Drill to details.
 Cascaded Parameter Report – This example
demonstrates building a BIRT Report that uses a
cascaded parameter.
 Query Modification – An example of modifying the query
using Property Binding or Script.
A series of URLs that your application can use to
display a parameter page, run and display a report,
etc.
 Report Engine API
A Java interface used to embed the BIRT report
engine within your application. The engine behavior
can be customized for use in a web app, RCP app,
command line app, etc.
Design-Time Integration
Date: 12/21/2017
Your application can explore or create BIRT XML report designs:
 Design Engine API
Provides access to a BIRT report design. You can explore
the design, modify it and so on. Use this API to create your
own custom report designer, or to perform batch tasks on
designs.
 Generate a Report Design Directly
If you can write XML files, or with templates, you can
generate report designs based on an application-specific
report designer. This technique is ideal for non-Java
scripting environments such as PHP.
Extending BIRT
Your application can extend BIRT for your specific needs:
 Scripting (Reference) (Scripting Primer)
BIRT provides extensive scripting support. You can create
anything from computed columns to sophisticated
business logic to extensive integration with existing Java
code.
 Open Data Access (ODA) Extension API
BIRT provides a JDBC data source. Use the ODA API to
create custom data sources drivers. Each driver has run-
time behavior along with optional design-time UI.
 Scripted Data Source (Scripting Primer)
The scripted data source and data set elements allow you
to access custom data sources directly from your report
without the need to create an ODA driver. This solution is
ideal for one-off data sources, prototypes, and the like.
 Report Item Extension API
The BIRT model is extensible; you can add new report
items. Use this API to include design-time, run-time or
presentation-time behavior.
Report Viewer
The BIRT Viewer can be used in a variety of ways:
 As a stand-alone, pre-built web application for running and
viewing reports.
 As a starter web application that you can customize to
your needs.
 As an example for learning how to build your own
reporting web application, or to learn how to use the BIRT
engine.
 As a way to run a report using a URL. This option provides
a simple way to integrate BIRT reporting into applications
build using non-Java technology such as Perl, PHP or
even static web pages.
The BIRT viewer is a web application included with BIRT to perform
the report preview operation within Eclipse. It is also a sample of
how to integrate birt with a web application.
 Integrating the BIRT Viewer explains how to deploy the
BIRT viewer onto your own application server. The
explanation uses Apache Jakarta Tomcat as the sample
deployment target.
 Using the BIRT Viewer discusses the viewer operation
URLs and their parameters.
Page: 14 - 17
 Using the Viewer from PHP discusses how to run
BIRT reports from a non-Java scripting environment
such as PHP. Also briefly summarizes how to use
PHP to generate custom report designs.
 Viewer Pages discusses the JSP that make up the
viewer. (Not yet available.)
 The viewer code is available in the BIRT CVS
repository in the org.eclipse.birt.report.viewer project.
See the BIRT build instructions for information on how
to access CVS and build the viewer.
Report Engine 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.
 Using the Engine API explains how to use the Engine
API to create a simple command-line program that
runs reports.
Design Engine 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 is built using this API. (Internally, the Design
Engine is also called the "report model" or just "model.")
 Using the Design Engine API: a brief primer for using
the DE API.
 The Design Engine code is available in the BIRT CVS
repository in the org.eclipse.birt.report.model project.
See the BIRT build instructions for information on how
to access CVS and build the code.
Pre-Requisites and Installation Instructions for BIRT
 Introduction
 Report Designer Full Eclipse Install
 Designer Install
 GEF
 EMF
 DTP
 BIRT
 Optional Eclipse Link File
 iText
 prototype.js
 JDBC Drivers
 Updating a BIRT Installation
 Deploying to J2EE Server
 Installing BIRT Language Packs on Windows
 Common Problems
Introduction
Below are complete instructions for installing BIRT. If you are
already familiar with Eclipse plugins, you might want to follow
the abbreviated requirements and instructions on the download
Date: 12/21/2017 Page: 15 - 17
page. Otherwise, follow along below for detailed steps for installing  From the desktop, right click, choose New→Shortcut.
BIRT.  For location, enter "C:\Program
Files\eclipse\eclipse.exe" (without quotes.)
The instructions here are for the Release 2.1/2.0.2 (and later)  Click Next.
builds.  Enter “Eclipse” for the shortcut name.

Java GEF

You'll need a Java runntime environment (JRE) The version you GEF, the Graphic Editor Framework, is an Eclipse plugin used
choose will depend on the version of Eclipse you are running. See by the BIRT UI. Download the GEF 3.1/3.2/3.3 Release, GEF
below. Runtime.

Eclipse GEF comes as a zip file. Unzip GEF into directory that contains
Eclipse. If you installed Eclipse into the standard location on
BIRT is currently tested with the following configurations: Windows, then unzip GEF into "C:\Program Files".

 BIRT 2.0.2 EMF

 Eclipse 3.1
 GEF 3.1. The BIRT charting feature uses EMF, the Eclipse Modeling
 EMF 2.1. Framework. Download the EMF & SDO RT version 2.1/2.2/2.3.
Look in the Latest Releases sections of the download page.
 JRE 1.4.2/JRE 1.5.

EMF also comes as a zip file. Unzip EMF into directory that
And
contains Eclipse. This is the same directory you used for GEF.
 BIRT 2.1/2.1.1
 Eclipse 3.2.
DTP
 GEF 3.2.
 EMF 2.2.
BIRT sources data for reports using the Data Tools Platform
 JRE 1.4.2/JRE 1.5. Project. Download DTP version 1.5. Note that 1.5 is only a
requirement for versions of BIRT newer than BIRT 2.2 M6. 2.2
And M6 is the last version of BIRT to include the required DTP
 BIRT 2.2M4 and higher plugins in the designer download.
 Eclipse 3.3.
 GEF 3.3. The BIRT allinone download will continue to include the
required DTP plugins. Additionally a separate download is now
 EMF 2.3.
available on the BIRT site that is a subset of the DTP plugins.
 JRE 1.5. This package referred to as the BIRT/DTP Integration package
 DTP 1.5. contains only the required DTP Plugins needed for BIRT to
function.
Report Designer Full Eclipse Install
BIRT
BIRT now supplies a download that incudes Eclipse, GEF, EMF and
BIRT. Use this download if you do not already have Eclipse Download Release 2.1.1 (or later). Download only the BIRT
installed. You will still need iText.jar and prototype.js (this file is no designer framework for now: "birt-report-framework-2_1_1.zip".
longer needed with 2.1 or later builds), which are described below.
BIRT is also a zip file. Unzip BIRT into the directory that
Designer Install contains Eclipse.

Use these instructions if you have Eclipse installed or do not desire
to use the Report Designer Full Eclipse Install.
Download and install the Eclipse Platform 3.1/3.2/3.3 Release
(Note: Eclipse, EMF, GEF, DTP and BIRT are all available from the
Eclipse download page.)
Eclipse comes as a zip file or tar file. On Windows, unzip the install
file into your "C:\Program Files" directory. This will create a
subdirectory called eclipse.
To make it easier to start Eclipse on Windows, create a shortcut to
Eclipse on your desktop:
Optional Eclipse Link File
If you currently have an Eclipse install with GEF and EMF, you
can download the BIRT framework and unzip the contents to
any directory.
 After doing this, create a links directory in your
installed Eclipse location (ie
C:\eclipse3.2\eclipse\links).
 Within this directory create a file with a unique name
like birt.2.1.link.
 Open the file you just created and enter
path=drive:/pathtobirt (ie path=c:/birt2.1)
Date: 12/21/2017
 You will still need iText and prototype.js files. See next
section.
iText
 iText 1.3.
The iText APIs are discussed at iText Homepage
If you are installing BIRT 2.2 M2 or later, download version 1.4.6 of
iText instead of 1.3.
BIRT 2.0.2
The itext-1.3.jar file needs to be copied to the
plugins/org.eclipse.birt.report.engine.emitter.pdf_version/lib
directory.
BIRT 2.1.0 (or later)
The itext-1.3.jar file needs to be copied to the
plugins/com.lowagie.itext_*/lib directory.
Birt 2.1.1 or Later Note:
To Support Asian fonts in PDF, download the following jar
and place it in the plugins/com.lowagie.itext_*/lib directory.
 iTextAsian.jar.
Birt 2.2 M2 or Later Note:
The iText version has been updated, download the
following jar and place it in the
plugins/com.lowagie.itext_*/lib directory.
 iText 1.4.6.
prototype.js
This step is only required if installing BIRT 2.0.2 or earlier.
Download prototype.js v1.4.0 from dev.conio.net. Copy it into the
plugins/org.eclipse.birt.report.viewer_version/birt/ajax/lib directory.
JDBC Drivers
You will likely want to use your own JDBC driver with BIRT. Use the
data source editor’s JDBC driver management wizard. To start the
wizard, open a BIRT report design, go to the Data Explorer view,
right click on “Data Sources” and select “New Data Source”.
Choose “JDBC Data Source” and click “Next”. In the next dialog,
choose “Manage Drivers…” to bring up the “Manage JDBC Drivers”
dialog.
In the “JAR Files” tab, click on “Add…” to add the JAR file required
by your JDBC driver. Then go to the “Driver” tab to confirm that the
list of drivers includes the new drivers added. You may also want to
assign a display name and URL template for the new drivers in this
tab.
Updating a BIRT Installation
If you have a version of BIRT installed, and want to install a newer
version, do the following:
 Close Eclipse.
Page: 16 - 17
 Locate your Eclipse plugins directory. If you installed
on Windows in the default location, this is "C:\program
files\eclipse\plugins".
 Delete all directories that start with "org.eclipse.birt".
 Download and install BIRT as described in the BIRT
section above.
 Restart Eclipse with the -clean option: eclipse -clean
Deploying to J2EE Server
Please see Setting up the BIRT Viewer
Birt 2.0.2 Runtime Note:
 If you are installing the BIRT 2.0.2 Runtime (J2EE
Application Server Deployment), The iText and
prototype files will need to be copied to the birt-
runtime/Web Viewer Example directory structure.
 Copy itext-1.3.jar to /Web Viewer
Example/plugins/org.eclipse.birt.report.engine.emitter.
pdf/lib.
 Copy prototype.js v1.4.0 to /Web Viewer
Example/ajax/lib.
Birt 2.1 Runtime Note:
 If you are installing the BIRT 2.1 Runtime (J2EE
Application Server Deployment), The iText file will
need to be copied to the birt-
runtime/WebViewerExample directory structure.
 Copy itext-1.3.jar to /WebViewerExample/WEB-
INF/platform/plugins/com.lowagie.itext/lib.
Birt 2.1.1 Runtime Note:
 If you are installing the BIRT 2.1.1. or 2.1.2 Runtime
(J2EE Application Server Deployment),
 Copy itext-1.3.jar to /WebViewerExample/WEB-
INF/platform/plugins/com.lowagie.itext/lib.
 Copy iTextAsian.jar to /WebViewerExample/WEB-
INF/platform/plugins/com.lowagie.itext/lib.
Birt 2.2M2 Runtime Note:
 If you are installing the BIRT 2.2M2 or later Runtime
(J2EE Application Server Deployment),
 Copy itext-1.4.6.jar to /WebViewerExample/WEB-
INF/platform/plugins/com.lowagie.itext/lib.
 Copy iTextAsian.jar to /WebViewerExample/WEB-
INF/platform/plugins/com.lowagie.itext/lib.
Installing BIRT Language Packs on Windows
1. Download the Language Pack for the desired product
and extract into your eclipse install.
2. Open the Regional and Language Options in the
Control Panel and switch to the advanced tab.
Date: 12/21/2017 Page: 17 - 17
3. Select the group 1 language you desire from the drop-
down combo box.
4. Save changes and restart the system.
5. Launch Eclipse and select Window->Preferences-
>Report Design->Preview. Select the desired language
from the drop-down combo box.
6. Restart Eclipse.

Common Problems

Some problems are due to cached information within Eclipse.

Eclipse caches information about plugins for faster startup. Adding
BIRT as we did above may result in stale cached information.
Symptoms of this problem include:

 The BIRT perspective does not appear in Eclipse.

 You receive "An error occurred" dialogs when opening
reports or using the BIRT UI.

Cleaning Cached Plugin Information

The solution is to clean up the cached information. The

recommended practice is to start Eclipse with the -clean option:

eclipse -clean

Cleaning the Cache on Windows

If you are on Windows, and are not familiar with how to invoke
Eclipse from the command line, do the following:

 Choose Start→All Programs→Accessories→Command

Prompt
 Move to the directory where you installed eclipse. If you
installed Eclipse in the standard location, enter:
 cd "\Program Files\eclipse"
 Run Eclipse with the -clean option:
 eclipse -clean
 Eclipse will restart. Again check for the BIRT perspective.