Page tree
Skip to end of metadata
Go to start of metadata

This guide is only for small customization which can be done directly in midPoint. In the case you need more complex customization it is maybe better to create new report template or customize existing one with Jaspersoft Studio. How to work with Jaspersoft Studio using live midPoint can be found here.

Report customization using midPoint

After listing reports in midPoint (Reports -> List Reports) and clicking on the configure button you are able to modify some basic report attributes. As the picture bellow shows there are three tabs. Each of them is related to different part of report which can be configured. In the first tab 'Basic configuration' you can configure name of the report and export format. The second tab 'Jasper template' can be used to customize existing template, e.g. you can add/remove parameters, modify query etc. The last tab 'Jasper template style' is used as a style for the report. You can change it according to your needs (e.g. font size, font family, ...)

Customizing Jasper template

In the midPoint's GUI you have available all the jasper template so it is possible to update it directly with midPoint. But, as I stated before, I don't recommend to do complex modifications in the midPoint. midPoint is not a reporting tool and for this purpose we decided to use Jasper Report framework. I recommend to do only small modification in queries or parameters in midPoint. 

  1. Report parameters - you can add/remove or modify report parameters. Support for multi-value parameters exists since 3.6. If you check 'For prompting' attribute, it means that this parameter is shown in the pop-up panel when you run report. Report parameters are used as input values to the query.
     
    1. There is a special column Properties. After clicking on the Configure link, new popup is shown. In this popup you can define additional properties describing the parameters. These properties are then used for customization of run popup such as lookup tables.
  2. Report fileds - you can add/remove or modify report fields. But be aware that if you make any change to the report field, you have to seek for the original filed definition throughout  the whole jasper report definition and replace old filed with the new one defined.
  3. Report query - customize query according to you needs. E.g. you can add filter to search only enabled user or user in some organization etc. The query language is 'mql' which is a shortcut for MidPoint Query Language. You can use the same query syntax as everywhere else (e.g. correlation rule). It is also possible to define script instead of query. All the existing midPoint function are available (Basic, midpoint, report). 
    • Queries must be wrapped in <filter> element
    • Scripts must be wrapped in <code> element

Adding auto-complete to input parameters

MidPoint can visualize report input parameter as select box with auto-complete ability. The optional auto-complete can be used for input parameters with limited set of values - e.g. whispering all available users, resources or organizations. Normally non-enum parameters are displayed as text input fields. If you wish midPoint to render parameters as select boxes with auto-complete, you need to specify these three parameter properties:

  • key - property path to target attribute that will be passed to Jasper query as parameter value (e.g. name, oid)
  • label - property path to target attribute that will be displayed as label in auto-complete box (e.g. name, fullName, oid)
  • targetType - full class name of target type that will be populated into auto-complete box (UserType, RoleType, OrgType...)

This example populates auto-complete with all roles in midPoint:

<parameter name="role" class="java.lang.String">
	<property name="key" value="oid"/>
	<property name="label" value="name"/>
	<property name="targetType" value="com.evolveum.midpoint.xml.ns._public.common.common_3.RoleType"/>
</parameter>


Limitations:

  • "key" and "label" properties can only reference prism properties of target object, not complex values like containers or references
  • "key" and "label" properties can only reference single-value properties, not multi-value

Configuring multi-value input parameters

Available since 3.6

Sometimes you need to specify report query using more than one value for the attribute, e.g you want to search users with employeeType=contractor and employeeType=fulltime. To prevent defining two different reports - one for employeeType = contractor and second one for employeeType=fulltime the support for multi-value parameters was added in midPoint 3.6. To enable this feature, you need to configure parameter class as a java.util.List and than nested class with the real value of items which will be filled into the list. However, be aware that after the parameter is changed to multi-value it is also needed to update the report query and (maybe) other jasper report parts.

In the picture above, there are two attributes defined as multivalue - eventType and eventStage. As you can see, both of these attributes parameter class is set to java.util.List and the nested class then contains concrete type which will be in the list.

Performance and run-time settings

Virtualizers

Jasper report has ability to utilize so-called virtualizers that can optimize memory usage. Virtualizers come handy when you generate very large reports of hundreds to thousands+ pages. In these situations memory consumption can become crucial and you may run out of Java heap space. Currently there are 3 virtualizers available in Jasper and what they basically do is they save memory consumption on account of consuming little more CPU or disk space.

Detailed virtualizers description can be found here: http://community.jaspersoft.com/wiki/virtualizers-jasperreports

