How to add reports & subfolders
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:
- 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)
- Copy your report ".rptdesign" in the "Report path". This path is explained later in this article.
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.
Copy new reports into BIRT report path
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 temporary folder issue.
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:
- 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.
If you want to set localized names for sub-folders, you can use the reportlet localization properties files. It is located in
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
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:
- Display name
If it is required in your projet, display names and desciptions can be localized through the Eclipse Birt designer.
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/Language.properties
- 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.
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.
Repository portlet for BIRT 21 October 2016
Birt required / facultative parameters 11 April 2016
Document & rendering caches 08 February 2016
How to define reports access permissions 06 November 2015
How to define a portal repository 28 October 2015
Inter-portlet communication 26 October 2015
Server-side Autocomplete 14 October 2015
How to disable the load fragment window 08 October 2015
How to automatically adjust charts size 10 September 2015
How to hide parameters labels 07 April 2015
Birt reports compatibility 310920 Views
How to build your own theme 288419 Views
How to modify reportlet styles 287075 Views
Inter-portlet communication 276433 Views
Document & rendering caches 273388 Views
Birt required / facultative parameters 263025 Views
Report data volume 262500 Views
Ajax inter-portlet communication 259019 Views
Reports datasources: Stored Procedure vs SQL query 247246 Views
How to automatically adjust charts size 232603 Views