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.
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:
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:
2. Use the RP_TENANTID parameter in the query of your Data Set:
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).
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 information you filled in the creation form, but not the report's name.
| 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.