Knowledge Base Article Knowledge Base Article

Getting started » Install on Liferay

Installation steps on Liferay

Liferay is probably the best portlet container available: it is powerful and very flexible for every kind of use.  Visioneo website runs with Liferay 6.2. If you are not sure which portal to install to try the visioneo reportlet, Liferay is a very good choice. 
Visioneo Community Edition is now available from Liferay Marketplace! Install it in one click onto your Liferay Portal! Please visit this article

 

1 - Prerequisites

  • A Liferay 6.x portal  installed
  • Memory "PermSize" of the portal should be at least 384 Mb . Usually Liferay bundles are setup with 256 Mb, which might not be enough when we start a BIRT engine in addition to a portal instance. For example, with a tomcat or a jboss bundle:
    • edit <Tomcat home>/bin/setenv.bat   OR <Jboss home>/bin/standalone.conf.bat
    • replace MaxPermSize=256m  with MaxPermSize=512m

2 - Remove older Visioneo versions

If an older Visioneo version was already installed, we need to remove it first.

  • In Liferay control panel ->  ("Application Manager" with Liferay 6.2, and "Update Manager" with older Liferay versions) -> Remove visioneo reportlet
  • Stop the portal
  • Check in your deployment folder if visioneo-portlet  application has been completely removed  (i.e. in Tomcat: <Tomcat home>/webapps/visioneo-portlet). If this folder still exists, remove it manually. 

3 - Deploy visioneo reportlet

  • Download a "quickstart" bundle from visioneo.org, in the download section. You get a quite large .war file (about 50 Mb): visioneo-portlet-<version>.final.quickstart.war. This file is recognized by Liferay as a portlet plugin.
  • Put this .war file in the deploy folder of Liferay. By default it is <Liferay home>/deploy
  • Start your portal, it will automatically install your new Visioneo reportlet plugin. If the portal was already started, hot deployment will also work, but sometimes we need to restart the portal anyway because the install process is stuck on the step "Deployment will start in a few seconds..."

Alternatively, we can  make use of the private plugin installer from Liferay's Marketplace, and then Panel Control ->Plugin Installation->Install more portlets->upload files. From Liferay 6.2, this plugin is replaced with a native "install" option in the application manager.

After a short time from 10 to 30 seconds you should see in your application server window something like:

  • If your console is stuck on "Deployment will start in a few seconds..." , you  need to stop / restart the portal to complete the install.
  • If you get a "DocumentException" at this point, it is because your server is behind a firewall limiting http streams to Liferay repository: go to step 6 "Adjust the DTD setup" to fix it. 

4 - Check Visioneo in Liferay UI

When the portlet is deployed, we can see in liferay applications 3 new portlets under a "Visioneo" category:

  • Visioneo BIRT reportlet
  • Visioneo external parameter
  • Visioneo refresh button

 

With a Visioneo Community Edition, we only need the first one,  "BIRT reportl".  

"External parameter" and "Refresh" portlets are intended to the Professional Edition, but a limited mode is made available in the Community Edition: we can display external parameters, but they won't refresh reports. Thus you can evaluate how it will be easy to define external parameters in your portal pages if you decide to purchase a professional edition!

5 - Define your first reportlet window

Drag & drop the visioneo reportlet on a portal page. The first actions are always longer to be run, it is normal a BIRT engine needs to be warmed up!  If you didn't change the portlet descriptor (portlet.xml file), by default a "radar" report is displayed. 

Click the portlet options to access the preferences mode, and select your report preferences. For example select the "welcome" report to see all parameter types in action! In some circumstances with Tomcat and Liferay 6.1.2, we might experience JSP troubles on the first UI actions. This can happen only after a fresh install, we just have to refresh the page to fix it once and for all.

With the default configuration, the reportlet window is maximized when this mode is selected. Thus it is more convenient to edit your preferences:

