Knowledge Base (Display) Knowledge Base (Display)

How to add reports & subfolders

How to add reports & subfolders

This article explains how to embed new reports and organize your sub-folders


Reports are xml files with a specific extension ".rptdesign", and created with the open source Eclipse BIRT designer .

Basically to deploy new reports in Visioneo portlet, we just have to copy them in a folder of the server and see them appear in the report browser.

3 steps to deploy a report:

  1. Make sure data drivers used by the report such JDBC  are deployed on your application server. In a production context, it is recommended to make use of connection pools (see section below)
  2. Copy your report ".rptdesign" in the "Report path". This path is explained later in this article.
  3. If some resources are used by reports (such non-embedded images, properties files, javascript file...), they must be deployed in the "Resource path"

Data drivers

Firstly it is necessary to make sure data drivers used by reports are available from the application server. For instance, if a report is accessing a database through a JDBC connection we need to copy the .jar driver related to this database in the same folder as the BIRT engine, or in a shared folder of the application server.

  • For a quickstart: copy your data drivers in <Visioneo application root>/WEB-INF/lib
  • Alternatively: we can install data drivers in a shared folder of the application server. For example with Liferay bundled with Tomcat, if reports make use of a mysql database we can install the appropriate driver mysql.jar in <Liferay home>/<Tomcat home>/lib/ext
  • In a production context , it is highly recommended to make use of connection pools to access databases from reports.
Forgetting to deploy data drivers is a very common mistake, particularly when installing a new Visioneo version!

Copy new reports into BIRT report path

Your reports must have the default extension of birt (.rptdesign). If they don't they will be ignored.
We just have to copy new reports under the root folder specified in <reportlet root>/WEB-INF/portlet.xml, by this parameter:





The 'type' attribute can be an "absolute" or "relative" path . Visioneo Professional edition supports  a third "portal" type, which allows to publish and manage reports as native portal documents.  By default, the path is relative and you will find the root folder here:

<visioneo application root>/birt/reports/demo

It is a good practice to change this default value.  From version 2.0, a powerful demo report named visioneo-sandboxing.rptdesign is included in distributions. This report is useful beyond measure, please use and abuse of it to test in advance if the path you plan to use will be validated by Visioneo engine, by the security manager of the portal (PACL) and by the operating system.

Visioneo Community Edition:

Set an absolute path, outside the scope of the web application. For example:



The folder you specifiy here must exist and your application server should have permission to read it, otherwise the Visioneo engine would log a warning and switch back to the default relative path.

If a security manager is enabled on your portal ( Liferay PACL ), you will most likely get a security exception when testing a new absolute path. Please visit section  " SecurityException with absolute path " of this article to fix it.

Visioneo Professional Edition ( on Liferay portals only ) :

Set a portal path such below, where "14507" is an example of a folder ID created in your portal documents library. Please visit How to add a portal repository for more informations.



From version 2.2 the following format is also supported, furthermore we can test and set " birtReportPath " from a configuration portlet .



Publish your report(s) at this location and organize them as you like in sub-folders. Please notice in the screen below we need to keep the file name of a report-design intact, including extension .rptdesign ,  in "Title" property of the portal document:

By publishing report-designs using "Multiple documents" option of Liferay document & Media this will be the default behavior: the file name without extension is set as document title. Therefore in order to avoid naming mistakes, using this "multiple documents" option is a safe way to publish new report-designs, even if we actually send a single report-design.

This video tutorial demonstrates how to define a report repository with Visioneo PE, how to publish & organize your BIRT reports from a native Liferay portlet "Document & Media", and how to define access permissions for sensitive reports. It is slightly deprecated though because  the configuration portlet was not yet implemented at the time of making this tutorial.

Refresh report list

Deprecated: This refresh is now automatic, please ignore this section if you make use of a recent Visioneo version (v2.1+)
if you install new reports whereas the portlet has already started, Visioneo report-list cache must be refreshed. Use the reportlet admin dialog, or your JMX console to refresh this cache.

Additionally if the report path is left as "relative" (not recommended), please take into consideration this .

Add reports resources to BIRT resource path

If your reports use resources such birt libraries, java script files, images etc., the Birt Engine will look for these resources in a 'resource path'. This path is also set up in portlet.xml file:





Most of the time reports developers are confused with this property because they don't explicitely define a resource-path in their Eclipse Birt designer , and include resources in the same folders as reports. Though mixing resources and reports is probably not a good practice. In eclipse birt designer, you should use a custom resource path to understand how it works, and organize files properly within :

Note that if you don't customize the resource path of a birt designer, the default value is your Eclipse workspace.

You must reproduce the whole resource folders hierarchy exactly as it is in Eclipse Birt designer. For example if you created three sub-folders under birt designer resource-path such:

  • <Birt designer resource path>/commons
  • <Birt designer resource path>/marketing
  • <Birt designer resource path>/financial

and included resources in these folders, you must do the same in the resource path of Visioneo reportlet. So by default:

  • <reportlet root>/birt/resources/commons
  • <reportlet root>/birt/resources/marketing
  • <reportlet root>/birt/resources/financial

