Custom Reports

The Custom Reports package leverages the reporting features of Eclipse BIRT, enabling users to create reports on the application's activity, directly from LogicalDOC. Users can create and generate reports, defining what statistics they want to compute. The report models are based on BIRT report files that have been imported in LogicalDOC. All the parameters defined in the BIRT report file are extracted and asked to the user that executes the report itself.
The execution of a report produces a plain document in a given folder, so normal users can read it depending on the security policies.

Before You Start / Prerequisites

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

  • in BIRT designer, to prepare the models
  • in LogicalDOC, where administrators can create reports

As a consequence, you need to install and set up the BIRT designer

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 LogicalDOC to create the reports. However, it doesn't need to be installed on the same server that hosts LogicalDOC. The BIRT engine required to generate reports at run time from the LogicalDOC application, is already included in the installation.

You also need the database driver for being able to let the BIRT Designer connect to your LogicalDOC database.

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 LogicalDOC. For information about how to create reports in BIRT and its features, you can refer to the tutorials, FAQ and examples from the Eclipse BIRT website.

Setting Up the BIRT Report Data Source

In order to try and debug the report, you need to create a proper data source to connect the BIRT designer to your production database(the one that's currently using LogicalDOC) or to whatever else test database you may set up just for this purpose. In this case, we recommend to import in the test database a real export of the production DB in order to work on plausible data.

LogicalDOC Data Source

In the LogicalDOC application, this data source will be automatically replaced by the database connection you configured at installation time.

Info

In case you directly connect to your production environment, you may take the connection parameters from the configuration file <LDOC_HOME>/conf/context.properties:

  • value of setting jdbc.driver in the context.properties -> Driver Class
  • value of setting jdbc.url in the context.properties -> Database URL
  • value of setting jdbc.username in the context.properties -> User Name
  • value of setting jdbc.password in the context.properties -> Password

Creating a Report Parameter

Define the RP_TENANTID parameter as a Report Parameter:

Report Parameter

Creating a Data Set

1. Define the RP_TENANTID parameter as a parameter of your Dataset, then link it to the report parameter with the same name:

Report Parameter

2. Use the RP_TENANTID parameter in the query of your Data Set:

Data Source Query

Sample BIRT Reports

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


Working with Reports

Reports can be created and edited by the LogicalDOC's administrators of the Default tenant, in Administration → Reports → Custom reports.

Creating a Report

1. Click on the New report button.

2. Fill in the form (see below for more information on the different fields available).

New Reportr

3. Click Save. The report is saved and its Properties tab is displayed.

Field Description
Name Name for this report
Output folder Folder that will receive the output of the report's execution
File Select the BIRT design file (.rptdesign) to use for the report

Editing a Report

When you edit a report, you can change all the informations you filled in the creation form, but not the report's name.

Report Parameter
Field Description
Format The format of the output document: it may be HTML or PDF
Description Optionally you can type a text explaining what the report is about
On update The action to be taken on the target document when the report is executed
Output The link to download the output document
Output folder The folder that will receive the result of the report execution

If you want to upload a different design file, right-click on the report and select Upload a new design.

Info

Only the administrators of the default tenant can create or upload new design files

Executing a report

When you execute a report, it is processed to create the output document in the specified target folder.

1. Right click on the report you want to launch.

2. In the menu, click on Execute. If the report defines some parameters a dialog box appears and you can fill them.

The report is now in execution as shown by the status icon. The report's processing may take time but at the end the new file is stored in the output folder and you can access it by clicking on Download or Preview.