Thursday, August 31, 2006

Designing Reports in Pentaho: Save As versus Publish

As part of my job at Pentaho, I occasionally get to help build solutions using the Pentaho BI platform and the solution building toolset, Design Studio, Report Wizard and Designer. I really enjoy that time, in part because I miss my developer days, but also because using the software we build makes me feel like I can connect and relate more to our community. The end product is I can do my job better, because I know the project and the software better.

I recently started creating some reports against our case tracking data, which lives in a JIRA database. JIRA is a phenomenal issue tracker, but I just can't get the reports and data analysis out of it that I really need. And that's OK, that's what we have the Pentaho platform for. One thing I came across that I thought would be good to explain a bit is the difference between "Save As" and "Publish" in our report designing tools.

Both the Report Designer and the Report Design Wizard have a "Save As" option and a "Publish" option. The "Save As" option is pretty straight forward, and "Publish" is a very powerful feature, if you know how to use it:) I have to warn you at this point that these options do produce slightly different results when you are in Report Design Wizard than when you are using Report Designer, and I will spell out what those differences are in a moment. If you are wondering WHY this is the case, read my previous blog post:)

Let's start by talking about what Save As and Publish do in Report Design Wizard.

If you choose the Save As option in the Report Design Wizard, you are saving the entire state of the wizard session you are in. The file will have a .xreportspec extension, which is the file extension that the Report Design Wizard expects when you select the File | Open option in the wizard. It may not seem intuitive at first to "save" the state of a wizard. However the wizard allows you to set so many options for your report, that you may want to go back to your wizard session and tweak a few report features. This makes less sense when you have the Report Designer, which gives you much more powerful report tweaking capabilities. The Save As option in the Report Design Wizard was built at a time when Pentaho didn't have a Report Designer, and so, as the two tools become more tightly integrated, I would hazard a guess that this Save As feature may go away.

The real power of the wizard is in its Publish feature. When you choose the Publish option from the Report Design Wizard, you get a number of files that amount to everything you need to run that report in the Pentaho BI platform. Here is a list of the files that would be generated with a Publish, and what they are for:

  • JFreeReport-WizardReport.xreportspec - the saved wizard session. This is the same file you would have if you chose the Save As option.

  • JFreeReport-WizardReport.xml - this is the JFreeReport report definition.

  • JFreeReport-WizardReport.xaction - this file is the action sequence built to run this report in the platform. If you are not familiar with action sequences, you can get a great overview from the Pentaho Creating Solutions Guide.

  • - this is the resource file, used for holding the action sequence's extracted strings. This file facilitates internationalization of your action sequence.

  • PentahoReporting.png - a sample image, referenced in the action sequence, that can be used in to represent this report in your solution's UI.

The Report Designer's Save As and Publish functions serve the same purposes, but result in slightly different outputs.

When you select the Save As option in Report Designer, you are saving the designer session you are working in. The file will have a .report extension, which is the type of file that the Designer expects on opening of a file.

When you choose Publish with the Report Designer, there are fewer files than what the Report Designer produces, but the same end goal is achieved. Here are the files produced by the Report Designer and what they are for:

  • Report.xml - this is the JFreeReport report definition.

  • Report.xaction - this file is the action sequence built to run this report in the platform.

Why, you might ask, does the Report Designer generate less files, but accomplish the same task? There are few differences between the outputs that I should note:

  1. First, the Report Design Wizard still gives you the wizard session (.xreportspec), even when you Publish, whereas the Report Designer does not give you the designer session (.report) on Publish.

  2. The Report Design Wizard extracts strings from the action sequence file for translations into a .properties file, whereas the Report Designer does not.

  3. The Report Design Wizard generates a sample icon for the action sequence where the Designer does not.

  4. Another difference worth noting, that is not apparent by examining just the list of output files, is where the query for the report lives when either tool publishes. The Report Design Wizard will put the query in the action sequence file, which is the best practice. The Report Designer embeds the query in the JFreeReport definition.

