Report module based on Eclipse BIRT - Report and analysis modules

Overview

The newly released BIRT(Business Intelligence and Reporting Tools) project (current version is 1.0.1) 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.

Help

Please help us to keep the cookbook updated with your experiences and solutions with BIRT, or have a look to get help:
BIRT Cookbook

Setup and basic use

After some testing of the BIRT designer I recommend installing the stand alone report designer (Eclipse Rich Client Platform - RCP) and not the Eclipse plugin.

BIRT Designer:
Dwonload BIRT 2.0 report designer (RCP)
BIRT designer installation instructions
Remember to follow the instructions for setting up iText, Axis 1.2.1, prototype.js and the jdbc drivers.

BIRT Viewer:
Download BIRT 2.0 report engine (web-based viewer)
Installation instructions for viewer
Documentation:
http://www.eclipse.org/birt/phoenix/deploy/viewerUsage.php

BIRT designer and DHIS 1.4
When successfully running BIRT here is a few hints on data source when using this with a DHIS 1.4 datamart file:

Start by selecting File -> New Report. Give it a suitable name
You need to make sure that there is a ODBC connection setup to access your datamart file. This is done on DHIS installation so there is a good chance it is already set up.
Right click on Data Source, Select New Data Source, select JDBC Data Source and give your data source a name (e.g. DHIS_xBW_BOTSWANA), next, select the ODBC-JDBC Bridge driver, replace <data source name> with the name of your ODBC connection (e.g. DHIS_xBW_BOTSWANA), leave username and password blank and test the connection and your finished.

Then to get some data to work with you have to set up a data set:

Right click on Data Sets and select New Data Set
Give your data set a name, select your data source, and keep the SQL Select Query Selected.
Then you can access your data mart tables and views (pre-defined queries) and set up your query to get some data.
As a start I recommend using the views, queries that are part of the datamart database that already combine the data in a meaningful way. Excel pivot tables also uses these views to get data.
In type, select View, and click 'Apply Filter'
Then you can see the queries for routine data and indicator, for 7 different (if you need that many) orgunit levels. Using the Botswana datamart you can e.g. select and expand the PivotSource_RoutineDataOU2 queryto get district data. Then you will see the available columns (type of data) that you can pull out. To make a basic report showing a data element (e.g. BCG doses) for all districts for 1 month (e.g. Jan-04) you would have to do the following:
- In the right window you see your query. This can be build by dragging fields from the left side or simply by writing the query directly. If you drag you have to remove the prefix PivotSource_RoutineDataOU2 and just keep the column name (e.g. District) (I don't know why!). To pull out the districts, the data element short name, the period and the values (EntryNumber) and specify that you only need the BCG doses for Jan-04, use this query:
  select District, Period, EntryNumber, DataElementShort
  from _PivotSource_RoutineDataOU2
  where DataElementShort = 'BCG dose' and Period = 'Jan-04'

To put these data into the report the easiest way for just testing is to drag the dataset (the one you just created) into the report layout and drop it there.

To view the report click on preview.
To print the report, go to the top menu: File->Preview as pdf and click print from within acrobat reader (or similar).

Data source integration

Using BIRT and Hibernate

BIRT provides a JDBC data source. Use the Open Data Access (ODA) Extension API to create custom data sources drivers. Each driver has run-time behaviour along with optional design-time UI. The 2.0 M2 release includes a new feature:
"Often the BIRT engine is embedded in or is part of an existing J2EE application. The ODA layer, which is responsible for data access, occasionally needs access to objects in the Context of the encapsulating application. This might include things like security credentials, connection handles, or parameter objects. To accommodate this requirement, BIRT 2.0 has added a Context Object within the ODA layer, which can be passed in from the external application. This object can take many forms and can be used for all of the items mentioned above."
See: http://eclipse.org/birt/index.php?page=project/notable2.0M2.html#jump_6

More info on the Eclipse ODA API here:
http://www.eclipse.org/datatools/project_connectivity/connectivity_doc/OdaOverview.htm

TASK - Integrate BIRT and DHIS 2.0

1. Integrate the report engine and report viewer with DHIS 2.0 by developing a web-based BIRT report module for DHIS 2.0 that generates reports based on the design from the BIRT designer and input parameters from the user (orgunit, period ++) and displays the report using the BIRT report engine within the DHIS 2.0 app. Data access is provided by jdbc directly towards the DHIS 2.0 databsse (standard way to do it in BIRT).
2. Set up the BIRT designer with the dhis-api as a custom data source (more long term goal)

Other resources

*Intro to BIRT
*Using BIRT and Hibernate
*Blog post: Integrating BIRT with Your Application