Customizing Reports

DirX Audit reporting is based on TIBCO JasperReports Library, which is an open source reporting engine. JasperReports defines a report with an XML file (suffix: .jrxml). Its format is XML-based and can be edited with any XML editor. We recommend that you use TIBCO Jaspersoft Studio to create and maintain your JasperReports definitions. It is a free, open source, Eclipse-based report designer and allows you to design complex JasperReports definitions easily and quickly.

The report design usually contains a SQL query to set the scope of database records to be reported. However, DirX Audit can optionally provide the input records via its API. See the chapter “Working with View Type APIs” for more details.

A report configuration comprises the following items:

Report definition – an XML-formatted file that contains meta data for the report. DirX Audit evaluates it when you set up a schedule for the report and configure its scope and when the report is produced either in DirX Audit Manager, DirX Audit Manager Classic or scheduled by DirX Audit Server. The report definition refers to a SQL query and Report output format.
SQL query – a file that contains a SQL query. DirX Audit executes this query and passes the resulting database records to JasperReports when the report is generated. The SQL query can contain placeholders, which are variables that must be set in DirX Audit Manager or DirX Audit Manager Classic when the report is configured and scheduled. See the chapter “Using Reports Page” in the DirX Audit Manager Guide for DirX Audit Manager or see the chapter “Using the Reports View” in the DirX Audit Manager Classic Guide for details.
Report output format – a *.jrxml file typically created using TIBCO Jaspersoft Studio.

These files must be stored in the following locations in the DirX Audit installation folder:

The report definition and SQL query files must be stored in the folder install_path/conf/defaults/report-definitions/reportName. The file names are reportName.xml for the report definition used in DirX Audit Manager Classic, reportName.json for the report definition used in DirX Audit Manager and reportName.sql for the SQL query.
The report output format must be stored in install_path/conf/defaults/reports/reportName/reportName.jrxml.

Make sure these files are stored in these locations on every host where either DirX Audit Manager, DirX Audit Manager Classic or DirX Audit Server is installed.

This chapter describes how to:

Configure a report definition file
Configure a SQL query with placeholders
Set up TIBCO Jaspersoft Studio
Create a new report and change an existing report
Add TIBCO JasperReports templates to DirX Audit Manager’s Audit Analysis and History
Solve problems with reports

For more information, see:

The TIBCO Jaspersoft Studio homepage:
https://community.jaspersoft.com/project/jaspersoft-studio
The TIBCO JasperReports homepage:
http://sourceforge.net/projects/jasperreports

Configuring Custom Files

If you want to customize a report and its resources, it is possible to do that for all or for a specific tenant. Configuration of custom files apply concepts described in the “General Customization” chapter.

Configuring Custom Files in Report-definitions Folders

Default report definition files are located in the common core default folder:

install_path/conf/defaults/report-definitions/reportName

It is not recommended to modify Report definitions and SQL queries located at this location, as with new installation or upgrade the entire folder will be overwritten or deleted. To create a customized version, copy the folder with its content to core customization folder for all tenants:

install_path/conf/report-definitions/reportName

For specific tenant, you can copy the folder to:

install_path/conf/tenants/tenantID/report-definitions/reportName

where tenantID is a unique tenant identifier. During installation or upgrade, these folders will be preserved.

It is necessary to rename the folder and its content, as report definitions must have unique names in order to load properly. As it is not allowed to overwrite default report-definitions the find first file resolving priority is applied. Modify the SQL query and Report definition according to the following chapters.

Configuring Custom Files in Reports Folders

Default report files are located in the common core default folder:

install_path/conf/defaults/reports/

Customized version for all tenants is located at:

install_path/conf/reports/

For specific tenant, the folder is:

install_path/conf/tenants/tenantID/reports/

where tenantID is a unique tenant identifier.

As the find last file resolving priority is applied, all files can be customized. These files are:
.jrxml – report output format
.svg – images used in report output format located at reports/img
.jrtx – report output format style used in report output format located at reports/_StyleTemplate

For example, the report output format .jxrml file for report HstApprovers located at:

install_path/conf/defaults/reports/HstApprovers/HstApprovers.jrxml

Can be customized for all tenants by copying the file to:

install_path/conf/reports/HstApprovers/HstApprovers.jrxml

And/or for specific tenant to:

install_path/conf/tenants/tenantID/reports/HstApprovers/HstApprovers.jrxml

During the report creation, the most specific .jrxml file will be used. The same applies for .svg and .jrtx files. This includes common shared subreports located at reports/_common_shared folder.

Note, that subreports defined in specific report must always be present inside the report’s folder and only those will be compiled.

Customizing Company Logo in Report Templates

A default company logo is located at:

install_path/conf/defaults/reports/img/company_logo.svg

The logo can be customized in a similar way to the report content as explained in the previous chapter. The customized logo file must be named company_logo.svg.

To disable the logo in generated reports by default, copy the provided transparent image at:

install_path/conf/defaults/reports/img/company_logo_empty.svg

For all tenants to:

install_path/conf/reports/img/company_logo_empty.svg

For a specific tenant to:

install_path/conf/tenants/tenantID/reports/img/company_logo_empty.svg

And rename the file company_logo_empty.svg in the new location to company_logo.svg. During report generation, the transparent image will be used, and the logo will not be visible in generated files.

Configuring a Report Definition File for Dirx Audit Manager Classic

A report definition is stored in an XML file according to the XML namespace http://definition.report.persistence.xml.audit.dirx.atos.net. To configure a report definition, you need to:

Set up report definition XML elements
Extend DirX Audit Manager Classic’s application context, if you have created customized versions of Java Beans for PickListControl controls defined in the report definition.

Setting Report Definition Elements for DirX Audit Manager Classic

You need to set the following XML elements:

id
– the unique identifier for the report.

name and description
– the name and description of the report to be displayed by DirX Audit Manager Classic when selecting and configuring a report. DirX Audit Manager Classic expects a variable in both fields and replaces them with the property found in the corresponding properties files messages_language.properties in the folder install_path/conf/i18/. If you want to override default properties or add your own ones, we recommend creating your own properties files and putting them into the same folder with the report definitions: install_path/conf/defaults/report-definition/reportName/reportName.properties for English (default), reportName_de.properties for German and reportName_fr.properties for French.

query
– the name of the file that contains the SQL query. The file must be in the same folder as the report definition file.

dataType
– the type of event on which to report. Set the value DXT_DATA if the report is on audit events and DXT_HISTORY if the report is on history entries.

outputType
– the type of report output. Currently, only LIST is supported to indicate that the report outputs a list of records.

