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.
You will find more explanations for these standard atttributes, and the list supported by Liferay, on Raymond Augé's Blog
Custom user attributes
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.):
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");
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:
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
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
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,
- 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:
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