Tuesday, July 11, 2006

BIRT: BIRT Report Scheduling without Apache Tomcat

Previously I had written about a way to schedule reports to run with BIRT using Apache Tomcat, wget, and a scheduling service. To me, this is a cumbersome and inelegant solution to a very simple problem. However, one of the great things about BIRTS architecture is that there are a number of different solutions to any given problem. In this article, I will show a simple way to schedule BIRT reports to run automatically that requires no programming and does not require Tomcat to run. This is a great solution for those who, like me, do not like the idea of loading unnecessary services where they are not required.

There are only two requirements for this solution. First and foremost, be sure to have Java on the machine that will run the reports. I have come to prefer Sun Java to other Java or Java-like solutions, such as the GNU Java interpreter. I had previously written about many compatibility issues running Eclipse and other Java centric programs using interpreters other than Suns. The second requirement is that you have the BIRT Runtime libraries, available from the BIRT Download page. For this example I am using BIRT 2.1 runtime, which has been extracted to C:\birt_runtime. I will use the Hello_World.rptdesign file that is included with the BIRT Runtime package, located under C:\birt_runtime\birt-runtime-2_1_0\ReportEngine\samples and output to HTML under the same directory. I will use the Windows Task scheduler to schedule this report to run each night.

First, I am going to create a batch file called runReport.bat. The file will be simple and only have the following lines:
Set BIRT_HOME=C:\birt_runtime\birt-runtime-2_1_0\
C:\birt_runtime\birt-runtime-2_1_0\ReportEngine\genReport.bat -runrender -output "c:\birt_runtime\birt-runtime-2_1_0\ReportEngine\sameples\output.html" -format html “C:\birt_runtime\birt-runtime-2_1_0\ReportEngine\samples\Hello_World.rptDesign”

To Schedule this file to run, I go under Control Panel, Scheduled Task, and create a new Scheduled Task. I set the command to run as C:\birt_runtime\birt-runtime-2_1_0\ReportEngine\runReport.bat. I set up the appropriate time, and set the directory to start in as C:\birt_runtime\birt-runtime-2_1_0\ReportEngine\. I also set this to run as a dedicated report user. Figure 1 illustrates the values I used under Scheduler.

Figure 1. Values used to run BIRT report.

Now, I can schedule BIRT Reports to run without needing Apache. This cuts down on system overhead. There are a few caveats to take into consideration. If your BIRT report hits a database, the appropriate drivers will need to be included in the ReportEngine\plugins folders. For example, if the report uses JDBC to connect, the JDBC drivers will need to be installed under the ReportEngine\plugins\ org.eclipse.birt.report.data.oda.jdbc_<version> folder. Also, you will need to copy the iText.jar file as indicated in the BIRT Runtime installation instructions to the appropriate plugins directory.

From this exercise I learned a few interesting things. I was unaware that Java classes could be invoked from the command line. For example, if I set a environment variable called BIRT Class Path like so:
SET BIRTCLASSPATH=%BIRT_HOME%\ReportEngine\lib\commons-cli-1.0.jar;%BIRT_HOME%\ReportEngine\lib\commons-codec-1.3.jar;%BIRT_HOME%\ReportEngine\lib\com.ibm.icu_3.4.4.1.jar;%BIRT_HOME%\ReportEngine\lib\coreapi.jar;%BIRT_HOME%\ReportEngine\lib\dteapi.jar;%BIRT_HOME%\ReportEngine\lib\engineapi.jar;%BIRT_HOME%\ReportEngine\lib\js.jar;%BIRT_HOME%\ReportEngine\lib\modelapi.jar;%BIRT_HOME%\ReportEngine\flute.jar;%BIRT_HOME%\ReportEngine\lib\sac.jar;

I can run the following command from the DOS prompt and get the parameters that the ReportEngine class is expecting:

java -cp "%BIRTCLASSPATH%" org.eclipse.birt.report.engine.api.ReportRunner


--mode/-m [ run | render | runrender] the default is runrender
for runrender mode:
we should add it in the end<design file>
--format/-f [ HTML | PDF ]
--output/-o <target file>
--htmlType/-t < HTML | ReportletNoCSS >
--locale /-l<locale>
--parameter/-p <parameterName=parameterValue>
--file/-F <parameter file>
--encoding/-e <target encoding>

Locale: default is english

parameters in command line will overide parameters in parameter file

parameter name can't include characters such as ' ', '=', ':'
For RUN mode:
we should add it in the end<design file>
--output/-o <target file>
--locale /-l<locale>
--parameter/-p <parameterName=parameterValue>
--file/-F <parameter file>