Organize sub-folders

  • You can create as many subfolders as needed under the report root folder
  • It is recommended to avoid spaces in folder names (some application servers such Websphere wouldn't like this).
  • In the ajax report browser, both reports and sub-folders are sorted by their file name.
  • A sub-folder is displayed only if it contains  at least one birt report, or recursively if one of its sub-folders contains at least one birt report.
  • A subfolder is displayed only if the current user has access permissions (Professional Edition) on at least one report within
  • For versions older than 2.1: if you create sub-folders when the reportlet is already started, you must refresh your list cache to see new sub-folders in the reportlet browser.
Please note with Visioneo portlet, it is risk free to move reports from a sub-folder to another, even if you defined drill-through hyperlinks between reports! The reportlet engine is dynamically building all paths, and will find your reports wherever they are in the folder hierarchy.

If you want to set localized names for sub-folders, you can use the reportlet localization properties files. It is located in <reportlet root>/classes/org/visioneo/portlet/localization .

For each sub-folder, the reportlet is looking for an entry  in these properties files, with the key tree.folder.<sub-folder name> .  If an entry is found it is used in the ajax report browser, else the folder name is used. For example, if you create a sub-folder 'marketing', you can localize this folder name with the key: .

Alternative for Community Edition: use a WEBDAV folder

Some portals such Liferay provide a WEBDAV service. This allows to connect a Network drive with a portal folder. Thus we can manage our reports through the portal interface even with Visioneo Community Edition , taking advantage of awesome features such versioning, comments,  rollback etc.

To achieve this:

  • Create a new portal folder, add your reports and subfolders within
  • Get the WEBDAV URL of this folder from your portal interface. Check your portal documentation
  • Create a Network drive through the Operating System of your server, with this URL and credentials. For example in "Windows Explorer", just right click on "Network"->Connect a network drive
  • In portlet.xml file of the reportlet application, setup the report path with an absolute path, and use our new network drive

Done! You can now add, move, edit reports from your portal interface!

Drawbacks and limits of using a WEBDAV folder

Webdav is a powerful and simple approach, though there are significant limits and drawbacks:

  • You need to make sure your network drive is still valid when the server is physically restarted:  when the operating system restarts it will try to map the network  drive whereas the portal WEBDAV service is not yet available.
  • Reports access permissions of end-users can't be checked, because we need to specify a unique portal user in the webdav connection
  • For the same reason
    • we can't define team permissions
    • we can't know which user has released a new version of a report-design
  • Draft mode is not supported through Webdav: Visioneo portlet CE always display the latest approved version
  • Lower performances
This is why Visioneo PE natively supports portal services to handle a report-design repository, allowing to take advantage of the powerfulness of the Document Management System without these limitations!

Report properties

Although it is facultative, you shoud fill theses BIRT properties in your reports, because Visioneo browser takes advantage of them by showing a summary when we want to select a report:

  • Author
  • Display name
  • Description
  • Thumbnail

If it is required in your projet, display names and desciptions can be localized through the Eclipse Birt designer.

Concerning the thumbnail, please use a png format with  200px width.

Blank default report

From version 2.2 there is no default report selected when we drag a new report portlet from the control panel onto a page.

Once a report is selected through "preferences" mode of a portlet window, it becomes the default report of this window and you will never see that message anymore. The content of the blank report can be controlled with one of the following:

  • Customize the text in <visioneo root>/WEB-INF/classes/org/visioneo/localization/
  • Customize the JSP page <visioneo root>/WEB-INF/jsp/visioneoPortlet_noreport.jsp
  • Set a default report as explained in next section.

Select a default report (facultative)

Once your reports are published, you can select which default report is displayed when a reportlet is dragged on a portal page. This feature is controlled by a portlet preference in portlet.xml:

<preference> <name>__report</name> <value>welcome</value> </preference>

The value is the report file name but without .rptdesign extension, i.e. "welcome" for "welcome.rptdesign". It is important to notice that you don't have to worry if this report is in a subfolder of the report path: Visioneo engine scans all subfolders and takes care of this kind of consideration for you. As a consequence, the report name (file name) is used as a "primary key" and should be unique across all subfolders.

You can reorganize the subfolders and move reports dynamically, all  portlet windows will still work as long as the file name of BIRT reports is kept unchanged!

Development context: use Visioneo as report viewer ( facultative )

If you have a portal and Visioneo locally installed on a development desktop, you might want to set the birt repository as "absolute" even with a Professional Edition and set paths referring to the eclipse birt project, for instance:





Thus any change of report-designs in Eclipse is immediately taken into consideration in Visioneo, without any publishment step.

Tags: admin developers
Average (0 Votes)
Tomcat temporary folder issues Overview From v7, Tomcat has a new behavior which might cause many troubles when we are not aware of: when it loads an application, it is cloning it in a temporary folder. Most of the time this folder is under /temp Until an application is restarted, tomcat serves all resources (javascript, css, jsp, .rptdesign, etc) from this folder, not the real orginal one. It is especially frustrating when we want to update reports: although all visioneo caches...
Most Recent
21 October 2016
11 April 2016
08 February 2016
06 November 2015
28 October 2015
26 October 2015
14 October 2015
08 October 2015
10 September 2015
07 April 2015