reportTemplates, reportTemplate
– an identifier (reportName) of a report output format; that is, a name reference to the *.jrxml file.

tags
– the list of <tag> sub-elements that characterize the report and help an auditor when selecting an appropriate report in DirX Audit Manager Classic. Note that these tags can be variables for message properties and be localized into supported languages.

controls
– the list of <control> sub-elements that you need for each placeholder in your SQL scope definition. A control represents a placeholder ${placeholder} in the SQL query string that you refer to in the element query. Each placeholder is a variable that must be replaced when the report is produced. When the report is configured in DirX Audit Manager Classic, the auditor can select value(s) for these variables. If a placeholder is flagged as optional, no value needs to be provided. DirX Audit Manager Classic uses the control elements to generate the HTML view for configuration of the report scope. The variables and sub-elements of <control> are:

label – the string or key to a message properties file. DirX Audit Manager Classic displays it as the head of the control. It should help the auditor to understand what to select.
controlType – the name of a user interface component. These components include:

BooleanControl – a checkbox.

DateControl – a calendar.

HiddenControl – a control that is not displayed. This component can be used to pass (nationalized) values into the report output.

IntegerControl – an input box.

PickListControl – a powerful control that helps the auditor to search and select from values found in the database; for example, to search and select a list of users by entering their last names.

PickListControlWithoutSearch – control that helps the auditor to select from pre-selected values set in report definition.

PickListCsvColumnsControl – control that allows the auditor to select which columns are included in the output when generating a report in spreadsheet (CSV) format.

SelectControl – a combo box.

StringControl – an input box.

TimePointControl – a combo box for defining a time point with a pre-defined option.

TimeRangeControl – a combo box for defining a time range (from – to) with a pre-defined option.

controlName – the name of a Java Bean that the control uses to obtain attribute names, attribute values and search results. The control must be configured with this name in the Spring report context file install_path/web/audit-manager-classic.war/WEB-INF/classes/reportContext.xml. See the section “Extending DirX Audit Manager Classic Report Context” for more information on the bean interface.
srchSelLabel – applicable only for PickListControl. Represents string or key to a message properties file. DirX Audit Manager Classic displays it as the label of PickListControl select list.
srchValLabel – applicable only for PickListControl. Represents string or key to a message properties file. DirX Audit Manager Classic displays it as the label of PickListControl value list.
params with sub-elements param or paramList – parameters specific for the control:
- The param element represents a single-value parameter. It is either the name of a placeholder used in the SQL query or passed to JasperReport as a variable. The params element has the following XML parameters:
  - name – the name of the parameter; exactly as used in the SQL query or in the JasperReports output file.
  - passToReport – a Boolean value. If true, it is passed to the JasperReports output file.
  - passAsValue – a Boolean value.
  - passToReportAsValue – a Boolean value.
  - type – the Java full class name that represents the type of the attribute.
  - use – whether or not the parameter must be populated. The value required (default) tells DirX Audit Manager Classic that a value for the parameter is required. If the value is optional, no value needs to be provided. If it refers to a placeholder in the SQL query, the corresponding section is dropped which requires specific formatting, and no constraints are applied regarding this placeholder.
  - initialValue – the initial value if displayed first time in DirX Audit Manager Classic. Note: this is not a default value.
  - initialDisplayValue – the initial display value, if displayed for the first time in DirX Audit Manager Classic and initialValue is not user-friendly enough.
- The paramList element represents a multi-value parameter. It contains the same XML attributes and sub-elements as param with the exception of initialValue and initialDisplayValue: here they are sub-elements that can occur several times rather than XML attributes.
  
  Parameters supported by the controls include:
- BooleanControl – supports only one parameter of type java.lang.Boolean.
- DateControl – supports only one parameter of type java.util.Date.
- HiddenControl – supports 1..n parameters, either param or paramList. They need to have an initial value; otherwise the parameter makes no sense.
- IntegerControl – supports only one parameter of type java.lang.Integer.
- PickListControl – supports only one parameter of type java.lang.String. It requires the controlName attribute for the Java Bean that obtains the attributes.
- SelectControl – supports only one parameter of type java.lang.String. It requires the controlName attribute for the Java Bean that obtains the attributes or one paramList element to provide the initial values from which to select.
- StringControl – supports only one parameter of type java.lang.String.
- TimePointControl – requires the following parameters:
  - Type java.lang.String that holds a constant for WhenType. Possible values are: END_OF_PREVIOUS_DAY, END_OF_PREVIOUS_WEEK, END_OF_PREVIOUS_MONTH, END_OF_PREVIOUS_YEAR, CUSTOM_TIME_POINT.
  - Type java.util.Date with the Date value for the specification of the time point.
- TimeRangeControl – requires the following parameters:
  - Type java.lang.String that holds a constant for WhenType. Possible values are: LAST_HOUR, LAST_24HOURS, LAST_WEEK, LAST_7DAYS, LAST_30DAYS, LAST_MONTH, LAST_3MONTHS, LAST_YEAR, TODAY, YESTERDAY, PREVIOUS_DAY, PREVIOUS_WEEK, WEEK_TO_DATE, PREVIOUS_MONTH, MONTH_TO_DATE, PREVIOUS_YEAR, YEAR_TO_DATE, CUSTOM_TIME and ANYTIME. They correspond to the values in the DirX Audit Manager Classic Audit Analysis tab: last hour / 24 hours, last week, last 7 days, last 30 days, last month, last 3 months, last year, today, yesterday, previous day, previous week, week to date, previous month, month to date, previous year, year to date, custom time (you set fixed start and end date and time) and all (any time). See the section “Filtering Audit Events” in the chapter “Using the Audit analysis” of the DirX Audit Manager Classic Guide for details.
  - Type java.util.Date with the from value for the start of the time interval.
  - Type java.util.Date with the to value for the end of the time interval.

Extending DirX Audit Manager Classic Report Context

When you configure your own Java Bean for a PickListControl, you need to extend DirX Audit Manager Classic’s report context.

The DirX Audit Manager Classic’s report context is in the file:

install_path/web/audit-manager-classic.war/WEB-INF/classes/reportContext.xml

You need to define a bean that reflects your PickListControl and you need to register it at the reportConfigurationHolder bean. The registration name must be identical to the name used in the report definition in the controlName XML attribute. See the description of this attribute in the section “Setting Report Definition Elements for DirX Audit Manager Classic” for details.

For example, suppose the controlName is "SelectUserUidsComponentService". We need to register it at the reportConfigurationHolder in the following way:

<bean
  id="reportConfigurationHolder" …>
  …
  <constructor-arg
    name="componentMap">
    <map>
      …
      <entry
        key="SelectUserUidsComponentService"
        value-ref="selectUserUidsComponentService" />
    </map>
  </constructor-arg>
