Report Configuration

Last modified 22 Apr 2024 16:29 +02:00
Reporting feature
This page describes configuration of Reporting midPoint feature. Please see the feature page for more details.
Table of Contents

MidPoint reports can be configured based on the following midPoint concepts:

Current implementation supports exporting reports to the formats mentioned in the following article.

How to Configure Reports

Every report object consists of the configuration of three basic parts:

  • behavior - represents the direction of the report. There are two possible types of behavior: export and import.

    Export behavior represents the basic reporting mechanism, where the file with reported objects is generated.

    Import behavior can be used in situations, when the objects need to be imported midPoint from an external file. The supported format is CSV. Import behavior is experimental.

  • engine - defines the report generation base. There are two supported options, reports based on object collections and reports based on a dashboard. Only one can be defined at the same time.

  • fileFormat - represents format of the generated report file. Supported formats for now are CSV and HTML. Default format for the dashboard-based reports is HTML and for object collection based reports is CSV.

All Configuration Attributes of a Report
Name Type Description

fileFormat

FileFormatConfigurationType

Define report output file format.

dashboard

DashboardReportEngineConfigurationType

Configuration for dashboard-based reports. When defined, dashboard engine is used to generate reports.

objectCollection

ObjectCollectionReportEngineConfigurationType

Configuration for object collection-based reports. When defined, object collection engine is used to generate report.

defaultScriptConfiguration

ScriptExpressionEvaluatorConfigurationType

Default configuration for the scripts executed inside the report.

postReportScript

CommandLineScriptType

Command-line script that will be executed after the report is complete and the output file is completely produced. Output filename will be passed to the script as the "file" argument.

Export Behaviour

With a report you can specify what kind of export file format should be used. If nothing is specified then there are defaults which are used based on the source of data used in the export.

The default for dashboard based reports is HTML. For object collection based reports it is CSV.

Show Configuration Attributes:
Name Type Description

type

FileFormatTypeType

Report data type. Possible values: csv and html.

csv

CsvFileFormatType

Configuration attribute for CSV export.

html

HtmlFileFormatType

Configuration attribute for html export.

HTML

Configuration for HTML file format doesn’t contain any other format specific attributes.

CSV

Configuration for CSV file format contains the following attributes specific for the used format:

Name Type Description Default

multivalueDelimiter

string

Multi-value delimiter.

,

fieldDelimiter

string

Field delimiter.

;

escape

string

The escape character of the format.

\

quote

string

Character for the quote.

"

quoteMode

QuoteModeType

Quote Mode for records. Possible values is all, allNonNull, minimal, nonNumeric and none.

nonNumeric

recordSeparator

string

Separator of line of record.

\r\n

trailingDelimiter

boolean

Define, whether to add a trailing delimiter.

false

trim

boolean

Define, whether to trim leading and trailing blanks.

false

createHeader

boolean

Create header in CSV output file.

true

encoding

string

Encoding of CSV file. Most common encodings (UTF-8, windows-125x, ISO-8859-x) are supported.

See IANA list of charsets for proper values - generally, both IANA and MIME names are supported as well as many aliases. Details of supported character sets depend on the concrete JDK used to run midPoint, but it is unlikely that your charset is not supported.

UTF-8

QuoteModeType

  • all - Quotes all fields.

  • allNonNull - Quotes all non-null fields.

  • minimal - Quotes fields which contain special characters such as the field delimiter, quotes character or any of the characters in the line separator string.

  • nonNumeric - Quotes all non-numeric fields.

  • none - Never quotes fields. When the delimiter occurs in data, the printer prefixes it with the escape character. If the escape character is not set, format validation throws an exception.

Report Engine

Report engine defines the source of data which is used in the report definition, either you use objectCollection or dashboard elements in report.

In the case you want to use Object Collections, have a look at this article dedicated to the related configuration.

In case of Dashboards checkout out this configuration article.

Report Creation

You have multiple possibilities how to create a report. One is using the classical flow for creating a new object. In this case look for the Report menu item on left side of screen in the main vertical menu, and select new Report. Here you have two types of reports to choose from, the "Dashboard" reports and "Collection" reports.

Alternatively you can click on the 'Create report' button under, most of the tables on object list pages (e.g. All users page). In this case, midPoint will automatically use the list as an implicit collection in the report.

users

After clicking the 'Create report' button, you will be redirected to the "new Report' page with predefined filters, based on the search panels from the object table. Also, the columns from the previous table will be used as columns for the new report. You can either use the generated values or you can customise the report definition further.

Another possibility is the usage of one of the report definitions present in each midPoint distribution out of the box. These are pre-configured reports based on often used use-cases. Naturally you can use them as a basis for your custom reports.

You can create and configure reports also with the use of the REST API.

Examples on how to create a report can be found in our Create a Report Guide

For additional configuration details chose from the following articles based on the type of report:

How to Generate The Report

The actual report (i.e. report file) has to be generated. This is done usually by clicking the "run" ("Save and run" or "Run original report") button from the report definition. This will execute a special task object which generated the actual report. After the "run" button is clicked you can access the task either directly through the "notification" prompt which will appear at the header of the page ("show task" button). Or you can access the report through the left vertical menu "Server tasks" > "Report tasks" button and find your task amongst the list of tasks.

The actual report file can be downloaded when the task successfully finished, for this the task GUI contains the "Download report" button.

There are multiple ways how tasks are build when executed from a report definition, for more information on this and also information how you can distribute the workload of the task to multiple nodes see this page

Import Behaviour 'Import From Report'

As mentioned above, the report functionality is also capable of using exported reports or custom csv files to create or update objects. We call this "Import" or "Reverse" reports, for more information regarding them please see the following page:

Import From Report

Reports With Large Datasets

The way how a report is generated by default might need to be customized in case you are working with a large set of data. For this you need to specify the resources which midPoint can allocate for such process. For some more details please have a look at this article.

Report Security

Reports quite often use midPoint expressions, which in some cases might cause security concerns if not used with caution. Please have a look at this page for a more detailed description.

See Also

Compliance

This feature is related to the following compliance frameworks:

Was this page helpful?
YES NO
Thanks for your feedback