Nuxeo - BIRT Integration

The Nuxeo - BIRT Integration package leverages the reporting features of Eclipse BIRT, enabling users to create reports on the application's activity, directly from the Nuxeo Platform.

When the Nuxeo - BIRT Integration package is installed on the Nuxeo Platform, users can create and generate reports, defining what statistics they want to compute. To help them, the application's administrators create report models, that already set up some parameters. The report models are based on BIRT report files that have been imported in the Nuxeo Platform. All the parameters defined in the BIRT report file are extracted and administrators can edit them in the Nuxeo Platform using the edit form of the Report Model Then, users can create reports in the Platform, based on this model. Reports are bound to the document context, allowing to automatically get and use information on the report (like where the report is in the application's tree, etc).

Before You Start / Prerequisites

The whole process to make reports available and use them takes places in two places:

• in BIRT designer, to prepare the models,
• in Nuxeo Platform, where administrators can create report models and users can create and generate reports.

As a consequence, you need to install and set up:

• the Nuxeo Platform (the Document Management module is required),
• BIRT designer (version 4.2),
• the Nuxeo - BIRT Integration package.

Nuxeo Platform

The Nuxeo - BIRT Integration package requires the Document Management module of the Nuxeo Platform. The Nuxeo Platform must run with a background database (vs the embedded one). You can see and edit the database settings from the Admin Center.

BIRT Designer

Of course, the administrators who will prepare report models need to have the BIRT designer installed to be able to create BIRT report files and use them in the Nuxeo Platform to create the models. However, it doesn't need to be installed on the same computer as the Platform. The BIRT engine required to generate reports from the Nuxeo Platform is included in the Nuxeo - BIRT Integration package.

You also need the database driver for being able to let the BIRT Designer with your Nuxeo Platform database.

Nuxeo - BIRT Integration Package

The Nuxeo - BIRT Integration package is available from the Nuxeo Marketplace. See the Nuxeo - BIRT Integration administration documentation.

Working with BIRT Reports

This section is about what needs to be changed in the BIRT configuration to have report files that can be imported successfully in the Nuxeo Platform. For information about how to create reports in BIRT and its features, you can report to the tutorials, FAQ and examples from the Eclipse BIRT website.

Setting Up the BIRT Report Data Sources

To automatically use Nuxeo data sources, the data sources you define in your BIRT report should follow a name convention. You have two possibilities:

• nuxeo: in the Platform, the JDBC URL of the data source will be replaced by the one from the context document where you've created your BIRT Report document instance.
• nuxeo-repositoryName: in the Nuxeo Platform, the JDBC URL of the data source will be replaced by the JDBC URL of the data source related to the 'repositoryName'. This name convention is the one to be used in a multi-repository configuration.

Creating a Report Parameter

To create a report parameter:

1. Define the docType parameter as a Report parameter:
   ×
   
2. Define the docType parameter as a parameter of your Dataset, link it to the report parameter:
   ×
   
3. Use the docType parameter in the query of your Dataset:
   ×
   

Sample BIRT Reports

You will find attached a set of sample reports to get you started: .

Working with Reports Models and Reports

Report Models

Reports models can be created and edited by the Nuxeo Platform's administrators, from the Admin Center.

The actions available on a report model are:

• edition,
• access rights management.

Creating a Report Model

Report models are managed (i.e. created, edited, deleted) from the Admin Center. As a consequence, only the administrators of the Nuxeo application can create new report models. After you installed the Nuxeo - BIRT Integration package, a new section is available in the Admin Center, called Reporting.

To create a report model:

1. Click on the Create Model button.
2. Fill in the form (see below for more information on the different fields available).
   ×
   
3. Click Save. The report is saved and its Summary tab is displayed. The report model is accessible only by administrators for now. You need to make it available to non-administrator users so that they can create reports based on it.

Editing a Report Model

When you edit a report model, you can change all the information you filled in on the creation form, but you can also set a parameter. If you set a parameter on the model, it will be set up by default on the report based on the model and users won't be available to change it. See the parameters section below.

Making a Report Model Available

By default, report models can be accessed by administrators only. So, they need to give access rights on the report models to non-administrator users. The access rights available on report models are the same as in workspaces. The access rights on report models are managed the same way as on any other space. You can report to the Access rights management page for detailed steps.

Reports

Reports are available in workspaces and folders. They can be created by users with Write right, who choose which model to use and have the possibility to define some parameters as frozen. Users with Read right can generate the report and see the updated computed results.

Creating a New Report

A BIRT report is created as any other document in the Nuxeo Platform.

1. In the Content tab of the workspace, click on the New button.
2. On the window Available document types, click on BIRT Report.
   ×
   
3. Fill in the report's creation form.

4. Click on the Create button. The Preview tab of the report is displayed. You can now either:

   • generate the report from the Preview tab,
   • edit it to set up some parameters for users who will generate the reports,
   • manage the access to the report.

Report properties

Editing a Report

The steps to edit a report are the same as for a default document of the Document Management module. When you edit a report, you can modify its properties and you can set up some parameters. The parameters you set in the Edit tab are not displayed on the Preview tab anymore. Their value is set for all users for the report generation.

Managing Access to the Report

Unlike for notes and files (which are the most common default Nuxeo documents), users can manage the access to the BIRT reports. The report access rights are inherited from the workspace or folder it's created in. You can grant or deny access rights on the report just like on a workspace or a section.

Generating a Report

Generating a report means filling in the available parameters on the report's Preview tab with values meeting your criteria and getting the results. By default, the report is generated in HTML in the Preview tab of the report. However, you can also generate the report in PDF format from this URL: http://NUXEO_SERVER/nuxeo/site/reports/REPORT_KEY/pdf. The REPORT_KEY can be found in the Summary tab of the report.

If no parameter is left to be filled in by the user, the report is generated when you click on it to consult it. For more information about the parameters, see the parameter section.

Parameters

Reports are generally based on parameters whose values can be set by users so as to computer the report. Parameters values can be defined at three places:

• on the report model Edit tab;
• on the report Edit tab: Only the parameters which are not set into the report model can be set here;
• on the report Preview tab: Only the parameters that are not set on the model or the report itself can be set here.
  ×
  

Reports are bound to the document context, which means that there is a set of parameters that will be automatically set from the document context if they are defined in the BIRT report. Those parameters will be filled by the Nuxeo instance when generating a report, and so you can use them when working on your BIRT report:

• ${userName}: the username of the current user asking for the BIRT Report;
• ${docType}: the document type of the BIRT Report (BirtReport);
• ${currentPath}: the path of the BIRT Report document in the Nuxeo Platform;
• ${currentRepository}: the repository name where the report is stored;
• ${currentSuperSpacePath}: the path of the first parent of the report that is a super space (ie that has the superspace facet). By default, workspaces and domains are super spaces.
• ${currentSuperSpaceId}:the ID of the first parent of the report that is a super space (ie that has the superspace facet). By default, workspaces and domains are super spaces.
• ${currentWorkspacePath}: the path of the first parent workspace of the BIRT report;
• ${currentWorkspaceId}: the ID of the workspace the report is in;
• ${currentDomainPath}: the path of the first parent Domain of the report;
• ${currentDomainId}: the ID of the domain the report is in.