Thursday, September 11, 2008

Naming Exported files from the BIRT WebViewer

A common question we get on the BIRT news group is how to change the name of an exported document. For instance, exporting to PDF, the developer may wish to have more control on what filename is used for the export. Currently the name used is just the report name followed by the emitter extension (eg MyReport.pdf).

BIRT 2.3.1 which will be released later this month now supplies a solution to this problem. The example web viewer has a setting that can be added to the web.xml that allows you to specify a Java class that will be responsible for generating the name.

<!-- Filename generator class/factory to use -->

The class specified must implement the IFilenameGenerator interface, which has one method named getFilename. This method is passed four parameters.

baseName – Contains the base filename for the report, with no extension provided.
fileExtension – The extension for the selected operation (ppt for export to PowerPoint).
outputType – The operation being executed. More on this parameter later.
options – Specific options for the operation.

The instance of the IFilenameGenerator is called in multiple locations within the example viewer. When you export the report:

When you export the report data:

And when you use the /document servlet mapping, for example:


This URL will run the report and download the rptdocument.

Suppose you wish to have the date in your filename, when exporting the report. To do this, create a class with the following code:

package my.filename.generator;
import java.util.Date;
import java.util.Map;
public class MyFilenameGenerator implements IFilenameGenerator{

public static final String DEFAULT_FILENAME = "BIRTReport";

public String getFilename( String baseName, String extension, String outputType, Map options )
return makeFileName( baseName, extension );
public static String makeFileName( String fileName, String extensionName )
String baseName = fileName;
if (baseName == null || baseName.trim().length() <= 0)

// check whether the file name contains non US-ASCII characters
for (int i = 0; i < baseName.length(); i++) {
char c = baseName.charAt(i);

// char is from 0-127
if (c < 0x00 || c >= 0x80) {

// append extension name
if (extensionName != null && extensionName.length() > 0) {
baseName += (new Date()).toString() + "." + extensionName;
return baseName;

If you check the source, you will notice this is just the default class with one modification.

baseName += (new Date()).toString() + "." + extensionName;

Which just inserts the date into the output.

You can also check the operation type if you wish to set the name based on the operation. Currently the available options for outputType are:

IFilenameGenerator.OUTPUT_TYPE_EXPORT – When exporting report to one of the supported formats.
IFilenameGenerator.OUTPUT_TYPE_DATA_EXTRACTION – When exporting report data.
IFilenameGenerator.OUTPUT_TYPE_REPORT_DOCUMENT – When using the document servlet mapping.

This example is located here.

Vincent Petry from the dev team has also uploaded a Birt Viewer 2.3 User Reference, which describes the settings and parameters available with the example web viewer. This document is informative and is located here.

If you wish to build your own version of the filename generator, make sure to include viewservlets.jar from the WebViewerExample\WEB_INF\lib directory in your build path.


Yasin Mallı said...

I want to cancel 'ppt' exporting option and some other changing from default options.
Where can I find configuration files about that points.
Please help me.

Jason Weathersby said...


If you want to delete the ppt export option remove the ppt emitter plugin from the WEB-INF/platform/plugins directory.


Manish said...


I want to use this class to construct report name based on report parameters. How could I possibly access report parameters from within the class MyFileNameGenerator.

Please clarify.

Jason Weathersby said...


Look at the options in
public String getFilename( String baseName, String extension, String outputType, Map options )

I believe the HttpRequest is stored in the options as httpRequest which should contain your parameter values.

Manish said...

Thanks Jason. Your suggestion worked for me.

Corrado said...

Please Help to install plugin...

i Try with your bulded class and a rebuilded by me (i verify the correct reference).

When i copy the class in WebViewerExample\WEB-INF\lib\my\filename\generator\MyFilenameGenerator.class

in birt 2.3.2 runtime, and add the line you specified in the web.xml, the viewer response with an error:

HTTP Status 404 -


type Status report


description The requested resource () is not available.


Apache Tomcat/5.5.27

what i can do to solve this problem? excuse me but i'm nibble on plugin for birt!


Jason Weathersby said...


If your class is not jarred try moving it to

Also did you set the web.xml entry

al91206 said...


You said "BIRT 2.3.1 which will be released later this month now supplies a solution to this problem."

When I export from the interactive viewer, the filename is simply iv.extension - not even the reportname.

If this is fixed - can you let us know where the option is set - or where to configure this?



Jason Weathersby said...

This feature should make it in the Actuate 11 version. Or at least the name that corresponds to the report name.

Suresh said...

is it possible in BIRT 2.2.1

Jason Weathersby said...


I believe this is only supported with 2.3.1 and above.


Bernhard said...


I know, the original post is > 2 years old now, but I wonder if this is supposed to work with BIRT 2.6.1, Java 6 and Tomcat 6.0 ?

I'm struggling getting this to work. I've tried the following so far:

1. change web.xml entry
my.filename.generator.MyFilenameGenerator, restart Tomcat => report viewer still works, thus I assume the viewer will use the default routine if the class is not found
2. create a "classes" dir below the WEB-INF dir and copy from the example files the structure below the bin dir into classes (=> WEB-INF\classes\my\filename\generator\MyFilenameGenerator.class), restart tomcat => error 404 as in Corrado's post
3. check the Tomcat Web Application manager; report viewer is not running. Try starting the report viewer. Message: FAIL - Application at context path /birt-viewer261 could not be started
4. remove MyFilenameGenerator.class, report viewer starts => so there must be something wrong with the class?
5. create a new java project in Eclipse and import all example files. Edit the Build Path Library entry for viewservlets.jar to the file in WEB-INF\lib.
6. In, the line starting with "public String getFilename" shows 2 warnings: "- implements
- Map is a raw type. References to generic type Map should be parameterized" => not sure what this means (I am not familiar with JAVA)
7. Ignore warnings, export generated class files to MyFileNameGenerator.jar. JAR Export finished with warnings.
8. Copy MyFileNameGenerator.jar to WEB-INF\lib. Try starting the report viewer. Message: FAIL - Application at context path /birt-viewer261 could not be started

I've seen this solution in 2009 and it worked. Since my requirement is different to the example and I did not figure out how to achieve this without learning JAVA first, I've postponed it hoping this feature would make it into the report viewer. I've no idea what I could have done different those days, except that it was a different BIRT/JAVA/Tomcat environment.

So far, I could use BIRT without knowing much about JAVA - using the Report designer, some javascript, mysql and php was sufficient. My requirement is pretty simple, as in Manish's post: I want to use this class to construct report name based on report parameters. E.g. __filename=xxx just as there is a parameter __title. I could even accept __title as a default filename rather than the name of the rptdesign file. Your answer "Look at the options..." worked fine for Manish - obviously it's easy with JAVA skills.

Any help / hint / clue is highly appreciated.

Jason Weathersby said...

Can you try jarring the package and put the jar in the WEB-INF/lib directory. If you need the jar I can send it to you. I tried this with 2.6.1 and it works fine. My email address is jasonweathersby at windstream dot net. Send me an email.


Jason Weathersby said...

BTW I modified the code to use a __filename parameter. The source and jar to deploy it can be downloaded here:


Bernhard said...

Hi Jason,

thank you very much for the fast response. The provided .jar file works fine. The reason why my .jar file did not work was because of different Java versions in Eclipse (JVM 1.6) and my Tomcat Installation (JVM 1.5). It seems the original .class file was also compiled with 1.6 while the new one is 1.5.
At least, after changing the compiler compliance level to 1.5 in Eclipse, I was able to build the project and export "my own" .jar.

Also lots of thanks for showing how to access the report parameter - I'm sure I would have spent some more hours to figure this out by myself.

abhijit said...

I want to cancel 'ppt' exporting option.I am using "org.eclipse.birt.runtime_3.7.0.v20110615-1818.jar" file. How to do that.

kedd said...

good day! May I ask how can I use this?
I've tried to put the jar file in the WEB-INF/lib
and then change the web.xml
content part from this:


to this...


but when I generate the report and extract it.. nothing happens to the filename?

can anyone help me, please?.. I don't know what I am missing.

I am using BIRT 2.3.2

and I got the jar file from here.

Thank you in advance.

Anonymous said...

Hi Jason,

I tried the steps you mentioned but it didn't work for me. I am using eclipse 3.7.1 birt all in one for Maximo.

I created Jar file and placed in lib folder, I also tried placing class file file in classes folder but nothing worked. When I export report from eclipse its showing old report file name.

any help will be highly appreciated.


Werner said...

Hi Jason,

I managed to change the filename generator to include the date.
Now, I want to include a set of chosen report parameters in the export filename. I could not find an example how to do this. Could you please help me with this?

Tanks a lot, Werner

Sadaquat Ali Ruk said...

Hi Jason...

I am not able to download the jar provided at
It gives me a permission error even though i am a registered member.
Can you suggest me the alternatives.?
Waiting for your prompt response.

Anonymous said...

Jason's sample no longer available in the link.

For gettting the parameter from options, below code can be used:

public String getFilename( String baseName, String extension, String outputType, Map options ) { options.containsKey(OPTIONS_HTTP_REQUEST); options.containsKey(OPTIONS_HTTP_REQUEST); javax.servlet.http.HttpServletRequest a = (HttpServletRequest) options.get(OPTIONS_HTTP_REQUEST); String fn = a.getParameter("__filename")+ "_" + a.getParameter("__dataset") + "_"; baseName = baseName + fn; return makeFileName( baseName, extension ); }


Anonymous said...

I am new to BIRT Report. Where I have to add this class file.I cant understand.please help me

Unknown said...

Merry Christmas,
Very nice and informative post. Please keep it up. If you want to read Christmas Wishes you have to see the link
Thank you,

Zeeshan said...

The very next time I read a blog, I hope that it does not disappoint me as much as this particular one.Funny Happy New Year Quotes I mean, I know it was my choice to read, but I truly thought you would probably have something useful to say. All I hear is a bunch of crying about something that you could possibly fix if you were not too busy searching for attention.