Developing Reports

In the file system, all the report data are stored in the following folder:

install_path/reports

The files are distributed to subfolders according to their type. See the following list on which subfolder contains which types of files. Please follow these best practices when designing your own reports.

The report templates must be stored in XML format in files with the suffix “.jrxml”. They can be edited with any XML editor. We recommend using TIBCO Jaspersoft Studio. It’s a free, graphical, Eclipse-based report designer that allows you to design complex JasperReports definitions easily and quickly. See the references [1] and [2] in the chapter “Helpful Resources” for its home page and user guide.

For production, the templates their configuration (search base, filter, etc.), and the other artifacts are taken from LDAP. For development, it is much easier to work with templates in files. Jaspersoft Studio primarily works with files and cannot use templates in LDAP.

DirX Identity supports this use case:

  • All the report artifacts can be stored in files.

  • A batch file allows for generating the report from the command-line passing options in a control file.

When you have finished report development with Jaspersoft Studio, you have to import the necessary artifacts to LDAP. A couple of CLI tools is supporting you for that.

See the next sections for more details.

Templates in the File System

You can store the templates in file folders. Out-of-the-box, the installation already contains a report template in the subfolder reports of the installation. The subfolder reflects the structure of the reports in LDAP:

reports/Users/Users with all properties

Subreports must be placed in the same folder with exactly the names used in the main template. For example, if the main template refers the subreport with:

Users_with_all_properties_Roles

the subreport template must be stored in the file:

Users_with_all_properties_Roles.jrxml

Report Configuration File

A configuration file must be supplied for configuring the entries to be filled into the report and other parameters (as described in the section “Report Configuration”).

The file name suffix should be “.xml”, the standard name in the samples is jspContent.xml. We recommend storing it in the same folder as the templates. The content is exactly the same as in the attribute dxrConfig (displayed in the Content tab) of the LDAP report entry.

Control File

You need a control file for generating a report in the file system. It is the same format as used in the report generation workflows. For each report delivered in the reports folder, there is a corresponding file control.ini in the same subfolder as the report templates.

Besides general information like the operation (generateReport), address and bind credentials to access the DirX Identity LDAP domain and logging levels, it especially sets values for the following keys:

  • reportFolder – The folder that contains the report control, configuration and definition files.

  • report.input.file - The file with the main report template. The path to the file can be absolute or relative to the folder where the report is located.

  • reportCtxFile – The absolute or relative path to the configuration file; in the samples: jspContent.xml.

  • report.filename – The file where the filled report is written. For example, Users_with_all_properties.pdf.

  • report.outputFormat – The output format for the report: PDF, XLSX, etc.

  • viewReport – Whether (true) the report engine opens a pop-up window with the report output or (false) writes it into the output file.

  • report.sizelimit – The maximum number of entries to be written into the report. This parameter helps to limit the LDAP search.

  • report.name – The DN of the report configuration entry in LDAP. This parameter is mandatory but its value is ignored when the parameter report.input.file is set (not commented).

  • reportsFolder – If set, the folder that contains the sub-folders with styles, images and i18n. Per default it is install_path*/reports*.

If you want the job to take the report from LDAP, comment out the line for reportCtxFile and make sure to have the correct DN in report.name. As a sample, take the file controlLdap.ini.

Running Reports

To generate the report, use the file genReport.bat. It is in the folder reports.

Change the last line in the file to select the appropriate control file.

Normally, run the batch file from the reports folder. Per default, it expects that the message properties files and the styles are in the subfolder reports of the installation. The samples also use relative file paths and are below the reports folder.

If you want to design and test in another folder, you can either configure absolute file paths for the properties reportsPath and / or reportPath or even store the batch file and your configuration in a different folder. In the batch file you see that the Java class path is set relative to the installation folder. This assumes DirX Identity is installed on your test system.

Report Template for Testing

The product provides a very simple report template and a corresponding subreport. Its function is to test and experiment with domain entries and their attributes, especially testing the values of the virtual attributes.

The templates, the configuration and the control file are provided in folder tests beneath reports.

Importing Report Artifacts to LDAP

If you are ready with the report design in files, you should transfer them to LDAP so that they can be used in the normal way, for example, from Identity Manager and Web Center.

The scripts for importing styles, images and message texts are in folder

install_path/reports/importTools.

Each script uses its own configuration file, which have most of the configuration properties in common:

  • User, password, host, and port for accessing the Identity domain.

  • Default: if true, the imported entries are put to the report default folder Domain/Configuration/Reports/Default. This flag is normally commented and then the imported entries go into the Customer Extensions folder.

The import tools create an LDAP entry per file or replace a corresponding LDAP entry, if it already exists.

There are two ways to import report definitions to LDAP:

  • Use the tool runImportReports and import a whole folder with report definitions, styles, images, and nationalization texts.

  • Create the LDAP entries with report and sub-report definitions manually and import the other artifacts by running the respective import tool.

Report Entries and Artifacts with Import Tool

The fastest way to import all artifacts that make up a report is to use the importReports tool.

The script

runImportReports.[bat | sh]

imports report definitions, image icons, styles, and nationalization texts in a selected folder to LDAP into folder

Domain/Configuration/Customer Extensions/Reports

Configure the import folder in the properties file install_path/reports/reportImport.properties. Set the property diskFolder to the desired folder path.

Before you can select the report in the User Interface, you must define the appropriate object type(s) in the field Types of the main report entry: User, Role, etc.

Create Report Entry manually

In LDAP, create a folder for the new report and create a new report entry. Copy and paste the report template from the jrxml file to the report entry’s Format tab. Copy the configuration from the configuration file (jspContent.xml) to the Content tab.

Do not forget to set the object type(s) in the field Types of this report entry: User, Role, etc.

For each subreport, create another report entry in the same folder as the main report. Make sure that the name of the report (LDAP RDN) matches the parameter name used in the report template.

You need to set the type of the subreport entry to subreport. At the time of this writing, this task must be performed in DirX Identity Manager’s Data View. From the context menu of the entry, select Go to DataView and change attribute dxrType to jasperSubReport.

Styles

The script

runImportStyles.[bat | sh]

imports style definitions to LDAP, per default into folder

Domain/Configuration/Customer Extensions/Reports/_StyleTemplate

If your style files are not in folder install_path*/reports/_StyleTemplate*: in the properties file styleImport.properties uncomment the line with diskFolder and set the folder or file name.

Images

The script

runImportImages.[bat | sh]

imports image icons to LDAP, per default into folder

Domain/Configuration/Customer Extensions/Reports/_Images

If your image files are not in folder install_path/reports/img: in the properties file imgImport.properties uncomment the line with diskFolder and set the folder or file name.

Nationalization texts (i18n)

The script

runImportI18n.[bat | sh]

imports nationalized message texts to LDAP, per default into folder

Domain/Configuration/Customer Extensions/Reports/Nationalization

If your message files are not in folder install_path/reports/i18n: in the properties file i18nImport.properties uncomment the line with diskFolder and set the folder or file name.