Use JasperReports in Identity Manager

• JasperReports library (delivered with Identity Manager)
  
• Downloaded TIBCO Jaspersoft Studio: https://community.jaspersoft.com/project/Jaspersoft-studio

Keep track of the software versions of JasperReports and TIBCO Jaspersoft Studio to make sure your report definitions are designed for the correct Identity Manager version. You find the relevant Jasper versions for different Identity Manager releases in IDM 23.10.3 - Requirements and interoperability.

JasperReports is a Java open source tool for generating reports for several file formats, such as PDF, HTML, XML, XLS and CSV. JasperReport uses its own XML-dialect (jrxml) for the report definition. The printable report will be generated using the jrxml file together with data from the Identity Manager database. For more information, go to https://www.jaspersoft.com/.

The preparation phase

• The preparation phase is done in Identity Manager Admin and Jaspersoft Studio.
• The report definition is created with Jaspersoft Studio and uploaded to Identity Manager Admin.

Work flow:

1. Modify an existing report template (jrxml) or create a new one using Jaspersoft Studio.
2. Save the report definition as DefinitionName.jrxml.
3. Upload the report definition in Identity Manager Admin. Use the menu item "Reports" in the navigation.

4. Navigate to a Search Configuration or Form button and select the uploaded report definition.

5. Save the Search Configuration or Form definition.

The execution phase

• The execution phase is done in Identity Manager Operator.
• The report data is collected from the data source and generated into the report output format.

To print the search results:

1. Do a search in Identity Manager Operator.
2. Click Export on the search result grid, select "PDF".
3. The JasperReport engine creates a report result as a PDF file.

To print from a form within a process:

1. Start the process that contains the print form in Identity Manager Operator.
2. When the form shows up, click Next and the PDF viewer will show the generated document. "Silent printing" in the background is not supported in the HTML client, because the browsers do not support this.

In Jaspersoft Studio you can either design a report definition from scratch or open one of the predefined reports delivered with Identity Manager to adjust the layout as needed.

If you create a new dynamic report, only templates for the the first column, the header and filter parameters are defined and the actual number of needed result columns is generated during runtime according to the specifications of the search configuration. Be careful to use the exact names as described here, because Identity Manager will use them to generate the report automatically.

To create the report definition in Jaspersoft Studio, do the following:

1. Define one column, that serves as a template for the additional columns. 
   The number of report columns to be produced depends on the column count of the search result.
2. Define one filter field as template for all filters specified in the search configuration (if filters should be displayed).
3. Save the report definition file.
   
4.  A pre-generation-mechanism creates the report definition dynamically and adds as many columns and filters as configured in the selected query.
   

The names of the template fields must be:

• filterName0  :  placeholder for the name of the search field <Parameter>
• filterOp0  : placeholder for the name of the operator <Parameter>
• filterValue0  : placeholder for the result of the search <Parameter>

The base elements of this generic report must be:

• value0  :  format for a column, placeholder for all columns <Field>
• colHeader0  : column header, placeholder for all columns <Parameter>
• reportTitle  : Report title <Parameter>

Refer to the documentation of Jaspersoft Studio for the details on report design.

To modify the predefined report definition, do the following:

1. Use the predefined file generic.jrxml included in the Identity Manager delivery.
2. Open it in Jaspersoft Studio and modify it as required, but be careful to keep the fix names as described above.

In Jaspersoft Studio you can either design a report definition from scratch or open one of the predefined reports delivered with Identity Manager to adjust the layout as needed.

In a static report definition the columns are not generated by Identity Manager as in the dynamic report, but taken as they are defined in the definition file. All fields are referenced by the name, so this will provide more flexibility according to report design. The disadvantage is that the report design only fits for search configurations that deal with the same fields as in the report. For example, if the report is based on person data, it only fits for search configurations for persons.

To create the report definition in Jaspersoft Studio, do the following:

1. Add all field definitions according to the data pool fields to the report definition, for example $F{Person_LastName}. Make sure that the report definition matches the correct data pool variable syntax, DataPoolName_FieldName, for example Person_LastName.
2. Add the columns in the details section of the report definition referring to the fields defined.
3. Save the report definition file.

