Knowledge Base (Display) Knowledge Base (Display)

Repository portlet for BIRT

Repository portlet Professional Edition

Visioneo PE includes a configuration portlet allowing to store in Liferay database the location of your report-designs & resources. This location is what we name a "BIRT repository".


A repository configuration consists in two simple input fields:

  • BIRT Report path: this is where we want to publish report-designs (.rptdesign)
  • BIRT Resource path: this is where we want to publish resources requested during reports generation (images, libraries, shared scripts etc.)

These two fields are detailed later in this article.

What is a repository path?

Concretely a path can be:

  • A document & media folder of the portal (also named a 'portal folder' in this documentation)
  • A file system folder (example: C:/birt/report )

The detection is automatic and simple: if we enter an integer the engine considers it is a document & media folder ID, otherwise it tries to match it to a file system folder. In both cases we just need to provide the root folder of the path: subfolders are automatically taken into account.

Of course the favorite path type of a BIRT repository should be a portal folder, because it allows to take advantage of the powerful document management abilities of Liferay: permissions, versioning, draft mode, teamworking, workflow etc. This is why the repository portlet has "Select" buttons offering facilities to choose document & media folders:

Repository portlet vs XML setup

In community edition (CE) we need to edit portlet.xml to setup a such repository, which is painful and has significant limits. The repository portlet of the professional edition has many benefits over a classic configuration xml file:

  • It is of course easier to setup a repository from a portal UI than it is by editing portlet.xml on a server
  • A new repository location is dynamically taken into consideration , without restarting the portal!
  • We are able to define a different repository for each site of the portal !
  • We don't have to juggle with multiple portlet.xml configurations across servers (production, dev, staging,etc.)
  • A "Test" button allows to validate an input before saving. It makes use of the same validation component as the sandboxing report : both file system permissions and portal security manager (PACL) are checked.
  • We don't have to update portlet.xml after a Visioneo upgrade: the setup of this portlet is persistent even if we re-install the application!

Repository levels

Notice in the schema below we can setup a separate BIRT repository for each site and also a default one for each company portal. This is fundamental because repositories are fully segregated using portal security:  for example a user navigating on site B1 has absolutely no way to access reports of site B2 if he is not a member of this site.

In visioneo application there are actually two distinct repository portlets with a similar form:

  • Portal-level repository portlet
  • Site-level repository portlet

Portal-level repository

  • Accessed from control panel -> Configuration -> Repository BIRT

  • Allows to define a default repository for all sites of the portal. Especially useful if we want to share BIRT reports across multiple sites
  • Facultative: we can leave fields blank and directly define a BIRT repository in each site
  • The recommended repository location for this level is a 'document & media' folder of the fictive "Global" site:

Site-level repository

  • This is the recommended configuration level, unless you need to share BIRT reports between many sites
  • Accessed from site configuration -> Repository BIRT
  • Shortcut access: logged as admin, click configuration from the site you want to setup

  • Allows to define a repository for each site of the portal. When it is defined for a site, it overrides the default portal repository
  • Facultative: we can leave fields blank and use the default BIRT repository of the portal
  • The recommended repository location for this level is a 'document & media' folder of the site

BIRT Report path

With a Professional Edition you probably want to take advantage of a portal repository (a 'Document & Media' folder). Just enter a valid folder ID and click "Test" button to check if it is correctly recognized before saving. Even faster, clicking on "Select" button opens a native Liferay selection browser and then we can smoothly select a folder of the current site as report path:

We can create as many subfolders as we need to organize reports under the report path. Pay a special attention to folder permissions: to be able to run a report, a user should have at least "Access" permission. Thus we can restrict access to sensitive reports in specific subfolders, by using a portal-level security robust as a rock !

Eclipse development context

In a development context , we might want to set the birt report path as an absolute file system path referring to an eclipse birt project, for instance:


