Tags Navigation Tags Navigation

Knowledge Base (Display) Knowledge Base (Display)

How to use portal & session attributes within BIRT reports

How to use portal & session attributes within BIRT reports

1 - Overview

Portal attributes such user name, ID, email, company etc. can be exploited in BIRT reports, to be displayed within the body or used as a filter in a dataset query. See the relevant live demo for a quick overview.

User attribute vs Session attribute

The article is mainly focused on portal user attributes. Session attributes must be handled in a similar manner, the only difference is the expression used to retrieve values. This point is addressed in the last paragraph.

Standardised attributes vs Extended attributes

Visioneo offers two ways to retrieve portal user attributes from reports:

  • Standardised attributes (JSR 286 portlet specifications)
  • Extended portal objects (with Liferay and Gatein portals only)

If you make use of a Liferay portal or a portal based on Gatein you should make use of extended portal objects. Extended objects are specific to each portal but they are easier to exploit and offer more possibilities. See the relevant section at the bottom of this article.

Standardised user attributes

A standardised portlet attribute (in this example, " user.name.family ") can be retrieved in a BIRT report with an expression such:


This method should work whatever the portal is (currently tested with Gatein, Liferay, JBoss EPP, eXo). Here "user.name.family" is a standardised attribute, published by portals which support the portlet specification. To be exposed to BIRT reports, it must be declared in the reportlet portlet.xml file like this:

<user-attribute> <description>Family Name</description> <name>user.name.family</name> </user-attribute>

By default three user attributes are already declared, among dozens available. You should only declare attributes actually used by your reports.

<user-attribute> <description>Given Name</description> <name>user.name.given</name> </user-attribute>
<user-attribute> <description>Family Name</description> <name>user.name.family</name> </user-attribute>
<user-attribute> <description>User department</description> <name>user.department</name> </user-attribute>

You will find more explanations for these standard atttributes, and the list supported by Liferay, on Raymond Augé's Blog

Custom user attributes

In addition to standard attributes, some portals allow to create and expose custom user attributes within their GUI. For example it is possibe to create and fill custom fields in Liferay, in this example 'demo.office':

A specific hook has been developed for Liferay, these attributes can be retrieved in a similar manner as standard attributes. So if you create a custom field in Liferay named "demo.office", in your BIRT report script (only primitive Liferay types are supported: simple integer, text, etc.):

In Liferay, don't forget to set "view" permission for custom fields to your community users!
We should use a safe prefix to name these fields, in order to avoid any confusion with standard attributes. Unlike standard attributes, it is not required to set up custom fields in portlet.xml, nor in any other descriptor file: as soon as we create a new custom field in the portal, it is embedded by the reportlet.
To avoid headaches when developing your reports, all exposed attributes are displayed in the reportlet admin mode, at the bottom of  "Security" tab:

Default value when a user attribute is not found or empty

To keep BIRT scripts simple, the reportlet API allows to specify a default value to return when a user attribute is not found or empty. Thus we don't have to write each time in scripts stuff like "if value returned is null or empty then...etc":

reportContext.getAppContext().get("visioneo.portal.userinfo").get("user.name.family", "Unknown family name");

reportContext.getAppContext().get("visioneo.portal.userinfo").get("demo.office", -1);

If an attribute is used as data filter (in the query of a BIRT dataset), this default value should make sense in the query. For example in the demo report, -1 is a special value indicating all data must be returned.

Of course, if you plan to use a portal attribute as security filter, your query should not return any data when it gets the default value of this attribute.

Keep compatibility with Eclipse designer

This "visioneo.portal.userinfo" object is of course only defined in a reportlet context, and will trigger an exception in Eclipe Birt designer. So when this is invoked in a BIRT script, it is necessary to check if it is null, or catch any exception, and then return a default value. To achieve this, the safest way is to use an expression like this:

reportContext.getAppContext().get("visioneo.portal.userinfo").get("demo.office", -1);

This expression returns -1 if an exception occurs in the "try" block, so that it can be invoked in any context.