MidPoint offers these two settings in report configuration to set Jasper virtualizer:

  • Jasper virtualizer - select one of three prebuilt virtualizers or select none to disable feature.
    • Recommended setting: JRSwapFileVirtualizer
    • Both file virtualizers save temporary data into <midPoint_home>/tmp directory.
  • Virtualizer's pages kick-on - only effective when virtualizer is selected. It defines number of report pages after virtualizer "kicks on". The more memory you have (Java Xmx), the higher number can be. Reports that do not reach the specified number of pages will not utilize any virtualizer.
    • Recommended setting: 300

Limitation: Maximum size of object being stored in any virtualizer is 65K. That equals massive number of text in one cell (one column X one row). If you encounter "Error virtualizing object java.io.UTFDataFormatException" or other problems, you should disable virtualizer.

Governors

Another mechanism to control the Jasper report runtime are so-called governors. Governors can limit number of pages and/or execution time of report. MidPoint has two settings for this, but please be aware that Jasper enforces these limits little unintuitively and practically limits are enforced some time/pages after threshold value has been reached. When limit is reached, report is cancelled without being generated. Using governors can increase robustness of reporting engine and prevent overloading of midPoint's resources. We strongly recommend using them.


Set value to empty or 0 to disable governor.

Changing delimiter in CSV export

To change delimiter in CSV export you have to define it in jasper template for any report :

  • Example 

<property name="net.sf.jasperreports.export.csv.field.delimiter" value=";"/>

Removing names of fields on all pages except the 1st page in CSV export

To remove names of fields on all report pages except the 1st page in CSV report you have to define "printWhenExpression" in jasper template

  • Example

<columnHeader>
             <band height="24" splitType="Stretch">
                         <printWhenExpression><![CDATA[$V{PAGE_NUMBER}==1]]></printWhenExpression> 
                         <frame>
                                 <reportElement style="Column header" mode="Transparent" x="0" y="1" width="1000" height="19" isRemoveLineWhenBlank="true" uuid="3e8fdd6d-a6ff-4407-9a1e-5d6b4706300a"/>
                                 <staticText>
                                              <reportElement style="Column header" x="0" y="0" width="300" height="18" uuid="86c74beb-bddd-48cc-945a-167b261b1e0b"/>
                                              <textElement textAlignment="Center" verticalAlignment="Middle"/>
                                              <text><![CDATA[Name]]></text>
                                 </staticText>
                         </frame>
            </band>
</columnHeader>


Security Of Report Expressions

Reports often use expressions. Expressions allow to customize midPoint behavior and they are essential for the success of midPoint deployments. However, the expressions are very powerful and they may even be too powerful for some use cases. The expressions can use general-purpose scripting languages such as Groovy or JavaScript. Therefore such expressions have almost unlimited capabilities. Which means that the expressions can damage the system or compromise security of the system. Use the expressions with utmost care.

Currently, there are very little restraints for expression execution. The expression functions provided by midPoint usually check for proper authorizations. But as the expressions can use general-purpose languages, there is no obligation for the expressions to use those libraries. The expression can easily circumvent those weak protections. Therefore do not let any unauthorized user to set up any kind of expression in midPoint. Allowing the right to edit any expression may lead to compromise of system security.

Some expression security can be achieved by using expression profiles.  Expression profiles can be used to limit the capabilities of report expressions, e.g. to limit them to safe operations that just manipulate strings and basic data structures. This seems to work reasonably well for ordinary object-based reports. However, when it comes to audit reports, this solution may not be sufficient. Audit records are not  midPoint objects, they are just rows in ordinary relational table. Therefore the usual midPoint mechanisms do not apply to them. E.g. they cannot be queries by using midPoint query mechanisms. There is a way how a "safe" expression can construct a string query for audit table. However, there is no protection against SQL injection or similar attacks. Major improvement to auditing capabilities of midPoint would be needed for that purpose.

An example of such an audit report can be found in midPoint tests: https://github.com/Evolveum/midpoint/blob/master/model/report-impl/src/test/resources/reports/report-audit-csv.xml
However, this is just an example. It may not be complete, it may not be secure. There are no guarantees. Use at your own risk.

In case that a secure audit reports are needed, the current recommendation is to make such reports outside of midPoint. The structure of an audit table is documented and it can be used for integration with data warehouse and/or SIEM systems. MidPoint is neither of those systems and it has no ambition to become one. Therefore such integration is likely to be required anyway to construct a complete information security solution.

See Security Guide for more detail regarding security-related functionality of midPoint.

See Also


  • No labels