Reporting Server/Reporting Functional Integration
The Openbravo backoffice is integrated with the Jasper Reports Server in various ways: transparent automatic login using single-sign-on logic, providing access to the reports server without relogin, show reports within the Openbravo backoffice and report bursting. These integration topics are described in detail in this document.
See also this howto for step-by-step information on how to access reports from the backoffice/webpos.
Integration Module
The functionalities described in this document are provided by the org.openbravo.reporting.integration module. We are delivering this module as part of the 20Q1 release. This module has limited dependency requirements, use with previous versions of Openbravo could be possible and will be tried on an as-need basis.
For WebPOS to reporting integration the following module also should be installed within Openbravo:
Openbravo Reporting Configuration
The Openbravo server needs to know how to access the required Jasper Server installation. The Jasper server information is configured in the 'Reporting Configuration' window. Note, there can be maximum one reporting configuration record defined in the system.
- Report Organization Key: the organization ID as defined in the Jasper Reports server for the organization.
- URL: the main url of the Jasper server, including the context (jasperserver-pro)
- Shared Key: the shared key used to support single sign on
- Webservice User: the jasper server user which is used to do webservice calls to the Jasper Server from Openbravo. Is often a Jasper admin.
- Webservice Password: the password within Jasper for the webservice user.
- Webservice Superuser: the super user login, should be normally 'superuser'
- Webservice Superuser Password: the password of the super user, use a strong password
- Base Reports Folder: the reports listing window (see below for a description) searches for reports within Jasper Server, setting a jasper repository folder path in this field is necessary to ensure users can only retrieve reports and no other system oriented information. Note any value other than / is resolved within the organization root folder. See more on this in the Jasper Serer Repository Folder Structure.
The reporting configuration can be tested by clicking the test configuration in the top right.
Note: we only allow one reporting configuration record per installation.
Automatic Login, Organizational Filtering, Automatic User Creation
Openbravo by default supports automatic login from the Openbravo backoffice to the reports server. So a user who is logged into the backoffice does not need to login again when accessing the reports server through links in the backoffice.
When the user retrieves reports or navigates to the reporting server from the backoffice, then Openbravo will first send a login request to the reports server. The reports server will create the user (if he/she does not yet have a reports server user) and authenticate the user. On successful authentication the user is authorized to access reports and the reports server repository.
In this login action Openbravo also passes the allowed organizations of the user. This information is used within the reports server to accomplish organizational data filtering. So that a user can only see data from stores to which he/she has access.
The login action also uses roles and role mapping so that the user gets the right authorizations within the reports server. This is discussed in more detail in the next sections.
Preference to see data of all organizations
By default the reporting integration will make sure that the user can only see data of the organizations to which he/she has access. With a preference it is possible to override this behavior and designate specific users or roles to see data of all organizations. See the preference: 'Reporting Integration - Show data of all Organizations'. Set this preference to Y for relevant users or roles.
Preference to enable access to reports in webpos
If the integration.retail module is installed it is possible to access reports also from Webpos. There is a preference to control who has access to the report functionalit, i.e. who will see the Reports/KPI menu option in WebPOS.
By default the reporting retail integration will enable it for all webpos users, but you can override it for specific users to prevent this.
Role handling and Role mapping
The reports server has a role definition which can be used to assign view and execute permissions by role.
Users will already have roles assigned to them within Openbravo. Therefore it makes sense to map Openbravo roles to Reporting Roles. This mapping and creation of reporting roles is done from the role mapping window.
When logging in from Openbravo by default a user will get the reports server ROLE_USER. This in addition to the role set in the role mapping window.
To get to a complete permission and role setup follow these steps:
- think of how you want to organize the reports in folders in the jasper repository to manage access to the reports.
- think of the roles you need for the envisioned folder and permission setup in the reporting server. Do not create these roles in the reporting server. That's done from the Openbravo backoffice through the Create Role button in the role mapping window.
- for each of the envisioned roles, define one or more role mappings within the Reporting Role Mapping window, choose sensible role names and select the corresponding Openbravo role. The reporting role does not yet have to exist in the reporting server, creation is done in the next step. One reporting role can be mapped to different Openbravo roles.
- create the role in the reporting server: when creating a role mapping record then also create the role in the reporting server through the Create Role button in the role mapping window. So do not create roles directly in the reporting server, this will not work as these are so-called internal roles which can not be used for single-sign-on/automatic login.
- now go to the folders in the repository and right click on the folder to set the correct permission for each role. See the screenshot above.
For more information on the role setting in the folder structure, see the next section.
Note: role inheritance is supported in this mapping. So you can define the mapping for a high level generic Openbravo role (e.g. Sales Rep Role) while the Openbravo users are linked to/using a specific role (e.g. Sales Rep Store 1 Role).
Reporting Repository Folder Structure - Guide Lines - Jasper Access Definition
The mapped roles can be used to define access of different groups of users to different sets of reports. For example you can place all the sales reports in a specific folder and all warehouse reports in another folder. Then by giving the sales role access to the sales reports folder and the warehouse role only access to the warehouse reports folder, you can make different report sets visible to different users. For more information on role setting by repository folder, see the next section.
The following guidelines should be followed when setting up the folder structure in the reporting server repository:
- within the base reports folder (see field in the reporting configuration in the backoffice), structure folders according to role and access to reports. So reports which are accessed by the same type of users, with the same roles, should be placed together in one folder.
- the ROLE_USER should have read-only access to all folders, except for the base reports folder (and its subfolders) defined in the reporting configuration. This ensures that all users can make use low level system resources.
- in the base reports folder, set the ROLE_USER to no-access (let it be inherited by all the subfolders) and then control specific read-only access by role for each of the subfolders.
By following the above setup new roles/users will not encounter unexpected authorization issues.
When single sign on is configured it is possible to navigate directly from the Openbravo backoffice to the Reports Server.
Report Listing
It is possible to directly show/open reports within the Openbravo backoffice. For this visit the 'Reports Server Report Listing' window. It will search for all the reports within the base reports folder (see the Reporting Configuration) and display them. Reports are only shown if the user has access to the report based on the current role of the user and the role mapping (see above section on role mapping).
To open a report, select a record and then click the 'Open Report' button.
Report Bursting
Jasper Reports Server allows you to schedule reports to be send by email or generated on designated file locations. The reports bursting functionality of Openbravo allows you to use this functionality for a large set of users. The main features of our report bursting functionality:
- report bursting is operated from the Openbravo backoffice
- it uses the Openbravo role and user definitions to assign schedules to users.
- the receivers of reports (by email) do not have to login to Jasper or have a user defined within Jasper.
- each user can receive a report with his/her specific data, personalized content based on the properties of the receiving user.
Report Bursting Main Steps
The main steps in the report definition are:
- define a template report schedule within Jasper
- define a report bursting definition within Openbravo backoffice referring to the template schedule
- select the target users for the report in the report burst definition
- generate reports jobs within Jasper for each of the report jobs
The report schedules can easily be regenerated from the Openbravo backoffice when new users have been introduced or roles change.
Create a template job within Jasper/Openbravo Reports Server
The first step is to create a report schedule in Jasper. This report schedule is the template for the report schedule for each individual user. Set the timing, the type of output (pdf, xls etc.) and the email subject and body text. After saving the template schedule check the schedule id. Note: the template report job does not have to be enabled.
Note: one not-yet-supported feature is to generate the report on different file locations for different users. In this release the main idea is to send reports by email.
Create Report Bursting Definition in Openbravo Backoffice
The report bursting definition in the Openbravo backoffice has several parts:
- the name, description, user include/exclude rules, the link to the Jasper report template
- the included roles (visible depending on the include/exclude rule)
- the included or excluded users
- the report variables
- a list of current reports schedules for the report bursting definition
Each of these parts is discussed here.
The Report Bursting Definition Header
The report bursting definition header allows you to specify a name and description and then two additional important fields:
- the id of the template report job, this can be found in the report schedule in Jasper, see the screenshot above, the id is shown in the black box
- the in- or exclude rule for users. Two values are possible:
- Roles excluding specific users: if this is chosen the roles tab is shown. The users which have these roles are included in this report burst, except the explicitly listed users in the Report Burst Users tab. The role tab/definition supports role inheritance, so you can specify a higher level role which will include all its (grand)child roles (i.e. their users).
- Specific users: with this setting only the specifically listed users in the user tab will get a report schedule generated.
The Report Bursting Variables
A main feature of report bursting is that each receiver of a report will get a report with his/her own personalized content. For example, a sales rep will only get the sales data for the tickets which he/she created, a store manager will only get a report for his/her store. To accomplish this the assumption is that the report has parameters to customize the content. For example as shown below.
The idea is that in the report bursting definition you can generate specific values for these parameters based on the user which will receive the report. The parameters are generated/set using the Report Bursting Variables tab which links Openbravo user specific variables to report parameters.
The variable name should correspond to the technical name of the parameter in Jasper. To find out the name you can just try one and press save, the error message will show you the available parameter names (see below). Based on the report parameters of your report as you defined them in Jasper you should be able to see what name correspond to what parameter.
Within the Jasper report template check also what value Jasper uses for the parameter, this depends on the report definition. This can be for example the name or the search key for a record.
With this knowledge you can then select which value of the user can be used to set the relevant parameter in the report schedule. You can use a so-called property path through the entity model starting from the user. The entity model is described here. The format of the parameter is always: '${user.[PROPERTY_PATH]}'. See the examples in the screenshot above.
Updating Report Schedules
Updating the report schedules is done by clicking the 'Update Report Schedules' button in the top. This action will create new report jobs for new users and remove report jobs of non-included users.
Note: check the paragraph, discussing a common error, further below.
To regenerate all report jobs, first remove them with the remove report jobs and then regenerate.
Remove and update report jobs are comparatively light actions so you can do them several times without issues.
Generated jobs will be prefixed with the template job name and suffixed with the user name.
The resulting report jobs within Jasper:
When you would go into the jasper report job you will find that several parameters are now set to the user specific values making the content personalized for the receiving user.
A possible error message when generating schedules is shown below. This error message occurs when the start date of the interval definition of the template job is in the past. Login into the jasper reports server to update the template schedule start date on the schedule tab.