</bean>

In the XML attribute value-ref, enter the (case-sensitive) name of your new PickListControlBean; for example, selectUserUidsComponentService in the snippet above.

The best way to define the PickListControl bean is to copy one of the existing bean definitions and then change the values. You need to change the bean name in the XML attribute id and the following constructor argument values:

dbType – the database type. Use DXT_DATA for a report on audit events and DXT_HISTORY for reports on history entries.
attributeNamesSqlFile – the name of the file that contains the SQL query for finding attribute names. A file with this name must be placed in the folder
install_path/conf/defaults/sql/common/report_search_queries/.
attributeValuesSqlFile – the name of the file that contains the SQL query for finding attribute values for the above found attribute names. A file with this name must be placed in the folder
install_path/conf/defaults/sql/common/report_search_queries/.
searchResultSqlFile – the name of the file that contains the SQL query for finding records that match an attribute name and value selected from the result set of the above queries. A file with this name must be placed in the folder
install_path/conf/defaults/sql/common/report_search_queries/.

Note, that you can add or customize these SQL files for all and/or specific tenant as described in the “General Customization” chapter. Examples are available in the chapter “Customizing SQL Scripts”.

Here is an example for the bean registered in the previous example:

<bean
  id="selectUserWhoUidsComponentService"
  factory-bean="reportComponentServiceFactory"
  factory-method="createComponentService">
<constructor-arg
  name="dbType"
  value="DXT_DATA" />
<constructor-arg
  name="attributeNamesSqlFile"
  value="data_user_who_uid_attribute_names.sql" />
<constructor-arg
  name="attributeValuesSqlFile"
  value="data_user_who_uid_attribute_values.sql" />
<constructor-arg
  name="searchResultSqlFile"
  value="data_user_who_uid_search_result.sql" />
</bean>

The control searches in the database on audit events.

The query for attribute names is intended to find all attribute names that were used as an identifying attribute for the "who" of an audit message. Typical examples of these names are: AltName, First Name, Last name, employeeNumber, Organization.

The query for attribute values is intended to find all values for a given attribute name obtained from the query above. It contains two placeholders: the first is replaced with the attribute name. For example, the auditor could select Last Name from the list above. The second placeholder is replaced with the sub-string the auditor entered. For example, the auditor wants to find all users whose last name starts with a, then the placeholders would become a%.

The query in searchResultSqlFile is intended to find – in this example – all users that match the attribute name (for example, Last Name) and the attribute value sub-string (for example, a). It returns the UID of these entries – here, users – along with other attributes that help the auditor to identify them. For users, these identifying attributes are often AltName and Organizational Unit. The placeholders for the attribute name and value sub-string are ${KEY} and ${VALUE_LIKE}. Note the ${…} notation here: these are not JDBC placeholders as in the query above, but placeholders as used in the Apache FreeMarker template engine. This gives you the option to use a placeholder several times in the query.

Configuring a Report Definition File for Dirx Audit Manager

A report definition is stored in an JSON file according to the JSON schema https://audit.dirx.solutions/schemas/report/report-definition-schema.json. To configure a report definition, you need to:

Set up report definition JSON properties
Extend DirX Audit Manager’s report components, if you have created customized versions of Components for array-picklist-modal or dxtselect UI parameters defined in the report definition.

Setting Report Definition Elements for DirX Audit Manager

The JSON schema for a report definition is structured into three main sections: itemUuid, metadata, and data.

itemUuid – the unique identifier for the report definition, represented as a version-4 UUID.

metadata – contains meta-information about the report definition, including:

version – the version of the report definition.
revision – the revision number of the report definition.
accessLevel – the access level required for the report definition. For customization purposes, set this property to PUBLIC.
name – the name of the report definition.
description – the description of the report definition.
creationTimestamp – the timestamp indicating when the report definition was created.

data – contains the actual configuration and structure of the report definition, including query references, UI parameters, templates, and other report definition-specific settings:

id – the unique identifier for the report.
name and description – the name and description of the report to be displayed by DirX Audit Manager when selecting and configuring a report. DirX Audit Manager expects a variable in both fields and replaces them with the property found in the corresponding properties files messages_language.properties in the folder install_path/conf/i18/. If you want to override default properties or add your own ones, we recommend creating your own properties files and putting them into the same folder with the report definitions: install_path/conf/defaults/report-definition/reportName/reportName.properties for English (default), reportName_de.properties for German and reportName_fr.properties for French.
query – the name of the file that contains the SQL query. The file must be in the same folder as the report definition file.
dataType – the type of event on which to report. Set the value DXT_DATA if the report is on audit events and DXT_HISTORY if the report is on history entries.
outputType – the type of report output. Currently, only LIST is supported to indicate that the report outputs a list of records.
reportTemplates – an array of objects, each representing a report output format. Each object contains:
- id – a unique identifier for the report template.
- label – the display name or key for the template, which can be localized into supported languages.
- path – the reference to the .jrxml file.
tags – the array of tags that characterize the report and help an auditor when selecting an appropriate report in DirX Audit Manager. Note that these tags can be variables for message properties and be localized into supported languages.
parameters – the array of UI parameters that you need for each placeholder in your SQL scope definition. A UI parameter represents a placeholder ${placeholder} in the SQL query string that you refer to in the query property. Each placeholder is a variable that must be replaced when the report is produced. When the report is configured in DirX Audit Manager, the auditor can select value(s) for these variables. If a placeholder is flagged as optional, no value needs to be provided. DirX Audit Manager uses the UI parameters for configuration of the report scope. The variables and properties of UI parameter are:
- key – the unique key of a UI parameter
- reportTemplateIds – references id values in reportTemplates for which the UI parameter is shown; the UI parameter is only shown for the specific selected template id(s) listed here, and hidden for others. If omitted, the UI parameter is visible for all templates.
- params or paramsList – parameters specific for the UI parameter:
  - The params property represents a single-value parameter. It is either the name of a placeholder used in the SQL query or passed to JasperReport as a variable. The params property has the following properties:
    
    name – the name of the parameter; exactly as used in the SQL query or in the JasperReports output file.
    
    passToReport – a Boolean value. If true, it is passed to the JasperReports output file.
    
    passAsValue – a Boolean value.
    
    passToReportAsValue – a Boolean value.
    
    type – the Java full class name that represents the type of the attribute.
    
    use – whether or not the parameter must be populated. The value required (default) tells DirX Audit Manager that a value for the parameter is required. If the value is optional, no value needs to be provided. If it refers to a placeholder in the SQL query, the corresponding section is dropped which requires specific formatting, and no constraints are applied regarding this placeholder.
    
    initialValue – the initial value if displayed first time in DirX Audit Manager. Note: this is not a default value.
    
    initialDisplayValue – the initial display value, if displayed for the first time in DirX Audit Manager and initialValue is not user-friendly enough.
  - The paramsList property represents a multi-value parameter. It contains the same properties and sub-elements as params with the exception of initialValue and initialDisplayValue: here they are sub-elements that can occur several times.