These differences constitute minor inconsistencies in implementation that I'm sure will be addressed very soon. That is everything I had hoped to cover.

I hope that this helps a few people get up and running with Pentaho Reporting, because it really is quite an extraordinary set of tools, and just keeps getting better (not that I'm biased or anything :).


Anonymous said...

Why do we need the xaction file, why cant we just run the report directly without going through the xaction? This is something I have never understood with the Pentaho platform. I can see that there is a point if working with workflow functionality including for example triggering alerts. But for a small installation not including work flows are xactions necessary?


/Eric the Swede

Gretchen said...

Hey Eric,

To run a JFreeReport standalone, you do not need an action sequence. You only need the JFreeReport reporting library, which is downloadable from

Because the platform is a workflow oriented system, it may seem like extra work to create an action sequence for a single task (generate a report). But we have found over and over again, case after case, that inevitably that single task will become part of a process. Even if that process is just to notify someone that the report was generated, or provide accountability for generation of the report (an audit trail or execution log).

That being said, the action sequence will become more and more invisible as we enhance the Pentaho Open BI Suite toolset, since we do understand that ease of use and elimination of steps is very important to the users of the suite.

Thanks for your input Eric, hope this helps!


daniel said...

i am using pentaho report designer ,is there any need to run the pentaho demo(server),can i connect to mysql,so that i can get the data from mysql for reports,JNDI connection is established but i am getting "no suitable driver",please post me your reply
thank you

Gretchen said...


No suitable driver driver implies that the driver library cannot be found. There are detailed explanations on where to put your driver jar in our forums at

all the best,

Noah said...


I don't see a "Publish" button anywhere in the Report Design Wizard Eclipse plugin (1.2), though I see it in the standalone version. How can I publish a report from Eclipse?

It appears that the Eclipse version is the forgotten stepchild: the documentation refers primarily to the standalone version, which also has more templates included. I hope the Eclipse version will get more attention, since it's useful for working on xaction files.

Thank you,

Gretchen said...

Hi Noah!

Yeah, the publish button was removed intentionally from the Eclipse version (also known as Design Studio). The idea behind Design Studio is that you are working in a solution project that has reference to your server already, so you don't need to publish the report. If you tell me your use case (ie., what your working scenario is), maybe we can make a case for publishing from the wizard within Design Studio. Post your response in our forums at .

As I noted in my blog, we are working toward design environment that integrates all of the design tools for the platform, so creating and publishing reports should get easier and easier.

And last, the documentation was originally written for the standalone RDW, but there is ecxtensive documentation for the Design Studio at

kind regards,

Carlos said...

Hi Gretchen.

First of all, I'd like to apologize for use your blog with a question about Pentaho, but I can not find the answer in the traditional forums (pentaho, google,..)
I have the following problem with the Report Design Wizard (windows) publishing in a Linux Server.

I have a problem with Report Design Wizard ( GA) running under windows. The Server ( GA) run under Debian and Tomcat 5.5.

When I try to publish a report directly to the server, it upload the files in the wrong folder with a wrong name. (slash and backslash problem)


I create a report called "report1" and I want to publish in /samples/reporting.
I publish the report successfully but when I browse through the directories and the files into the server I can see that the files (.xml,.xaction) have been uploaded to the folder "/samples" (not /samples/reporting) and their names are "reporting\report1.xml", "reporting\report1.xaction" ....

I think that must be a problem between report wizard in windows and a server under linux with the slash and back slash.

Could you help me?

Thanks in advance and I'm sorry again

Carlos de la Torre

Gretchen said...

No apologies necessary Carlos, I am happy to pass along the info and get you some help for your problem. I have logged your issue as a bug in our tracking system, as it seems pretty clear that that's what we are dealing with. You can track the progress of the issue here .

You went the right route in trying to get your issue addressed, the forums really are the best way to go.

kind regards,

Gretchen said...


Now I'll apologize - I had a URL on the "here" in the statement you can track the issue progress here - and it dissappeared! You're case URL is .

kind regards,

Carlos said...

Thank you very much!!!!

Anonymous said...

I'm having lots of problems getting Pentaho Report Design Wizard 1.2.1 to work with SQL Server. I can get the jndi to connect to the server, not the specific database. When I specify in Query Designer comes back with Connection failed to return data.
Any instructions on how to set up to specific SQL Server database? Or why Query Designer not working?
Beth Good

solutionhacker said...

hi, Gretchen

I want to integrate pentaho with my dao layer instead of using SQLLookup that goes to JDBC directly. Has anyone done that before?


Hardhono said...

How can I publish Pentaho Report Designer Wizard using Tomcat as server?

First I put password for publish on pentaho-solutions/system/publisher-config.xml Then I run publish on Pentaho Report Designer Wizard and I empty user id and password. But I haven't success publish. What is user id and password? Is it same as tomcat admin or what?

Gretchen said...

The username and password are the admin username and password of your Pentaho platform installation. The demo PCI ships with an Admin user "Joe" for instance.

Hope this helps,\

Justinfo said...


We are considering using the pentaho open source reporting tool. Need to be able to create custom reports and access them via tomcat.

I looked around and couldn't find an easy step-by-step guide/instructions which allows me to do that.

What I'm looking at:

1. Deploy pentaho reporting only on tomcat
(what is solutions and do I need to deploy this alongwith reporting)

2. Use the report designer wizard by accessing it thru a web url, say,

3. Reports should be saved to a path specified.

Is this possible ?

If not, can you please suggest me an alternative.

Many thanks

Gretchen said...

dear justinfo,

What you would like to do is possible with Pentaho. You can start either by downloading the Pentaho demo server (PCI), or by installing the Pentaho server into an existing Tomcat. You'll then need to create a metadata model for your database(s). The metadata model works with Pentaho ad-hoc reporting, which is the web-based report designer. Users have the ability to save reports out of the web-based designer, to a structure defined on the server or in the server repository. (The Pentaho Report Designer project and the Report Design Wizard are both Java applications that you can download to design reports, but are not yet web-based.)

You can read up on how to do much of this here:

Hope this is helpful,

Justinfo said...

Dear Gretchen

Thanks for the doc link. That was useful.

I have now been able to setup and access pentaho homepage on tomcat connecting to postgresql.

However, the next problem I have is that I'm unable to login as pentaho_user/password which is the default.

How do I proceed from here ?

The default users available in the drop-down list dont appear to work.

Am I required to run any other scripts ?

Appreciate your help with this.


timchamplin said...

Awesome blog, I wish to pose a question. RE: MyReport.xAction.
I have a query_result, a reportDef.xml and am trying to send ReportOutput.csv to file://C:/Folder/

I am able to create a string file to the location, but I fail on sending the Report.csv to that folder.
(ref Pentaho 1.7 server on windowsXP). Is there something preventing a formatted report as the file output?

Sebastian said...

Hello Gretchen, I want to design a report with the Analyzer (or the Ad-Hoc in the web-user-console or the Spoon) that can be consumed in a J2EE application.

I can't find the Publish option to get the .xml I suppose I need to put it in my Tomcat server and be consumed.

I can't find any complete documentation for my needs.

What should I have installed (BI-Server, Jars for connecting from Java code in Tomcat), how is the process to develop the report and the final users can press a button in a web app and get the PDF.

Thanks a lot.

Gretchen said...


Please post your question in our forums. I have run out of time to update my blog unfortunately, and you'll get much better attenstion in the forums!


Anonymous said...

hi! can anyone tell, how can i create a report template in report designer 3.8 (community edition)? When I save and publish a report it only creates .prpt files, it does not create .xreportspec or .xml or .xaction files. looking forward...

Gretchen said...

PRPT is the file format for Pentaho Reports since roughly the 3.5 version of the software (maybe earlier). The .xreportspec and xml docs are now included in the prpt, albeit in much different formats.

You should continue this thread in the Pentaho forums for any further discussion.