Using Eclipse BIRT Report Libraries and Templates

About BIRT

BIRT is an Eclipse-based open source reporting platform for web applications, especially those based on Java and J2EE. BIRT has two main components: a report designer plug-in for Eclipse, and a runtime engine that you can deploy to your application.

An extended introduction to BIRT is available on this page of the BIRT section of the Eclipse web site:

http://www.eclipse.org/birt/intro

This flash movie highlights the steps for building a report using the BIRT Designer in Eclipse:

http://download.eclipse.org/birt/downloads/examples/misc/BIRT/BIRT_demo_Camv3.html

Business Scenario

We will examine a fictitious company called Classic Models Inc (CMI). CMI is a retailer of scale model classic cars and other vehicles. The organization is planning to implement a BIRT-based web reporting application with a projected large number of complex reports. They wish to leverage a small staff of skilled Java programmers to create and maintain an infrastructure where report developers can build reports for their own departments.  In addition, they wish to minimize any impact to established reports that can occur when the business rules or data structures under them change, as they frequently do in any organization.

CMI arrives at a plan to create a reporting 'center of expertise' made up of their Java development staff, who will identify commonly required report components, such as database connections and queries, and charts and graphs. They will also establish report design standards, incorporating a common look-and-feel and coporate logos.

Additionally, they want to create a set of standard report templates for their report developers, who can use them to build their own reports in a drag-and-drop assembly fashion without IT assistance.

The CMI team decides to leverage BIRT Library and Template features to create and deploy easy to use and tightly controlled report writing capabilities for their report developer community.

Further, the libraries will create an abstraction layer for reports and templates that will help insulate them from underlying changes to data and/or formatting standards, thus 'future-proofing' the reporting application.

BIRT Libraries

BIRT 2.0 Milestone 3 introduces the library feature. With this feature, commonly required functions and report items can be encapsulated within a library. These libraries can then be imported into any number of BIRT report designs and templates for reuse, significantly reducing design time. For example, a BIRT report developer may create a complex scripted data source and then encapsulate it within a BIRT library, freeing other members of the reporting team from implementing the same code for their own designs.

In addition, the concept of libraries helps segment report development tasks by skill set, as opposed to burdening a report developer with creating all components for each report by themselves. For instance, those technicians with strengths in SQL could be tasked with creating only database connection and query components, while scripting experts can concentrate on creating advanced scripted components, and so on. Once complete, a library enables a simple drag and drop report assembly model that can be effectively used by anyone.

Reports that reference libraries are automatically updated when executed. This is very useful in cases where business or technical changes would otherwise require report rework. For example, if library components such as corporate logos and database queries are used in a large number of report designs, then the database schema changes or the company logo is altered, only the library would require the change. All referencing reports would be automatically updated to reflect the change.

This diagram illustrates the concept of using libraries in a report design at a high level. A report developer using BIRT Designer imports a library to a new or existing report design, then they simply drag-and-drop various pre-built components into the report.

The resulting report is a standard BIRT XML report file that can be deployed to the web using the BIRT runtime engine.

Discussion

We will look in detail at how a CMI 'center of expertise' staff member can use the BIRT Designer interface to create a library of components, then make it available for use in other report designs. We will then examine how a library is imported to a design, and how any changes to the library are automatically reflected in the design that is using it.

I will focus first on showing the process for creating several library components for use in a standard CMI corporate sales revenue dashboard reports. The components built will display summary charts and tables.

Creating a BIRT Library

A new project item type is now available for library creation in the BIRT Designer interface. The process begins by selecting the 'Library' item type in the 'New' menu.

This action opens a blank library design view in the BIRT Designer.

The new library file has the extension '.rptlibrary'. I will create a new library with components for sales revenue reporting called 'CMI_Sales_Reporting.rptlibrary'

Next, open the 'Outline View' in the BIRT Designer, then add report components by right clicking over the 'Report Items' icon and selecting 'Insert'.  The desired type of component is selected from the 'Insert Element' menu.

(Alternatively, items can be added to a library by dragging them from the component Palette View to the Outline View.)

Components that can be added to a library include Data Sources and Sets, Report Parameters, Grids, Charts and Tables, Themes, and Images.

Once added to the library, component properties and attributes are then set using wizards and/or property editors just as in any BIRT report design.