- formlySchema – definition of the UI, contains:
  - type – simple or complex type of UI parameter:
    
    boolean – a checkbox, supports only one parameter of type java.lang.Boolean.
    
    integer – an input box, supports only one parameter of type java.lang.Integer.
    
    string – an input box, supports only one parameter of type java.lang.String.
    
    object – a complex input described further.
  - widget – contains definition of formlyConfig:
    
    type – complex types:
    
    period – a combo box for defining a time range (from – to) with a pre-defined option, requires the following parameters:
    
    Type java.lang.String that holds a constant for WhenType. Possible values are: LAST_HOUR, LAST_24HOURS, LAST_WEEK, LAST_7DAYS, LAST_30DAYS, LAST_MONTH, LAST_3MONTHS, LAST_YEAR, TODAY, YESTERDAY, PREVIOUS_DAY, PREVIOUS_WEEK, WEEK_TO_DATE, PREVIOUS_MONTH, MONTH_TO_DATE, PREVIOUS_YEAR, YEAR_TO_DATE, CUSTOM_TIME and ANYTIME. They correspond to the values in the DirX Audit Manager Audit analysis tab: last hour / 24 hours, last week, last 7 days, last 30 days, last month, last 3 months, last year, today, yesterday, previous day, previous week, week to date, previous month, month to date, previous year, year to date, custom time (you set fixed start and end date and time) and all (any time). See the section “Filtering Audit Events” in the chapter “Using Audit Analysis” of the DirX Audit Manager Guide for details.
    
    Type java.util.Date with the from value for the start of the time interval.
    
    Type java.util.Date with the to value for the end of the time interval.
    
    timepoint – a combo box for defining a time point with a pre-defined option, requires the following parameters:
    
    Type java.lang.String that holds a constant for WhenType. Possible values are: END_OF_PREVIOUS_DAY, END_OF_PREVIOUS_WEEK, END_OF_PREVIOUS_MONTH, END_OF_PREVIOUS_YEAR, CUSTOM_TIME_POINT.
    
    Type java.util.Date with the Date value for the specification of the time point.
    
    dxtselect – a combo box, supports only one parameter of type java.lang.String.
    
    array-picklist-modal – a control that helps the auditor to search and select from values found in the database, pre-selected values set in report definition or select which columns are included in the output when generating a report in spreadsheet (CSV) format. Supports only one parameter of type java.lang.String.
    
    templateOptions – contains miscellaneous options
    
    label – label of a UI parameter
    
    componentId – id of a component providing values from database, relevant only for array-picklist-modal or dxtselect
    
    options – property providing values, relevant only for array-picklist-modal or dxtselect
  - default – preselected value of UI parameter
  - required – boolean value deciding if values must be provided

Extending DirX Audit Manager Report Components

When you configure your own Component for a array-picklist-modal or dxtselect, you need to extend DirX Audit Manager’s report components.

The DirX Audit Manager’s report components are in the file:
install_path/conf/defaults/report-components/dxtComponents.json

For adding or customizing a report component(s), see the chapter “Customizing Report Components for DirX Audit Manager” in the “General Customization” chapter.

To define a component that reflects your array-picklist-modal or dxtselect. The id must be identical to the name used in the report definition in the componentId property.

{
  "components": [
    …
    {
      "id": "selectUserWhoUidsComponentService",
      "dbType": "DXT_DATA",
      "attributeNamesSqlFile": "data_user_who_uid_attribute_names.sql",
      "attributeValuesSqlFile": "data_user_who_uid_attribute_values.sql",
      "searchResultSqlFile": "data_user_who_uid_search_result.sql"
    },
    …
    {
      "id": "selectUsrAttrComponentService",
      "dbType": "DXT_HISTORY",
      "attributeNamesSqlFile": "hst_usr_attrs.sql",
      "attributeValuesSqlFile": null,
      "searchResultSqlFile": null
    },
    …
  ]
}

The best way to define the Component is to copy one of the existing component definitions and then change the values. You need to change the following constructor argument values:

id – componentId defined in formlySchema.
dbType – the database type. Use DXT_DATA for a report on audit events and DXT_HISTORY for reports on history entries.
attributeNamesSqlFile – the name of the file that contains the SQL query for finding attribute names. A file with this name must be placed in the folder
install_path/conf/defaults/sql/common/report_search_queries/.
attributeValuesSqlFile – the name of the file that contains the SQL query for finding attribute values for the above found attribute names. A file with this name must be placed in the folder
install_path/conf/defaults/sql/common/report_search_queries/.
searchResultSqlFile – the name of the file that contains the SQL query for finding records that match an attribute name and value selected from the result set of the above queries. A file with this name must be placed in the folder
install_path/conf/defaults/sql/common/report_search_queries/.

The component searches in the database on audit events.

Configuring a Report Indicator for Dirx Audit Manager

A report indicator is used for creating conditions, see the chapter “Using Reports Page” in the DirX Audit Manager Guide for details. Report indicator is stored in an JSON file according to the JSON schema https://audit.dirx.solutions/schemas/report/indicator-schema.json. To configure a report indicator, you need to:

Set up report indicator JSON properties
Extend DirX Audit Manager’s report indicators

Setting Report Indicator Properties

The JSON schema for a report indicator is structured into three main sections: itemUuid, metadata, and data.

itemUuid – the unique identifier for the indicator, represented as a version-4 UUID.

metadata – contains meta-information about the report indicator, including:

version – the version of the report indicator.
accessLevel – the access level required for the report indicator. For customization purposes, set this property to PUBLIC.

data – contains the actual configuration and structure of the report indicator:

id – the unique identifier for the indicator.
name and description – the name and description of the report indicator to be displayed by DirX Audit Manager when selecting and configuring an indicator.
indicatorQueryId – id of a referenced report indicator query
queryParameterValues – an array of query parameters, see the chapter “Configuring a SQL Query with Placeholders” for more information:
- queryParameterId – a unique identifier for the parameter.
- value – value of the given parameter.

Extending DirX Audit Manager Report Indicators

When you configure your own Indicator, you need to extend DirX Audit Manager’s report indicators.