For advanced reports developers , have a look on the expression used by the demo report, this is more complex because it is designed to retrieve the "office" parameter from different possible attributes. Indeed, "demo.office" attribute is a custom field and can only be created with Liferay, for other portals the demo report tries to use a standard "user.department" attribute. For example in Gatein this department can be filled in the user profile:

So the script works like this:

  • return the "demo.office" attribute if exposed,
  • else  return the "user.departement" if  exposed
  • else return -1
var office=reportContext.getAppContext().get("visioneo.portal.userinfo").get("demo.office", -1);
(office==-1) ? reportContext.getAppContext().get("visioneo.portal.userinfo").get("user.department", -1) : office;

Where using portal attributes in a BIRT report?

We have learned in this article how to retrieve user attributes from portals. Very well, but where are we going to set them in BIRT reports?

Portal attributes should be invoked in only one place: in the "default value" expression of report parameters. Here is the guidance: if you need to use, for instance, 3 portal attributes in a report,

  • declare 3 report parameters (hidden or not),
  • initialize each one with the correct portal attribute,
  • use these parameters in any place in your reports
This is the most important point to remember: portal attributes should ONLY be used through report parameters!

Please note it doesn't limit in any way what you can do with these user data: it is just required to put them in report parameters first, and then use these parameters instead in the report. Why this step?

  • Thus it works harmoniously with the cache engine, which is based on report parameters
  • Report parameters represent an abstract layer, allowing to easily migrate your reports from a "report container" to another. For example, if you need to migrate your BIRT reports from Visioneo to Pentaho or iServer, all you have to do is to change the report parameters initialization. You should always follow this rule, whatever your reporting software is.

How to initialize a report parameter with a user attribute

  • Edit this parameter in Eclipse designer,
  • Set the "default value" field to "javascript syntax", as in the example below
  • In the expression builder, enter an expression such described above in the article.

Secured & hidden properties

Usually when we plug a report parameter to a portal attribute it is not intended to be changed by end users. Therefore it is probably a good practice to set it as hidden and .

Beyond security considerations it will also prevent these parameter values to be stored in portlet preferences, if we make use of parameters dialog in edit mode.

Using session attributes instead of user attributes

If we need to use a session attribute in a BIRT report, we should follow exactly the same rule as described for user attributes:

  • Create a new report parameter
  • Set an expression getting the session attribute in "default value" property of this parameter (see example below)
  • Wrap the expression in a try..catch block to return a value whatever the context is

Retrieve an attribute from the PORTLET_SCOPE


Retrieve an attribute from the APPLICATION_SCOPE


Extended portal informations

In major supported portals (Liferay, Gatein, eXo, JBoss EPP), the context of BIRT reports is extended with specific objects.

To use these objects we should follow exactly the same rules as described for standardised user attributes in previous sections:

  • Create a new report parameter
  • Set an expression in "default value" property of this parameter (see example below)
  • Wrap the expression in a try..catch block to keep compatibility in Eclipse designer
  • Set this parameter as "hidden" and / or  "secured".

Portals based on Liferay

ThemeDisplay object is  available through the key " liferay.themedisplay ", thus we can access to many informations related to the current user. This should be your favorite way to access to user informations required by reports. For example, in the default value script of a report parameter, we can get the email address of the connected user:


Another example showing how we get the company name of a connected user:






We can also retrieve device informations such:


Portals based on Gatein

object is available through the key " exoplatform.user ". For example, in the default value script of a report parameter, we can get the email address of the current user like this:


Average (0 Votes)
Secured parameters This article describes how to secure a birt report parameter Security parameters In visioneo reportlet, a "security parameter" is a BIRT report parameter used in a dataset query, and designed to restrict data permissions depending on a portal user attribute or a session attribute. For example in the demo report "Portal attributes", user office is designed to be a security parameter. Parameter's value is set by the portal on server side, and we don't want it to be modified...
Most Recent
15 August 2014
09 August 2014
26 July 2014
19 July 2014
01 July 2014
29 June 2014
11 June 2014
10 June 2014
09 June 2014
19 May 2014