Note that Liferay makes use of specific and very convenient configurations files to extend the portlet.xml descriptor, especially liferay-portlet.xml. This file is located in the reportlet /WEB-INF folder, for instance on tomcat: <Tomcat home>/webapp/VisioneoReportlet/WEB-INF/liferay-portlet.xml

6 - Adjust the DTD setup

IMPORTANT

By default visioneo makes use of the DTD of Liferay 6.2 in <visioneo app root>/WEB-INF/liferay-portlet.xml

<!DOCTYPE liferay-portlet-app PUBLIC "-//Liferay//DTD Portlet Application 6.2.0//EN" "http://www.liferay.com/dtd/liferay-portlet-app_6_2_0.dtd">

With an older Liferay version,  this DTD is transparently requested on the fly if your server has access to the Liferay repository. But with  servers which are not connected to Internet, or with a Firewall limiting http streams we get an Exception and the application won't start.
 
If you make use of Liferay 6.0.x or 6.1.x, even if your visioneo application has correctly started you should fix it manually:
  • Edit <visioneo app root>/WEB-INF/liferay-portlet.xml, and follow instructions mentionned at the beginning of the file:
<!--For liferay versions prior to 6.2:
    1- comment or remove the line referring to DOCTYPE DTD 6.2 
    2- uncomment the line referring to DOCTYPE DTD 6.0
    3- comment or remove lines with (2 lines): <requires-namespaced-parameters>false</requires-namespaced-parameters>
-->

7 - Define the security roles

If you use a default Liferay bundle, the security roles should be already correctly setup in the liferay-portlet.xml file.

Anyway it is very simple. In this file, you will find these entries:

        <role-mapper>  
                    <role-name>manager</role-name>  
                    <role-link>Administrator</role-link>  
        </role-mapper> 
        <role-mapper>  
                    <role-name>administrator</role-name>  
                    <role-link>Administrator</role-link>  
        </role-mapper>   
         <role-mapper>  
                    <role-name>standard</role-name>  
                    <role-link>User</role-link>  
        </role-mapper>      
         <role-mapper>  
                    <role-name>poweruser</role-name>  
                    <role-link>Power User</role-link>  
        </role-mapper>
 

For each entry, "role-name" is the internal role used by the reportlet, when "role-link" is the Liferay role name as you can see it in the portal Control Panel. 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.

 

Liferay 5.x compatibility  

With Liferay 5.  we encounter these issues: 

  •  Visioneo reportlet currently requires a 1.6 or later Java Virtual Machine (JVM), when the Liferay 5.x are bundled by default with a 1.5.x JVM. If you run the reportlet with a 1.5.x JVM, then a 'UnsupportedClassVersionError' is thrown. Check your JVM release before installing the reportlet, and upgrade it if necessary. 
  • It requires a container compatible with servlet 2.5 or later. It is recommended to use a Tomcat 6+ bundle
  • You might have to upgrade jsp-api.jar. This jar is in common libraries.
  • There are css conflicts between the portal and the reportlet. Although most of these css issues have been resolved, since Liferay 5 does not use any css scope selector for jQuery, it is difficult to find a completely satisfactory solution. As you can see on the screen below the theme is a small mix between the Liferay 5 theme and the reportlet theme. You can of course harmonize it by using the jQuery themeroller, and building a theme wich corresponds to your portal. An article has been added in  the knowledge base to explain how to embed your own theme

Tags: install
Average (0 Votes)
Install from Liferay Marketplace How to install Visioneo portlets from the awesome Liferay Marketplace! Third party software Visioneo makes use of these third-party software. Prerequisites This is a large application because it embeds a BIRT runtime. Therefore, it might be necessary to increase memory arguments of your portal before installing it: Java permanent memory Java heap memory Please visit this article first: it details memory arguments and shows how to change the current values...
Most Recent
Install on Jahia 26 April 2015
Getting started 01 April 2015
Install on Gatein 07 February 2014