The DirX Audit Manager’s report indicators are in the file:
install_path/conf/defaults/report-indicators/dxtIndicators.json

For adding or customizing a report indicator(s), see the chapter “Customizing Report Indicators and Indicator Queries for DirX Audit Manager” in the “General Customization” chapter.

{
  "indicators": [
    …
    {
      "itemUuid": "fe3a9947-9e74-4c81-8387-ead535f79b16",
      "metadata": {
      "version": "1.0.0",
      "accessLevel": "PRODUCT"
      },
      "data": {
        "id": "evn_added_users_in_5_days",
        "name": "indicator.def.evn_added_users_in_5_days.name",
        "description": "indicator.def.evn_added_users_in_5_days.description",
        "indicatorQueryId": "evn_added_objects_in_number_of_days",
        "queryParameterValues": [
          {
            "queryParameterId": "NUMBER_OF_DAYS",
            "value": "5"
          },
          {
            "queryParameterId": "OBJECT_TYPE",
            "value": "User"
          }
        ]
      }
    },
    …
  ]
}

The best way to define the Indicator is to copy one of the existing indicators and then change the values. It is necessary to change itemUuid to a unique valid value.

Configuring a Report Indicator Query for Dirx Audit Manager

A report indicator query is stored in an JSON file according to the JSON schema https://audit.dirx.solutions/schemas/report/indicator-query-schema.json. To configure a report indicator, you need to:

Set up report indicator query JSON properties
Extend DirX Audit Manager’s report indicator queries

Setting Report Indicator Queries Properties

The JSON schema for a report indicator query is structured into two main sections: metadata, and data.

metadata – contains meta-information about the report indicator query, including:

version – the version of the report indicator query.
accessLevel – the access level required for the report indicator query. For customization purposes, set this property to PUBLIC.

data – contains the actual configuration and structure of the report indicator query:

id – the unique identifier for the indicator query.
name and description – the name and description of the indicator query.
dxtDbType – the database type. Use DXT_DATA for a indicator query on audit events and DXT_HISTORY for indicator query on history entries.
queryPath – the reference to the .sql file.
resultDataType – type of a result retruned by the query.
queryParameters – defined parameters, which the query expects.
- id – a unique identifier for the parameter.
- name and description – the name and description of the report indicator query.
- parameterDataType – type of parameter passed as a placeholder to SQL query
- required – boolean value deciding if values must be provided

Extending DirX Audit Manager Report Indicator Queries

When you configure your own Indicator Query, you need to extend DirX Audit Manager’s report indicator queries.

The DirX Audit Manager’s report indicator queries are in the file:
install_path/conf/defaults/report-indicators/dxtIndicatorQueries.json

For adding or customizing a report indicator queries, see the chapter “Customizing Report Indicators and Indicator Queries for DirX Audit Manager” in the “General Customization” chapter.

{
  "indicatorQueries": [
    …
    {
      "metadata": {
        "version": "1.0.0",
        "accessLevel": "PRODUCT"
      },
      "data": {
        "id": "evn_added_objects_in_number_of_days",
        "name": "indicatorQuery.def.evn_added_objects_in_number_of_days.name",
        "description": "indicatorQuery.def.evn_added_objects_in_number_of_days.description",
        "dxtDbType": "DXT_DATA",
        "queryPath": "data/evn_added_objects_in_number_of_days.sql",
        "resultDataType": "number",
        "queryParameters": [
          {
            "id": "NUMBER_OF_DAYS",
            "name": "queryParameter.def.NUMBER_OF_DAYS.name",
            "description": "queryParameter.def.NUMBER_OF_DAYS.description",
            "parameterDataType": "number",
            "required": true
          },
          {
            "id": "OBJECT_TYPE",
            "name": "queryParameter.def.OBJECT_TYPE.name",
            "description": "queryParameter.def.OBJECT_TYPE.description",
            "parameterDataType": "string",
            "required": false
          }
        ]
      }
    },
    …
  ]
}

The best way to define the Indicator Query is to copy one of the existing indicator queries and then change the values.

Configuring a SQL Query with Placeholders

In the query element of a report definition, you refer to a file that holds a SQL query. The file must be located in the same folder as the report definition. DirX Audit executes the SQL query when it generates the report. It passes the query result to JasperReports.

The file contains a normal SQL query that must be recognized by the database you have deployed. Typically, you’ll use some variables or placeholders that are replaced at runtime. The most common are the start and end of the time range in which you are interested. They should not be fixed, but cover, for example, the previous month. Other use cases can include:

An option for whether or not to include only orphaned or disabled accounts.
A list of users whose data should be reported.
A list of privileges whose users should be reported.
A list of target systems whose accounts or groups should be reported.

These placeholders can be mandatory or optional. An auditor might provide exactly one value, multiple values or none.

These placeholders must be configured in the report definition as param or paramList sub-elements of control elements.

Use these placeholders in the SQL query to set a value of the form ${placeholder} instead of a real value. For example, use the placeholders ${WHEN_FROM} and ${WHEN_TO} for the beginning and end of a time range or ${UIDS} for a list of unique identifiers.

Pay attention to optional parameters. In most cases, it is not sufficient just to enter the placeholder name. If no values are given, they can render the query incorrectly or produce an unexpected result. The typical solution in these cases is to drop certain sections of the query that contain the optional parameter.

DirX Audit supports these use cases by leveraging the Apache FreeMarker open source template engine. See http://freemarker.org/docs/index.html for the Apache FreeMarker user guide. The conditional if statement is particularly useful for excluding sections depending on a parameter value. Here is a sample snippet for a parameter that represents lists of users occurring as a "what" in an audit event:

  <#if UIDS?? >
    and what_user.WHAT_UID in ${UIDS}
  </#if>

The condition for the WHAT_UID column is only included into the SQL query when the UIDS placeholder is not empty.

Check the queries delivered with the product for additional samples.

Setting up TIBCO Jaspersoft Studio

This section provides information on how to install and set up TIBCO Jaspersoft Studio in the DirX Audit environment.

Installing TIBCO Jaspersoft Studio

To install TIBCO Jaspersoft Studio:

Download Jaspersoft Studio from https://sourceforge.net/projects/jasperstudio/files/
Run the downloaded file to install TIBCO Jaspersoft Studio

You can now run TIBCO Jaspersoft Studio from the installation location.

Setting Up the TIBCO Jaspersoft Studio Classpath

TIBCO Jaspersoft Studio no longer requires a large, unique classpath for the entire application like iReport does. Each report is intended to be a part of a project. Each project has a classpath where jar libraries are added. To set up the TIBCO Jaspersoft Studio classpath for the selected project:

Start TIBCO Jaspersoft Studio.
Right-click on the project you selected.
Select Properties → Java Build Path → Libraries.
Click Add external JARs… . A file dialog opens.
Add the files:

install_path/Deployment/Manager/audit-manager-classic.war/WEB-INF/lib/DirXjdiscoverAPI-version.jar

install_path/Deployment/Manager/audit-manager-classic.war/WEB-INF/lib/dxt-common-config-version.jar

install_path/Deployment/Manager/audit-manager-classic.war/WEB-INF/lib/dxt-common-reports-support-version.jar

install_path/Deployment/Manager/audit-manager-classic.war/WEB-INF/lib/dxt-db-api-config-version.jar

install_path/Deployment/Manager/audit-manager-classic.war/WEB-INF/lib/dxt-db-apiquery-version.jar

install_path/Deployment/Manager/audit-manager-classic.war/WEB-INF/lib/dxt-db-api-raw-version.jar

install_path/Deployment/Manager/audit-manager-classic.war/WEB-INF/lib/dxt-db-schema-version.jar

install_path/Deployment/Manager/audit-manager-classic.war/WEB-INF/lib/dxt-dbv3-event-version.jar

install_path/Deployment/Manager/audit-manager-classic.war/WEB-INF/lib/dxt-dxi-digest-version.jar

install_path/Deployment/Manager/audit-manager-classic.war/WEB-INF/lib/dxt-history-api-version.jar

install_path/Deployment/Manager/audit-manager-classic.war/WEB-INF/lib/dxt-pep-api-version.jar

install_path/Deployment/Manager/audit-manager-classic.war/WEB-INF/lib/dxt-utils-lib-version.jar

install_path/Deployment/Manager/audit-manager-classic.war/WEB-INF/lib/log4j-version.jar

install_path/Deployment/Manager/audit-manager-classic.war/WEB-INF/lib/slf4j-api-version.jar

install_path/Deployment/Manager/audit-manager-classic.war/WEB-INF/lib/slf4j-log4j12-version.jar
Click Apply.

Creating a New Report

Creating a new report consists of the following tasks:

Creating the top-level page of the report
Creating a sub report

The following sections describe these tasks.

Creating the Top-Level Page

Creating the top-level page consists of the following tasks:

Creating the report file
Setting the classpath
Selecting the field list

Creating the Report File

To create the report file:

Start TIBCO Jaspersoft Studio.
Select File → New → Jasper Report.

The Report Wizard starts. It will guide you through the following steps:

1. Report Templates
2. Report File
3. Data Source
4. Finish

Select a template; for example, BlankA4. Click Next.
Enter MyTableReport as the report name. You can select a parent folder where the report will be created. Click Next. (Alternatively, once you finish with your changes and save the report, you can just copy your report to the folder of your choice.)
In the Data Adapter drop-down list, select One Empty Record - Empty Rows. You must specify the data source later. Click Next.
Click Finish. If no errors occur, the new report is created.

Setting the Classpath

To set up the classpath, follow the instructions in “Setting Up the TIBCO Jaspersoft Studio Classpath” if you have not already done so.

Setting the Data Adapter

To set the data adapter:

Switch to the Repository Explorer.
Right-click Data Adapters and choose Create Data Adapter.
The Data Adapter Wizard opens.
Choose Database JDBC Connection and follow the wizard to specify your database connectivity. Pay special attention to defining the database connectivity when your audit events and history entries are stored in different databases.

Defining Report Parameters

To define report parameters:

In Outline, right-click Parameters and then select Create Parameter.
Provide Name, Class and additional properties of the new parameter.
Repeat the procedure for additional report parameters.

Selecting the Field List

To select the field list:

In Outline, right-click the name of your report and then select Dataset and Query …
Click the Query tab.
Select the data adapter you have defined in “Setting the Data Adapter”.
Select sql in Language.
Place your SQL query in the Texts. The query should correspond to your SQL query file as defined in the “Setting Report Definition Elements for DirX Audit Manager” or in the “Setting Report Definition Elements for DirX Audit Manager Classic” and in the “Configuring a SQL Query with Placeholders”.

The query cannot contain any Apache FreeMarker elements and placeholders must be transferred to JasperReports parameters set in the “Defining Report Parameters”.
This means that ${placeholder} must be replaced with $P{placeholder} in the query. The query can be simplified. In the TIBCO Jaspersoft Studio, it serves only to support designing the report output format. The query will not be applied during the report execution in DirX Audit Manager or DirX Audit Manager Classic and DirX Audit Server.
Click Read Fields to automatically read a list of report fields from the SQL query. Review the automatically generated data type for each field.
Now the list of fields is available in the Outline view under the Fields node. You can drag these fields to the report layout area and then set up your report as required. See the TIBCO Jaspersoft Studio and TIBCO JasperReports documentation for more information.

Don’t forget to save your report definition from time to time. You can also see what your current report looks like by clicking the Preview tab.

Creating a Subreport

Top-level pages can contain subreports, which should be used for parts that may occur multiple times per audit message, especially the Extension, What and What Details sections in audit events. To create subreports:

Create the subreport element in the current page.
Create the subreport definition as a separate TIBCO JasperReports file (JRXML).

Creating the Subreport Element

You need to create a subreport element in your table layout for each subreport. For each of these subreport elements, you need to assign the corresponding TIBCO Jaspersoft Studio file that contains the subreport definition. This section shows how to create a What section in a top-level report and then display the field What – Name.

First, we will create the subreport element in our top-level page:

Start TIBCO Jaspersoft Studio. Click File → Open File … and then select the JasperReport to which you want to add subreport.
Select the subreport item in the Palette tab and then drag it to the report pane. A wizard opens.
Select Just create the subreport element and then click Finish. The new subreport element is visible.
Adjust the size and position of the subreport element.
Select the element to open its properties and then select the Subreport tab.
In Expression, enter the string $P{SUBREPORT_DIR} + "WhatReport.jasper".
The "WhatReport.jasper" expression specifies the external TIBCO JasperReports file with the definition of the subreport.
Edit Data Source Expression.
In Connection Expression, enter the string $P{DXT_SUBREPORT_CONNECTION}.
Add a parameter reference to the subreport:
- Click Edit Parameters.
- In the Subreport Parameters dialog, click Add. The Parameter Configuration Dialog is opened.
- Fill in the Parameter Name to the new parameter name WHEN_FROM.
- Click the edit button of the Parameter Expression. A new Expression Editor dialog opens.
- Enter $P(WHEN_FROM) to create an expression for the parameter, and then click Finish.
- Click OK to close the Parameter Configuration Dialog.

