Knowledge Base Article Knowledge Base Article

Getting started » Install on Gatein

Installation steps on Gatein


Gatein is the original portal on wich the reportlet has been developed, therefore all features are perfectly supported. It has a great portlet container,  and the general portal look is awesome.



0-Reportlet context name

  • Gatein uses the reportet .war file name to set the application context name. Therefore, you should rename the downloaded .war file to remove the version number. For example, if you have downloaded visioneo-reportlet-1.2.0.quickstart.war, rename it to visioneo-reportlet.war. If you don't, Gatein installs each version as a distinct portlet application , and you will have to modify your portal pages each time you upgrade your reportlet version. 
  • Some application servers such JBoss 7 allow to set up the deployment name when you install the reportlet

1-Install the reportlet on the application server

Unlike for Liferay, you must install the reportlet on the application server first. For instance, on tomcat run the tomcat manager, select the .war file and click deploy.

EDIT: from visioneo v1.2, the quickstart bundle is larger than the default size limit of Tomcat manager (50Mb). To install it without the manager, just put your .WAR downloaded file under <tomcat root>/webapp so that Tomcat deploys it automatically. Alternatively we can also edit <tomcat root>/webapp/manager/web.xml and increase this size limit:

      <!-- 60MB max -->


The deployment lasts from 5 to 20 seconds depending on your processor, and you should be able to see the progress log messages in the application server window:

2-Register Visione reportlet in the gatein portal

You must be logged as an admin user, and then click on groups->Administration->Application registry.

Click on the Import application option, and the reportlet will be automatically registered:


3- Add the portlet on your pages

Choose a portal page or add a new one, in the page editor drag & drop a portlet window from the portlet list to your page:


Click on the portlet editor to configure your portlet window:

Save the page, the default report will run automatically. The first run is always a bit longer.

Reportlet maximization

Note most of the time the Gatein bundles are configured in a 1024 width resolution, whereas the default maximized width for the reportlet is 1100. To avoid nasty effects when you maximize a reportlet, you must  adjust the maximizedWidth parameter in the portlet.xml file. For example a width of 900px: 

<init-param> <name>maximizedWidth</name> <value>900</value> </init-param>

Restart your application server, and test if this value meets your needs.

Defining security roles

In the default Gatein bundles,  "member", "manager", and "validator" are membership types, when "/platform/administrators" and "/platform/users" are groups. It's easy to be confused when you try to map your security roles in the reportlet.

Gatein extracts portlet roles (and more generally j2ee roles) from groups, not from membership types.

More informations can be found on the Gatein wiki.  So, for instance to link the adminstrator role and the standard user role, in the portlet.xml file:











For each entry, "role-name" is the internal role used by the reportlet, when "role-link" is the Gatein group name as you can see it in the portal Control Panel.

By default, only groups created under /platform are taken in consideration for J2EE roles. This behaviour can be controlled with a Gatein parameter:


To start up, the most important role to check is "administrator". You can see in the reportlet admin dialog wich roles are correctly mapped, and if the "useSecurityRoles" option is enabled. From reportlet RC1.0 release, all Gatein roles should be correctly mapped by default.


Edit mode permissions

By default, Gatein allows any authenticated user to edit the portlet preferences, and does not implement a user permissions feature to access the portlet 'Edit mode'. Since on a site page, the preferences are shared by all users it is obviously a problem. There are two options:

  • When you create a reportlet window, set up the options so that the portlet modes are not displayed. The 'Edit mode' can be accessed only by users allowed to edit the page, wich is a perfect behaviour. The drawback is, your users won't be able to access the 'help mode' neither.
  • Modify the default Gatein template so that the 'Edit mode' is only displayed to specific user roles. The 'Edit mode' can still be accessed by users allowed to edit the page, and this time the 'Help mode' remains available. This template is located at: <GateIn home>/webapps/portal/groovy/portal/webui/application/UIPortlet.gtmpl

For example, in this template locate the line:

if(mode.equals("edit") && rcontext.getRemoteUser()==null) continue; 

and replace it by:

if(mode.equals("edit") && !rcontext.isUserInRole("administrators")) continue;

Install on JBoss7

The reportlet can be installed on Gatein-JBoss 7 since the v0.9.4.  

  • To use visioneo reportlet with the default Gatein JBoss 7 Bundle, as long as the issue GTNPORTAL-2466 has not been resolved, you must apply this workaround:

After installing JBoss7 & Gatein, modify this file : jboss-as-7.1.0.Final/gatein/modules/org/gatein/lib/main/module.xml

<system export="true">


    <path name="sun/misc"/>


    <!-- Add this line -->

    <path name="com/sun/xml/internal/stream"/>





Use the JBoss console admin interface to deploy the reportlet (typically: url=http://localhost:8080    user=root password=admin)


Click add content, and select the downloaded war file


Click on 'enable' to start the reportlet

Tags: install
Average (0 Votes)
Most Recent
Install on Jahia 26 April 2015
Getting started 01 April 2015