All added components are displayed in the Outline View, where they can be accessed for further adjustment and visual fine tuning as required.

The experience of building a report component library is very similar to building a BIRT report, and does not require advanced technical knowledge.

When the library is completed and saved, report developers can then access the .rptlibrary file and import it to their designs. Once imported, all components in the library can be easily included to a report in a simple drag-and-drop fashion.

Using a BIRT Library in a report design

Next we will examine how a report developer can access, import, and use  a library in their own design. We begin by looking at a report design already in progress, in which we wish to use pre-built components such as data connections, charts, and tables from a library. To access the library, the developer opens the Library Explorer View in the BIRT Designer.

Next, the preferred library is opened in the Library Explorer View, and all desired components are dragged directly into the report design where appropriate. By dragging components to the design, the Library is automatically imported to the report design file. Here we see dragging a chart from the library into our design.

Because all data connections, queries, and formatting are encapsulated in the library components, no further adjustments or settings are required for the chart. Next we will drag a table component from the library to the design.

Then we will preview the report by running it.

Changing a BIRT Library component

Now lets make a change to the library, and see the results in the new report design that references it.

In the 'CMI_Sales_Reporting.rptlibrary' file, we will add a new column to the summary table. The column will contain dynamic images to indicate positive or negative revenue growth for our various product lines.

Once the library change is made and saved, all reports using this component will inherit the change automatically.

To see the automatic inheritance in action, lets re-open the new report where we are using the table component from the library.

The change to the table is reflected with no user intervention. This is because the table component is referencing the library that it came from. Now lets re-run the report and see the finished change.

In addition to referencing properties in the 'parent' library from which they came, individual components can be modified locally in the report by the report developer. Any local changes to specific properties will persist, while remaining unchanged properties will continue to reference their settings from the 'parent' library. For example, a report developer could change the backgound color of a label component they have added from a library. The new color will persist in the single report from that point on, while font size and style properties for the label will continue to be referenced from the library.

As shown in this simple scenario, the library feature in BIRT is a powerful way to efficiently encapsulate report functionality in reusable, pre-formatted components that can be easily added to any report design. The ability for any report to automatically inherit changes from libraries also provides the level of abstraction required by CMI to insulate their report designs from underlying changes to their business or data.

BIRT Templates

BIRT now provides the ability to build and publish report templates. Consistent look and feel can be difficult to achieve and maintain when building web reporting applications. In addition, productivity and adoption by a broader range of report developers can be fostered by providing a pre-built report elements. Templates address these concerns and can range from skeletal outlines with predefined themes to complete reports.

Additionally, BIRT templates can be complimented with BIRT libraries to deliver the easiest possible experience to the less technical CMI report developers who wish to build reports.

This section of the article will examine how to create a BIRT report template that includes a pre-formatted report structure and layout, as well as a BIRT library of components, to facilitate easy and expedient report designing.

This diagram illustrates the concept of using report templates that contain libraries at a high level. BIRT report developers select the template when building new content, then choose from a variety of pre-built components included in the included library, as well as generic components in the component Palette. These components are then simply dropped into a pre-formatted standard layout. Report developers are spared the tasks of report construction that may be complex or time consuming.

 
The resulting report is a standard BIRT XML report file that can be deployed to the web using the BIRT runtime engine.

Creating a BIRT Template

Building a BIRT report template is very similar to building a standard BIRT report. The process begins by selecting the 'Template' item type in the 'New' menu.

This action opens a blank Template design in the BIRT Designer. The new template file has the extension '.rpttemplate'. We will create a new template that report developers can use to quickly create product sales dashboard reports called 'Sales_Dashboard.rpttemplate'

Next we will include a library to the template in order to leverage pre-formatted components in the design.

Next we will add a corporate header that is already fully formatted with the company logo and color scheme, from the library to the template.

We will also add generic Grid and Label components from the component Palette, then format and arrange them to a dashboard style layout.

For those elements in the template that can be edited or changed, descriptive prompts are added to guide the developer. In this case we wish to indicate to the developer that the label can be edited. This is accomplished by right clicking over the component and selecting 'Create Template Report Item', then adding a prompt phrase.

This is repeated for all elements that the template user can edit or change. Once complete, the template is then ready to be published for use by the CMI report developer community.