If you want to create additional subreport elements, copy an existing subreport and then simply change the Expression field in the Subreport tab of the element’s Properties view. This action changes the file name for the TIBCO JasperReports file.

Creating the Subreport TIBCO JasperReports File

Now we will create a TIBCO JasperReports definition file (a JRXML file) for the subreport. Name it WhatReport.jrxml.

Follow the steps in the “Creating the Top-Level Page”. Now you can place the fields from the sub-level within this page (in this case, the What level). To create, for example, the What – Name field, simply create a field with the expression $F{Name}.

Modifying a Report

Use TIBCO Jaspersoft Studio to modify a report definition:

Select File → Open from the menu bar.
Navigate to the file you want to change.
Select the file and then click Open.

Now let us make some typical changes.

Changing the Report Title

To change the report title:

Select the text field and change it, for example, to $R{report.title.myreportcopy}.
Create a new file install_path/conf/defaults/reports/reportName/reportName.properties (or reportName_de.properties for reports in German, reportName_fr.properties for reports in French) to store new keys and labels. Create a new line containing: report.title.myreportcopy = My Report Copy, where My Report Copy can be easily replaced by any string.

Changing the Color of the Column Headers

All data fields have style properties. You simply change the property value to change the field.

In the Design view, click on a field that you want to change.
In the Properties tab, select Appearance.
In the Color section, you can set Forecolor and Backcolor by clicking on the square that shows the color.
Select your color and then click OK. The color of the field changes.

You can now change the top-level page or sub-reports using TIBCO Jaspersoft Studio features. See the TIBCO Jaspersoft Studio documentation for more information.

Note: if you create a new field and/or your color does not change, it’s because the Transparent flag is set. To clear the Transparent flag:

In the Properties tab, select Appearance.
In the Color section, uncheck Transparent.

Changing Common Parts of Reports

Reports have defined common parts, which are reused as subreports. These are page header, page footer and no data message and can be customized as is described in the section “Configuring Custom Files” in reports folders:

Common shared subreport files:
install_path/conf/defaults/reports/_common_shared/_common_pageHeader.jrxml
install_path/conf/defaults/reports/_common_shared/_common_pageFooter.jrxml
install_path/conf/defaults/reports/_common_shared/_common_noData.jrxml

Adding JasperReports Templates to Audit Analysis for Dirx Audit Manager Classic

You can add your own TIBCO JasperReports templates to DirX Audit Manager Classic’s Audit analysis. To add a JasperReport template to the Audit analysis:

Navigate to install_path/conf/defaults/reports/. Create a new folder that starts with EventMonitor; for example, EventMonitorTest.
In TIBCO Jaspersoft Studio, create a new report with the same name as the folder you created in the previous step. For example, EventMonitorTest.jrxml.
Customize your report. The Audit analysis reports are based on Java Bean, not a SQL query. See EventMonitorAll, EventMonitorPlain and EventMonitorStd reports and their definitions. For more details on the Java Bean API, see the chapter “Working with View Type APIs”.
Make sure that the name in the Outline view is same as the name of the report.
Save the report to your TIBCO Jaspersoft Studio workspace.
Navigate to your workspace. Right-click on your report (in this case, EventMonitorTest.jrxml) and then click Copy.
Navigate to your new folder – for example, install_path/conf/defaults/reports/EventMonitorTest - and then paste your report file here.
Make sure that the name of your report is the same as the name of the folder in which it is located.

If you cannot see your new template in DirX Audit Manager Classic / Audit analysis / Report / Template list, restart the Apache Tomcat service used for DirX Audit Manager Classic.

Note, that you can add or customize these reports for all and/or specific tenant as described in the chapter “Configuring Custom Files”.

Adding JasperReports Templates to Audit Analysis for Dirx Audit Manager

You can add your own TIBCO JasperReports templates to DirX Audit Manager’s Audit Analysis. To add a new report template to the Audit analysis:

Navigate to install_path/conf/defaults/reports/. Create a new folder, for example, EvnAuditAnalysisExportTest.
In TIBCO Jaspersoft Studio, create a new report with the same name as the folder you created in the previous step. For example, EvnAuditAnalysisExportTest.jrxml.
Customize your report.
Make sure that the name in the Outline view is same as the name of the report.
Save the report to your TIBCO Jaspersoft Studio workspace.
Navigate to your workspace. Right-click on your report (in this case, EvnAuditAnalysisExportTest.jrxml) and then click Copy.
Navigate to your new folder – for example, install_path/conf/defaults/reports/EvnAuditAnalysisExportTest - and then paste your report file here.
Make sure that the name of your report is the same as the name of the folder in which it is located.
Navigate to install_path/conf/defaults/reports-definitions/EvnAuditAnalysisExport/EvnAuditAnalysisExport.json and extend the reportTemplates array with new template.
Here is an example of a new template in reportTemplates:

…
{
  "id": "EvnAuditAnalysisExportTest",
  "label": "EvnAuditAnalysisExportTest_Label",
  "path": "EvnAuditAnalysisExportTest"
},
…

If you cannot see your new template in DirX Audit Manager / Audit analysis / Report / Report templates, restart the Apache Tomcat service used for DirX Audit Manager.

Note, that you can add or customize these reports for all and/or specific tenant as described in the chapter “Configuring Custom Files”.

Adding JasperReports Templates to History tab for Dirx Audit Manager Classic

You can add your own TIBCO JasperReports templates to DirX Audit Manager Classic’s History tab.To add a JasperReport template to the History tab:

Navigate to install_path/conf/defaults/reports/. Create a new folder that starts with HistoryEntries; for example, HistoryEntriesTest.
In TIBCO Jaspersoft Studio, create a new report with the same name as the folder you created in the previous step. For example, HistoryEntriesTest.jrxml.
Customize your report. The History reports are based on Java Bean, not a SQL query. See HistoryEntries and HistoryEntriesPlain reports and their definitions.
Make sure that the name in the Outline view is same as the name of the report.
Save the report to your TIBCO Jaspersoft Studio workspace.
Navigate to your workspace. Right-click on your report (in this case, HistoryEntriesTest.jrxml) and then click Copy.
Navigate to your new folder – for example, install_path/conf/defaults/reports/HistoryEntriesTest - and then paste your report file here.
Make sure that the name of your report is the same as the name of the folder in which it is located.

If you cannot see your new template in DirX Audit Manager Classic / History / Report / Template list, restart the Apache Tomcat service used for DirX Audit Manager Classic.

Note, that you can add or customize these reports for all and/or specific tenant as described in the chapter “Configuring Custom Files”.

