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.
- JFreeReport-WizardReport.properties - 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:
- 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.
- The Report Design Wizard extracts strings from the action sequence file for translations into a .properties file, whereas the Report Designer does not.
- The Report Design Wizard generates a sample icon for the action sequence where the Designer does not.
- 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 :).