Locale: default is english

parameters in command line will overide parameters in parameter file

parameter name can't include characters such as ' ', '=', ':'
For RENDER mode:
we should add it in the end<design file>
--output/-o <target file>
\t --page/-p <pageNumber>
--locale /-l<locale>

Locale: default is English

For me, this is a major break from the paradigm of compile and run software in other languages.

Next article, I will show how the same thing can be accomplish programmatically using the BIRT API’s to run the report.


Salome said...


I am using the scheduling as you suggested.

Have you used ReportRunner with parameters yet? It seems to ignore the passed parameters. I have a report which takes a date input parameter and I need to pass in the date when scheduling this report.


Salome said...

Example of what I'm doing:

C:\software\birt-runtime-2_1_0\ReportEngine>genReport.bat -o salome20051111.html
-p DATE=20051111 samples\renewalsForDayByChannel.rptdesign

Note: the date parameter I'm passing in.

Then, I get an exception stating DATE cannot have a null value as below:
C:\software\birt-runtime-2_1_0\ReportEngine>genReport.bat -o salome20051111.html
-p DATE=20051111 samples\renewalsForDayByChannel.rptdesign

C:\software\birt-runtime-2_1_0\ReportEngine>ECHO off
2006/09/29 08:10:51 org.eclipse.birt.report.engine.api.impl.EngineTask validateS
SEVERE: Parameter DATE doesnt allow a null value.
2006/09/29 08:10:51 org.eclipse.birt.report.engine.api.ReportRunner runAndRender
SEVERE: Some required parameter values are not set or set to incompatible data type.
org.eclipse.birt.report.engine.api.EngineException: Some required parameter values are not set or set to incompatible data type.
at org.eclipse.birt.report.engine.api.impl.RunAndRenderTask.run(RunAndRe
at org.eclipse.birt.report.engine.api.ReportRunner.runAndRenderReport(Re
at org.eclipse.birt.report.engine.api.ReportRunner.execute(ReportRunner.
at org.eclipse.birt.report.engine.api.ReportRunner.main(ReportRunner.jav

John Ward said...


I have posted a response here. I hope it helps.


Anonymous said...

Thanks for the wonderful blog.
i can use the command line to export the report to html.

But how can i use this command line if i would like to export to pdf
I tried the following way ,didn't worked
Set BIRT_HOME=D:\BIRT\birt-runtime-2_1_0\
D:\BIRT\birt-runtime-2_1_0\ReportEngine\genReport.bat -runrender -output "D:\BI Projects\BIRT\testreport.pdf" -format pdf "D:\BI Projects\BIRT\Testreport.rptdesign"

Will appriciate any help.


John Ward said...


If I had to guess, I would say your missing iText.jar. By default, I don't believe the BIRT Runtime ships with it. Check here for instructions on how to import iText. Although this is for a CVS build of BIRT, the instructions and plugin paths "should" be the same.


Anonymous said...

Brilliant article (as your other BIRT ones have been). One problem I had is with your use of the "-runrender" option to genReport. It should actually be "-m runrender". Apache's options library seemed to quietly disregard all options after this, specifically the -o output file destination which had me confused for a bit - it was showing up in the same place as the design.

Anonymous said...

nice article, we use a batch job to schedule various tasks as you have described. you might want to stop using the word "interpreter". The Java VM of course translates the bytecodes into machine code that is usually nearly as fast as the binaries produced by gcc, it's not "interpreting" the bytecodes, except perhaps the very first time.

Denise said...

How do I pass multiple parameters?

For example, the following:
"%BIRT_HOME%/ReportEngine/genReport.bat" -o "report.html" -i "images" -d "logs" --parameter "pclint_xmlFile=e:\data\pclint_all.xml" --parameter="cccc_xmlFile=e:\data\anonymous.xml" -t HTML "e:\BIRTrpts\BIQ2.rptdesign"

generates the error:
SEVERE: Required parameter cccc_xmlFile is not set.


Steve Shiflett said...

Denise -

Where did you find the documentation on the parameters? I have an error:

SEVERE: Required parameter rp_issue is not set.

but I cannot find out what rp_issue is.

A said...

Working with Apache Tomcat has been getting complicated with every new project. I recommend using Access Query Scheduler to simplify your information requirements.

Steve Shiflett said...

My earlier problem was solved when I set up my odbc connection as a System DSN rather than a User DSN. After I took care of that, things worked quite fine and my reports work quite well.

Also, the "required parameter" issue was an argument required in the procedure I had written!!!