One of the most common needs with a reporting tool is to keep the number of different report templates at a minimum. One way to facilitate template re-use is to make it easy to control certain aspects of a template for different classes of users. To that end, EspressReport allows you to set any number of different security configurations to control both column-level, row-level, and even cell-level appearance depending on which users are viewing the template.
For example, say you have a sales report that shows total sales grouped by sales region. Executives viewing the report need to see the totals as well as the contributions by each region, while individual account managers would only need to see data for their region. The base template for the report would look something like this:
| Sales Report | ||||
|---|---|---|---|---|
| Total Units Sold: 29 Total Sales: $24,449.69 | ||||
| Eastern Region | ||||
| Order # | Quantity | Product | Unit Price | Total Sales |
| 1001 | 2 | Chair | $325.16 | $650.32 |
| 1 | Table | $1,114.18 | $1,114.18 | |
| Order Total: | $1,764.50 | |||
| 1004 | 3 | Table | $1,114.18 | $3,342.54 |
| 2 | Dresser | $1,518.60 | $3,037.20 | |
| Order Total: | $6,379.74 | |||
| Total for Eastern Region: | $8,144.24 | |||
| Midwestern Region | ||||
| Order # | Quantity | Product | Unit Price | Total Sales |
| 1003 | 4 | Chair | $325.16 | $1,300.25 |
| 2 | Table | $1,114.18 | $2,228.36 | |
| 1 | Dresser | $1,518.60 | $1,518.60 | |
| Order Total: | $5,047.21 | |||
| Total for Midwestern Region: | $5,047.21 | |||
| Southern Region | ||||
| Order # | Quantity | Product | Unit Price | Total Sales |
| 1005 | 2 | Table | $1,114.18 | $2,228.35 |
| 1 | Dresser | $1,518.60 | $1,518.60 | |
| Order Total: | $3,746.95 | |||
| 1007 | 3 | Chair | $325.16 | $975.48 |
| 1 | Table | $1,114.18 | $1,114.18 | |
| Order Total: | $2,089.66 | |||
| Total for Southern Region: | $5,836.61 | |||
| Western Region | ||||
| Order # | Quantity | Product | Unit Price | Total Sales |
| 1006 | 2 | Dresser | $1,518.60 | $3,037.20 |
| 4 | Chair | $325.16 | $1,300.25 | |
| 1 | Table | $1,114.18 | $1,114.18 | |
| Order Total: | $5,451.63 | |||
| Total for Western Region: | $5,451.63 | |||
Using the security features, this one template could be used to meet the requirements of each group. In this example, assume that the report has a query parameter that filters based on region.
For executives, the view above is what they would want to see when viewing the report, so a security level called Management could be created that retrieves data for all regions. This is accomplished by mapping all the available values for the region parameter to the Management level. In this example, the values for the Eastern, Midwestern, Southern, and Western regions would be assigned to the security level. Note that in EspressReport, in order to supply more than one value to a query parameter, you need to define a multi-value parameter. For more information about this, please see Section 1.3.2.2.2.1 - Multi-Value Parameters.
For the account managers, different security levels could be created for each region. The above example has four regions, so security levels East, Midwest, South, and West would be added. Since account managers should not see the aggregate data, cells containing the summaries in the header would be hidden for the region levels using the cell-level security features discussed in Section 1.12.2 - Cell-Level Security. To make sure that each level returns data for the appropriate regions the parameter value for the Eastern region would be mapped to the "East" security level, the parameter value for the Midwestern region would be mapped to the Midwest security level, the parameter value for the Southern region would be mapped to the South security level, and the parameter value for the Western regions would be mapped to the West security level. For more information about setting security levels to apply parameter values, see Section 1.12.2.1 - Security Parameters.
When the report is run, a security level can be supplied (Typically the user's application will determine which security level to use based on a login or some other authorization method. EspressReport does not have its own user authorization mechanism). The cell settings for that security level are applied and the parameter values associated with that level are automatically supplied to the query without prompting the user. For example, here is the same report run with the East security settings:
| Sales Report | ||||
|---|---|---|---|---|
| Eastern Region | ||||
| Order # | Quantity | Product | Unit Price | Total Sales |
| 1001 | 2 | Chair | $325.16 | $650.32 |
| 1 | Table | $1,114.18 | $1,114.18 | |
| Order Total: | $1,764.50 | |||
| 1004 | 3 | Table | $1,114.18 | $3,342.54 |
| 2 | Dresser | $1,518.60 | $3,037.20 | |
| Order Total: | $6,379.74 | |||
| Total for Eastern Region: | $8,114.24 | |||
As a toolkit designed to be embedded within other application environments, EspressReport does not maintain a list of users or access privileges. Rather developers can create any number of unique security levels within a report template. For each level they can assign certain cell behavior, as well as data filtering. At run-time, a security level can be supplied to the report through the API. This solution is flexible enough to adapt to most application security models.
There is no limit to the number of different security levels that can be defined within a template. The only requirement is that each level must have a unique name. The security levels are used globally within a report and can have cell-level settings, as well as parameter values assigned to them. Security levels can be defined at the same time as security settings are applied.
For any cell/visible column in the report, you can set different behaviors for different security levels. To apply security settings to a cell, either select the cell and select Security from the Data menu, or right click on the cell and select Security from the pop-up menu. This will bring up a dialog allowing you to specify security settings for that cell.
Cell Security Settings Dialog
The dialog contains a list of all the defined security levels for the template.
You can add a new security level by clicking the button. This will bring up an additional dialog allowing you to specify a name for the new level.
Add Security Level Dialog
You can enter any name you want for a security level. You can also rename any defined level in the report by selecting the button. Security levels in the report that are not associated with report cells or query parameters are automatically removed.
To add security settings for a report cell, select the level for which you want changes to take effect and click the button (If you create a new security level, it will be automatically added to the cell). The security level will then appear in the drop-down list on the left side of the cell security dialog. Now you can modify the cell for that security level. There are three basic controls available for cells. You can render the cell invisible for a security level. If the cell is visible, you can either provide custom text for the cell or you can apply a cell script. For more information about the cell scripts, please see Section 1.9 - Scripting. If you select to make a column (cell in Table Data section) invisible, make sure to select the column header along with the data cell so they both contain the same security setting, then you can check the Shift Column X option to make the other columns shift to the left when the security level is applied.
![[Note]](../../../images/note.png) | Note |
|---|---|
When you specify to change the text of a cell, it will not work for default column headers. This is because column headers are unique elements that retrieve their value from the data source. If you wish to modify the text of a column header, you will need to convert it to a static label first. For more information about this, please see Section 1.5.7.2 - Editing Elements. |
You can propagate this behavior to any cell that has controls for this security level by clicking the button on the right side. You can specify controls for as many different levels of the cell as you want.
Once you finish specifying the security settings for the cell, click the button. You will go back to the Design window where a red s will appear in the upper left corner to indicate that the security settings have been applied to the cell.
Report Cells with Security Settings
In addition to controlling the specific behavior of cells in a report, you can also assign parameter values to a security level. For example, using the scenario described earlier where a sales report is grouped by region, you could add a query parameter that filters by sales region, and then assign the appropriate region value to a security level for that region. When an employee logs in, the report is run with the appropriate security level and the user will only see data for their sales region as the appropriate parameter value has been supplied to the report by the security level. To use security parameters, the report must use either a parameterized database query or a parameterized class as the data source.
To add security settings for parameters, select Secured Query Parameters from the Data menu. This will bring up a dialog allowing you to select query parameter values.
Security Parameters Dialog
Like the cell security dialog, the parameter security dialog contains a list of all the security levels defined in the template on the left side. You can create and edit levels in the same way as in the cell-level security dialog.
To add security settings to report parameters, select the level you want to assign parameter values to and click the button. The security level will then appear in the drop-down list on the right side of the dialog. For each selected security level, you can select which parameters you want to secure using the check box next to the parameter. For each secured parameter, you can select the value(s) that you want to be associated with this security level. Once you finish assigning parameter values, click the button to return to the design window.
Template security settings can be automatically applied to sub-reports as well as drill-down layers. In both cases, you need to edit the sub-report or drill-down layer (by clicking the sub-report tab, or navigating to the drill-down layer) to add security. In the sub-report or drill-down layer, you can add security settings just as you would for the main report. If you want to apply security to both the main report and the sub-report/drill-down layer, you will need to assign the security levels with the same name(s) as in your main report. When a report is run with a security level, the security level will be automatically applied to the sub-report(s) and/or drill-down layer(s).
For more information about drill-down and sub-reports, please see Section 1.10 - Drill-Down and Section 1.11 - Sub-Reports.
You can preview the effects of your security settings in the Preview window of the Report Designer. To do this, select Set Preview Security Level from the Data menu. This will bring up a dialog prompting you to select the security level that you want to use to view the report.
Preview Security Level Dialog
Select the level you want and then preview the report. You will see the report with security settings applied for the level you selected. This level will remain selected until you change the settings. Selecting the blank entry at the top of the list in this dialog will set the report to run without applying any security settings.
When running secured templates using the API, you can apply the security setting you want to use. The security level can either be passed in as an argument in the QbReport constructor, or set using the setSecurityLevel() method. For more information about running secured templates in the API, please see Section 2.3.5.1.5 - Secure Reports.
There is also a servlet example showing how to run a report with security settings included in the EspressReport installation. Source code and setup instructions can be found in help/examples/servlet/ReportSecurity directory under the EspressReport installation.
When running the Report Designer through the API, you can also apply security. When the Designer is launched, you can pass in a security level using the setSecurityLevel() method. When the Report Designer is running in secure mode, users will only be able to preview reports at the specified level. In addition, they will be unable to modify report cells with defined security settings, or cell scripts that have been applied as security settings. For more information about running Report Designer from the API, please see Section 2.3.5.7.11 - Calling Report Designer from Report API.