Adding JasperReports Templates to History tab for Dirx Audit Manager

You can add your own TIBCO JasperReports templates to DirX Audit Manager’s History. To add a new report template to the History:

Navigate to install_path/conf/defaults/reports/. Create a new folder, for example, HstHistoryExportTest.
In TIBCO Jaspersoft Studio, create a new report with the same name as the folder you created in the previous step. For example, HstHistoryExportTest.jrxml.
Customize your report.
Make sure that the name in the Outline view is same as the name of the report.
Save the report to your TIBCO Jaspersoft Studio workspace.
Navigate to your workspace. Right-click on your report (in this case, HstHistoryExportTest.jrxml) and then click Copy.
Navigate to your new folder – for example, install_path/conf/defaults/reports/HstHistoryExportTest - and then paste your report file here.
Make sure that the name of your report is the same as the name of the folder in which it is located.
Navigate to install_path/conf/defaults/reports-definitions/HstHistoryExport/HstHistoryExport.json and extend the reportTemplates array with new template.

Here is an example of a new template in reportTemplates:

…
{
  "id": "HstHistoryExportTest",
  "label": "HstHistoryExportTest_Label",
  "path": "HstHistoryExportTest"
},
…

If you cannot see your new template in DirX Audit Manager / Audit analysis / Report / Report templates, restart the Apache Tomcat service used for DirX Audit Manager.

Note, that you can add or customize these reports for all and/or specific tenant as described in the chapter “Configuring Custom Files”.

Designing Reports for CSV Format

Modify an Existing Report Template

To modify an existing report template for CSV format:

Copy the report template file and extend its name with the _csv suffix.
Remove Title, Page Header, Page Footer, Last Page Footer, Summary, No Data and Background bands.
Modify the Report Page properties (Page Height, Page Width, Page Orientation, Bottom margin, Left Margin, Page Width, Right Margin). Height, width and margins can be set to 0. Page orientation is recommended to be Landscape.
Set the report property net.sf.jasperreports.print.keep.full.text to true in the jrxml file: <property name="net.sf.jasperreports.print.keep.full.text" value="true"/>
Edit the Detail band and optionally also the Group Header and/or the Group Footer bands.
Check the Print Repeated Values (isPrintRepeatedValues) property for all text fields.

See Designing Reports for CSV Export, https://community.jaspersoft.com/wiki/designing-reports-csv-export, for more details, including how to set a different delimiter; for example, a semicolon.

Use a Common CSV Format Report Template for Dirx Audit Manager Classic

To use common CSV format template:

Set reportTemplate element described in chapter “Setting Report Definition Elements for DirX Audit Manager Classic” to reports/_common_template_csv/_common_template_csv to reference reusable common CSV format template. This will present all columns from SQL query used for specific report.
Optionally, to generate only desired columns, add PickListCsvColumnsControl control named DXT_SELECTED_COLUMNS to report definition with initial values set to column aliases in report SQL query.
Here is an example, in which SQL query returns three columns named USER_NAME, ORGANIZATIONAL_UNIT and MANAGER:

<control
  controlType="PickListCsvColumnsControl"
  label="report.param.select_columns" >
  <params>
    <paramList
      name="DXT_SELECTED_COLUMNS"
      type="java.lang.String"
      passToReport="true" >
      <initialValue>USER_NAME</initialValue>
      <initialValue>ORGANIZATIONAL_UNIT</initialValue>
      <initialValue>MANAGER</initialValue>
    </paramList>
  </params>
</control>

Use a Common CSV Format Report Template for Dirx Audit Manager

To use common CSV format template:

Set path in reportTemplates element described in the chapter Setting Report Definition Elements to reports/_common_template_csv/_common_template_csv to reference reusable common CSV format template. This will present all columns from SQL query used for specific report.
Optionally, to generate only desired columns, add array-picklist-modal control named DXT_SELECTED_COLUMNS to report definition with initial values set to column aliases in report SQL query.

Here is an example, in which SQL query returns three columns named USER_NAME, ORGANIZATIONAL_UNIT and MANAGER:

{
  "key": "DXT_SELECTED_COLUMNS",
  "paramsList": [
    {
      "name": "DXT_SELECTED_COLUMNS",
      "passToReport": true,
      "type": "java.lang.String"
    }
  ],
  "formlySchema": {
    "type": "object",
    "widget": {
      "formlyConfig": {
        "type": "array-picklist-modal",
        "templateOptions": {
          "label": "report.param.select_columns",
          "options": [
            {
              "label": "USER_NAME",
              "value": "USER_NAME"
            },
            {
              "label": "ORGANIZATIONAL_UNIT",
              "value": "ORGANIZATIONAL_UNIT"
            },
            {
              "label": "MANAGER",
              "value": "MANAGER"
            }
          ],
          "preselectAll": true
        }
      }
    },
    "required": true
  }
}

Solving Problems

This section provides tips and tricks to ease report creation, test and execution, including information on how to handle:

Report design errors
Problems with report definition changes
Report execution errors

Handling Report Design Errors

After designing the report, run the compiler and check the output for errors. Double-click an error message in the Report State window to open the definition with the error condition. Correct the error and run the compiler again.

If compilation is successful without errors, you can save the record and test it.

Handling Problems with Report Definition Changes

If the DirX Audit Manager does not recognize changes you have made to the report definition, try this procedure:

Navigate to the folder where your report definitions are stored.
Delete all *.jasper files.
Run your report in DirX Audit Manager again. This action forces recompilation of the JRXML files.

Handling Report Execution Errors

When you test your reports, you may encounter the error message "Transaction has failed, please try again." If you receive this error, check the Apache Tomcat Application Server log file(s) for error messages:

Navigate to the folder tomcat_install_path/logs.
Check the file dirxaudit-manager.log for error messages and try to solve the problem.
A typical error is:
java.lang.NoClassDefFoundError: org/jfree/util/classname

JasperReports has many features and this message indicates that a Java library is not available.
Check the website http://www.findjar.com/ and search for the library classname.
If found, download it and store it under the following path:
tomcat_install_path/lib

Warning: If the library already exists, rename it with an extension that is not jar. This action allows you to reset the library if something goes wrong.
Restart the Apache Tomcat Application Server and run your report again.

About the Reports Overview

The Reports Overview file is designed to help you identify the most suitable report for your data needs. It provides a categorized list of available reports, including:

Report groups
Tags and descriptions
Source data and output format
The DirX Audit version in which each report was introduced

Additionally, the overview links each report to:

Its configuration file in the install_path/conf/defaults/report-definitions/ folder
Sample report files located in the install_media/Additions/Data/SampleReports folder, where the overview file itself is also stored