BIRT: Annoyance of the WEB.XML File

For those of you who have worked with any of the recent web technologies that have come into fruition in the past 10 years, such as Java and .Net, you will be familiar with a little bastard titled the WEB.XML file. Usually, when I create an application, nice little tools like Visual Studio and Eclipse take care of all the little nasty details and I rarely, if ever, have to handle anything inside of this file. That is not the case with the BIRT Example Web Viewer. I came across a really nasty and annoying issue with it.

The issue, you might wonder, is that if you use the BIRT Web Viewer that is supplied with the BIRT Runtime, which is the recommended installation method from the Eclipse/BIRT homepage, it will completely ignore any setting in the WEB.XML file completely, and instead just go on its merry little way using the default values. So, if your not happy with the location of report documents files in the BIRT Web app, and you are using the viewer supplied by the Runtime package, your SOL. Your stuck with either keeping them in the root of the application, or using the relative path in your report execution. This is a bug, and has already been reported, and verified under Tomcat 4.1, 5.5, with Java 1.4, 1.5, and 1.6, and verified with BIRTs version 2.1.1, 2.1.2, 2.2 M4, and 2.2 M5.

The good news... there is a nifty little workaround, and if your already using the Eclipse BIRT Designer, you don't need to download anything extra, just shuffle around a few files to roll your own BIRT Web Viewer, and you get all the features of the BIRT Web Viewer from the Runtime package, plus the ability to change those settings in the WEB.XML file.

These instructions are demonstrated using the BIRT 2.2 M4 All-In-One package, which has been upgraded to 2.2 M5 using the Eclipse Download Manager. I am also using Apache 5.5, and Java 5 (1.5) for my runtime environment.

• First, locate the birt.zip file under yourr Eclipse designer, located under the BIRT/WTP Integration package. In my case, it is under: C:\birt2_2M4\eclipse\plugins\org.eclipse.birt.integration.wtp.ui_2.2.0.v20070109\runtime\birt.zip
• Extract this package to a folder called birt under your Tomcat 5.5 webapps folder. For me, this is located at: C:\Program Files\Apache Software Foundation\apache-tomcat-5.5.20\webapps\birt
• Now, this should end here, but, there are missing files. All of these missing files, fourtunatly, are located in the BIRT Viewer package. So, file the BIRT viewer package, and copy everything under the "birt" folder to your newly created BIRT web application folder under Tomcat. In my case, I am copying C:\birt2_2M4\eclipse\plugins\org.eclipse.birt.report.viewer_2.2.0.v20070208\birt\* to C:\Program Files\Apache Software Foundation\apache-tomcat-5.5.20\webapps\birt, overwriting any files.
• Restart Tomcat
• If everything worked, you should be able to run the BIRT test report. For me, this report is at http://localhost:8080/birt/frameset?__report=test.rptdesign&sample=my+parameter
• Once this report executes correctly, test to make sure the configuration file changes will work also. Under the /WEB-INF folder, open the WEB.XML file. Look for a section with a tag called BIRT_VIEWER_WORKING_FOLDER. Under this tag, put in the value for the folder you want reports to reside under. In my case, I put in /myReports, for a section that will look like:
  
  BIRT_VIEWER_WORKING_FOLDER
  /myReports
  
  
• Restart Tomcat, or reload the BIRT application
• Re-run the test report (it should error out since the test report does not reside in the new report folder)
• Copy the test*.rptDesign files from to the newly created report folder. Note: this folder gets created by BIRT when the application starts (that is another way you can tell if the configuration is working correctly).
• Re-run the report. Now it should work.

That's it. A fairly easy workaround.