Example:

The report definition contains three fields:
$F{Person_LastName}: LastName variable from variable map
$F{Person_FirstName}: FirstName variable from variable map
$F{Person_PersonnelNumber}: PersonnelNumber variable from variable map.

Additionally a page number should be added to the report:
$V{Page_Number}: internal Jasper variable

Refer to the documentation of Jaspersoft Studio for the details on report design.

To modify the predefined report definition, do the following:

1. Use the predefined file person_list.jrxml included in the Identity Manager delivery as an example.
2. Open it in Jaspersoft Studio and modify it as required.

You can use grouping of search results to add sums, average or other calculations to a report. For example, group a list of cards sorted by the card type and add a total count of each card type.

To set up a report with grouping in Jaspersoft Studio is similar to setting up a plain list report like described above. For the grouping, some additional things must be added:

• Grouping values
  Add a section "groupResult Group Header" to the report definition. Refer to the documentation of Jaspersoft how to do so.
  This section is optional. You can remove it or customize it.
• Total grouping values
  Add a section "groupResult Group Footer" to the report definition.
  If you use any columns for grouping, the number of elements in grouping are displayed in this section.
• In the section "Page footer" a page summary can be printed, for example the current date or the page number.
• In the section "Summary" a total summary of the report can be printed, for example the total count of all elements.

In the dynamic report, grouping can only be done by the first column of the search configuration's result columns. The structure of the report is the same as described in the section "Set up dynamic report definition", except that grouping is added.

1. To adjust the layout of the report, open the file generic_grouping.jrxml in Jaspersoft Studio and customize it.
2. Do not rename the predefined field names. They are needed later to generate the report from the search configuration settings.

With a static report template it is possible to select any column for grouping without changing the order sequence of the search configuration.

This can be done because in a static report all fields are referenced by the name, and this provides more flexibility according to report design. The disadvantage is that the report design only fits for search configurations that deal with the same fields as in the report. For example if the report is based on person data, it only fits for search configurations for persons.

The structure of the report is the same as described in the section "Set up static report definition", except that the grouping was added.

You can create a static report definition based on the fields that are contained in the data map of the process where the PDF printing form should be used. The report definition in this case does not represent a list of data but a printable representation of the current process data. This can be used for printing receipts or PIN letters for example.

To edit the report definition in Jaspersoft Studio:

1. Add all field definitions according to the data pool fields to the report definition, for example $F{Card_LastName}. Make sure that the report definition matches the correct data pool variable syntax, DataPoolName_FieldName, for example Card_LastName.
2. Add the columns in the details section of the report definition referring to the fields defined.
3. Save the report definition file.

Example:

The report definition contains four fields:
$F{Card_LastName}: LastName variable from the data map.
$F{Card_FirstName}:FirstName variable from the data map.

$F{Card_PIN}: PIN variable from the data map.
$F{Card_PUK}: PUK variable from the data map.

Refer to the documentation of Jaspersoft Studio for the details on report design.

1. Create a JasperReport definition file (jrxml) with Jaspersoft Studio as described in the previous sections.
2. Open Identity Manager Admin and navigate to the Reports menu.
3. Create a new report template and upload  the report definition file (jrxml) .
4. Use the report in a:
   1. Search Configuration: select the report template in the export dialog. See Set up search configuration in Identity Manager for more information.
   2. Form: add a report component and select the report template for it. See Set up form in Identity Manager for more information.

In order to use custom fonts, they must be installed in Jaspersoft Studio in the following way:

1. Download the font from a website (make sure that you have the correct license to do so). Jaspersoft supports a various number of font types, like like TTF, SVG, WOFF and EOT.
2. Install a font extension in Jaspersoft Studio.
   
3. Embed the font in the report definition.
4. Export the font extension to a jar file.
5. Add the jar file in the Identity Manager class path under prime_explorer/WEB-INF/lib.
   

A detailed description of how to install a font is described in the Jaspersoft documentation: https://community.Jaspersoft.com/wiki/custom-font-font-extension