This way, changes of report-designs in Eclipse are immediately taken into consideration in Visioneo: it can be used as a design viewer without any report publication step! Don't underestimate this feature, it might drastically improve your reports development productivity and make it very pleasant.

Notice a single Liferay development portal can be plugged to as many Eclipse projects as necessary : we simply have to create one Liferay site for each Eclipse project and then setup the BIRT path for each site as explained above. Furthermore don't miss Liferay "User dashboards" are technically considered as sites and therefore they can also have their own BIRT repository!

BIRT resource path

Enter an absolute path referring to resources used by reports (libraries (. rptlibrary ), background images, shared scripts,...). Leave it blank if your reports don't make use of resources, or if you want to use default resources defined at a portal-level.

Future versions

HOT ! Visioneo v3.2: 'BIRT resource path' can be defined as a  'Document & Media' folder too, allowing to publish your libraries, shared scripts, background images etc. through the portal UI !

Clicking this button allows to choose a Document & media folder as a resource path:

  • As for report path above, make sure your reporting users have at least "Access" permission on these document & media folders
  • You can create as many subfolders as you need but they should faithfully mirror the file tree of the underlying BIRT Eclipse project, otherwise resources might not be found when they are requested by a report.
  • For a quickstart: if you put a resource directly under the root folder of a "Document & media" resource path, it will always be found by the engine even if it was created under a subfolder of the Eclipse project!

Logged as admin we just need to click " Content->Document & Media " from a site as shown below to manage BIRT resources of this site!


Caches need to be refreshed when a resource is updated

If you take advantage of Visioneo render & document caches, then these caches should be cleared when a resource has been updated. Otherwise, new generated reports will correctly make use of the latest resource version, but reports already cached won't be updated until the cache expires.

Configuration flexibility

As you will notice if you take advantage of Visioneo PE, the flexibility is really impressive: in a nutshell, everything is possible ! For example these combinations are all valid:

  • Set a 'document & media' folder as report path and a 'File system' folder as resource path, and vice versa.
  • Set 'document & media' folders as repository of a site A, and 'File system' folders as repository of a site B
  • Set a default repository for the portal and:
    • Override the default repository in site A
    • Use the default repository in site B (leave repository fields blank in this site)
  • Set a default repository for the portal and:
    • override the report path in site A
    • use the default resource path of the portal in site A (leave the field blank in this site)
  • Multiple companies: set different default repository locations for portals P1 and portal P2 of a same Liferay server
  • Multiple companies: share a default repository across portal P1 and portal P2 by using a file system folder
  • Etc...

Private repository in user dashboards

This management is so much flexible that it is even possible to define private birt repositories in user dashboards!

In this example, "Joe Bloggs" is an administrator who defined a private BIRT repository in 3 steps:

  1. He created a folder "BIRT Joe Bloggs" in Documents & Media content of his private dashboard site
  2. He uploaded a couple of reports across two subfolders "Joe charts" and "Joe Grids"
  3. In BIRT repository configuration of his dashboard site, he linked BIRT report-path to the folder ID  of "BIRT Joe Bloggs"

That's it! Now in portlet windows of his dashboard, Joe Bloggs can access his private reports:

BIRT reports are very powerful components, and as such each new report should be subject to a quality insurance control . This is why by default only administrators can define a private BIRT repository in their dashboard, and it is highly recommended to keep it that way.

Security Exception with absolute path

If you have setup your repository paths with document & media folders as it is recommended, then you can ignore this section.

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:

In that case, it is necessary to update <visioneo root>/WEB-INF.xml/ and authorize a new entry to security-manager-files-read property. Notice D:/data/birt/-  at the end of the sample below:


Alternatively you can disable the security manager for Visioneo plugin, still in the same file :


Tags: admin
Average (0 Votes)
Most Recent
08 February 2016
06 November 2015
28 October 2015
08 October 2015
01 April 2015
01 April 2015
23 March 2015
23 March 2015
04 March 2015
20 June 2014