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:

 

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.

 

 

 

 

  • No labels