Publishing a BIRT Template

The BIRT Designer now includes a Template Publishing Wizard that quickly deploys templates for use. It allows the template developer to specify what the user will be presented with when selecting the new template, such as a display name, description, and a sample image of the layout.

Templates are typically published to a central location in order to serve a community of report developers. The publish location is configurable, and can be set from the BIRT Designer interface by clicking 'Window>Preferences>BIRT>Template'.

Using a BIRT Template

Now that the template has been published, we will examine the report developer experience using a template in BIRT Designer.

The process begins by selecting the 'Report' item type in the 'New' menu. This presents the standard list of report templates, as well as the new Sales Dashboard template that was published earlier. When the new template is selected, properties entered in the Publish Template Wizard are displayed.

By following template item prompts, and by dragging components from the included library, we can very quickly create a Sales Dashboard report in simple drag and drop fashion.

After adding a table and a chart from the library, and editing the report title label, we can preview the new report by running it.

Using this BIRT template, CMI report developers can quickly create sales summary content that is complete with corporate logos, colors, database connections and queries, and fully formatted tables and charts, using an easy assembly model. Because the template includes a library, reports built from this template are also shielded from underlying changes to the business or data. If anything changes, CMI Java developers only need to adjust the library, and all reports based on this template will reflect the change.

Deploying a BIRT report

Deploying BIRT content to the web is a straightforward process, especially in the case of deploying via a J2EE based web application.

In this example we will deploy the sales report created in the previous scenario to the CMI corporate web site, making it available to sales executives across the company. The CMI website is a J2EE web application that runs in the Apache Tomcat servlet container, we will add the BIRT report engine to the application, then access and run the report over the web.

BIRT engine

A BIRT runtime engine example J2EE application (including the viewer framework) is supplied as part of the BIRT package of plugins for Eclipse. It is found in 'eclipsepluginsorg.eclipse.birt.report.viewer_x.xbirt'. In most cases it can be deployed to the servlet container without modification.

To quickly deploy the engine to the Tomcat based CMI web application, we only need to copy the 'eclipsepluginsorg.eclipse.birt.report.viewer_x.xbirt' directory to the 'Tomcat 5.5webapps' directory, then restart the Tomcat server.

Because the BIRT viewer example application is J2EE compliant, the Tomcat servlet container instantly recognizes it and adds the context to the server root. Alternatively, you can leave the BIRT viewer directory separate from the application directories, and add appropriate code to the Tomcat application context configuration document "Tomcat 5.5confserver.xml" as such:

<Context path="/birt" docBase="C:birt" debug="0"/>

To test the viewer install, simply access it via a web browser. The URL syntax to access the BIRT viewer is: 'http://<web server name>:<port #>/<BIRT viewer context name>'. For example, we have deployed our BIRT viewer to the CMI web application, so the URL is:

http://CMI_intranet:8080/birt

Next, we will copy the report design created earlier to the  BIRT viewer framework directory.

Our work in the BIRT Designer created a report design file with the file extension: '.rptdesign'. This file is found in the workspace directory for the report design project, our report file is called: 'Sales Dashboard.rptdesign'

Once this file is copied to the BIRT viewer directory, it as accessible via the web. We will copy our report design file to a folder under the 'birt' directory called 'report'

Now we can access and run our report over the web by issuing appropiate URLs to the BIRT engine. To run the sales dashboard report, we simply use the URL: http://CMI_intranet:8080/birt/Sales Dashboard.rptdesign

As implied by this example, deploying BIRT report content to the web is straightforward and expedient.

Conclusion

This article has detailed how an example company has realized their goal of building a standards based reporting infrastructure that facilitates easy report creation for their community of report developers by leveraging the rich Library and Template features in BIRT. Further, they have addressed the impact of business environment changes on their report content by relying on the inheritance capabilities of the BIRT Libraries.

Next Steps

Visit the BIRT section of the eclipse web site (www.eclipse.org/birt) for more information on BIRT, including tutorials, examples and the downloads for both the designer plug-ins and the runtime engine.

BIRT also has a very active community. Visit the community page: http://www.eclipse.org/birt/index.php?page=community.html for information on how to participate.

About the Author:

Mark Gamble is part of the BIRT team.