Templates and Input Files

Artifacts that make up a complete report definition need to be stored in LDAP entries. For compatibility reasons and for supporting report development, all or a part of them can be stored in the file system. See chapter ‘Developing Reports’ for more details.

In the DirX Identity LDAP domain, the Jasper-based report templates are stored along with the XSLT-based reports. So, the default reports delivered out-of-the-box are in

Domain/Configuration/Reports/Default

For better management and easier overview, the Jasper-based reports are stored in the subfolder Jasper-based Reports. Unlike the XSLT-based reports, there are no Jasper-based reports specific for target system types.

Artifacts that make up a complete report definition are:

Report template or report output format - A report template prescribes the structure and layout of a report. The report template is in XML format and stored in an LDAP entry. In the report design phase, it can also be stored in a file. The file needs the suffix .jrxml.
Images – A report template may refer to images, for example, a company logo. These entries are stored in LDAP in the subfolder Domain/Configuration/Reports/Default/_Images.
Style templates – The product provides a couple of style templates, for example, for blue, green or yellow. You select them at the beginning of a report template. These entries are stored in LDAP in the subfolder Domain/Configuration/Reports/Default/_StyleTemplate.
Internationalization (i18n) – The keys and their translations to the respective language are stored in LDAP entries in the subfolder Domain*/Configuration/Reports/Default/Nationalization*. The section ‘Error! Reference source not found.Error! Reference source not found.’ gives more details on the LDAP entries and the format.
DirX Identity specific report configuration – An XML document that defines the data to be filled into the report, the output type (PDF, XLS, etc), the i18n bundle name and the output file name. The configuration is stored in the same LDAP entry as the report template. When used in design phase, it can be stored in an XML file.

Report Templates

A report template contains all the information about the structure and the aspects of the document that will be generated when the data is provided. This information contains the position and content of various text or graphic elements, their appearance, the custom calculations, the data grouping and data manipulations that should be performed when the data are generated, and so on.

For details on a report template, see the Jaspersoft documentation, especially the chapter “Report Template Structure” and the subsequent ones in [4] (see “Helpful Resources” in this document).

A report template is stored in LDAP in a report entry of object class dxrReport. Identity Manager presents it in its Format tab and stores it in the dxrFormat LDAP attribute. This is the same kind of entry and attribute that holds the output format of XSLT-based reports.

Subreport templates are also stored in LDAP entries of object class dxrReport. They are distinguished from the main template by the value jasperSubReport in their LDAP attribute dxrType. In subreport entries, the configuration (attribute dxrConfig) is ignored and can be left empty. The subreport entries MUST be stored in the same folder as their main templates.

Please pay attention to the artifacts described in the next sections.

Parameters

Parameters are defined at the beginning of a report template. They can be output to the report document and are referred to by $P{parameter_name}.

Some parameters are set from the DirX Identity report generator at report production time, including SearchBase, SearchScope, SearchFilter, REPORT_LOCALE and all the properties listed in the <consumer> section of the report configuration.

Other important parameters refer to the document template: DIRX_STYLE_TEMPLATE_DIR (leave this unchanged) and DIRX_STYLE_TEMPLATE_FILE. Change the value of this file parameter if you want to exchange the template style; for example, from DXT71_Styles_blue to DXT71_Styles_orange.

Subreports

Subreports are typically used when printing a variable list of information in a main report. Examples are the roles or groups assigned to a user.

A subreport is referred from its containing main template by an XML element <subreport>. Its <subreportExpression> needs to contain the name of the subreport template. In DirX Identity, this name must be defined as a parameter and is filled by the DirX Identity report generator at report production time. The name MUST match exactly the RDN of the LDAP subreport entry.

For example, the subreport for a user’s roles:

The parameter is defined as

<parameter name="Users_with_all_properties_Roles" class="net.sf.jasperreports.engine.JasperReport"/>

… and referred in <subreport> as:

<subreportExpression>
<![CDATA[$P{Users_with_all_properties_Roles}]]>
</subreportExpression>

The LDAP entry must be stored in the same folder as the main template and named as the parameter; in our example, it needs to be:

cn=Users_with_all_properties_Roles,cn=Users_with_all_properties,cn=Users,…

Some parameters should be passed to the subreport: REPORT_LOCALE, DIRX_STYLE_TEMPLATE_DIR, DIRX_STYLE_TEMPLATE_FILE, REPORT_RESOURCE_BUNDLE.

Report Configuration

A report configuration is an XML document that defines

The data to be filled into the report
The output type (PDF, XLS, etc.)
The i18n bundle name
The output file name
The style template
The images folders

The configuration is stored in the same LDAP entry as the report template in the LDAP attribute dxrConfig. The configuration is nearly the same as the one used for XSLT-based reports.

A Jasper-based report is identified by the XML attribute type="jasper" in the top XML element <report>.

The <producer> section contains the search parameters that identify the set of entries that are to be filled into the report. In its sub-element <search>, these are the attributes base, filter, scope, attributes, sizelimit and order. They are mapped directly to the corresponding attributes of an LDAP search.

Note: Due to the way in which DirX Identity Storage components behave, the list of LDAP attributes need not necessarily be complete. But it supports performance if they are. If an attribute is requested in the report template and is not within the list of search attributes, a DirX Identity Storage object performs an extra LDAP read.

The output format is specified by an XML element of the output type name in uppercase. For PDF output, the element must be <PDF>, for Excel output it must be <XLS> or <XLSX>.

Its sub-element <FILE><consumer> contains sub-elements <property> for setting various parameters.

output file name:

<property name="file" value="Users_with_all_properties.pdf"/>

resource bundle name (see the section “Nationalization“)
```
<property name="i18nBundle" value="messages"/>.
```

Folder and name of style template LDAP entry (or file)

<property name="DIRX_STYLE_TEMPLATE_DIR" value="STYLE_TEMPLATE_DIR_LDAP_DEFAULT:"/>.
<property name="DIRX_STYLE_TEMPLATE_FILE" value="DXT71_Styles_blue"/>.

If you want to use custom styles, place them under folder “cn=_StyleTemplate, cn=Reports,cn=Customer Extensions,cn=Configuration,cn=<domain name>” and configure template directory

<property name="DIRX_STYLE_TEMPLATE_DIR" value="DIRX_STYLE_TEMPLATE_DIR_CUSTOM:"/>.

Identifiers for default and custom image containers. Don’t change them.

If you want to use custom images, place them in folder“cn=_Images, cn=Reports,cn=Customer Extensions,cn=Configuration,cn=<domain name>”.

Nationalization

Reports can be localized by leveraging the Java internationalization support. Format and naming of the message properties must follow the Java conventions for internationalization (see https://www.oracle.com/technetwork/java/javase/tech/intl-139810.html). For example, the English text for the key ‘sn’ must be denoted as:

sn=Last name

The translated key can be referred to from the report template by the placeholder $R; for example, $R{sn}.

The report engine first searches the appropriate message texts in LDAP. If it doesn’t find them, it searches in the file system.

In LDAP it searches below the folder “cn=Configuration,cn=<domain name>”. The default message texts are delivered below folder

“cn=Nationalization,cn=Jasper Based Reports,cn=Default,cn=Reports,cn=Configuration,cn=<domain name>”.

Custom messages should be located below folder

“cn=Reports,cn=Customer Extensions,cn=Configuration,cn=<domain name>”.

The attribute cn (displayed in Identity Manager as Name) of a nationalization entry must match the configuration property i18nBundle. Messages for a different language, but same i18nBundle have to be placed into different folders, for example “cn=messages,cn=de, …”. The language is stored in the attribute dxrLanguage, displayed in Identity Manager in field Language. If the report engine doesn’t find an entry with the requested language, it takes English as default.

The message texts are stored as one long string in attribute dxrMessage. This allows you to easily copy all the messages from a simple text file to the LDAP entry.

If not found in LDAP, the report engine searches the message properties files in the installation’s reports folder (install_path*/reports*) in the subfolder i18n. For a configured i18Bundle ‘messages’ the default file name is messages.properties. Language-specific files suffix the bundle name with a locale-specific identifier. For example, the file name is messages_en.properties for English and messages_de.properties for German.

Template Fields and [Virtual] Attributes

In the report template, field names identify the properties of the data source entries from which the information is taken. For example, the following XML element specifies the surname property with a Java value type String:

<field name="sn" class="java.lang.String"/>

Each attribute to be printed in the output document must be declared by such a <field> element. When reading this property from the data source, the Jasper report engine expects exactly the configured return type and stops processing the report if it is different.

A field is referred to from the template by the $F placeholder, for example $F{sn}.

The DirX Identity service layer classes provide a number of “virtual attributes”. They are not real LDAP attributes that can be found in the LDAP schema, but are supported by individual classes in their method getProperty(<name of attribute>). They are used for various purposes, especially to implicitly read associated LDAP entries from LDAP. As an example, the SvcUser class retrieves the user-role assignments of its user when it is called with getProperty(roles.assigned).

These virtual attributes can be leveraged in the report templates and are very helpful when including associated entries of an entry selected by the search in the report configuration. The associated document virtualAttributes.pdf lists DirX Identity service layer classes and the virtual attributes of attribute prefixes they support.

For example: the class SvcUser passes getProperty requests for attribute names starting with “roles.” to a controller class SvcUserRoleAssCtrl, which returns for attributes such as “roles.assigned” the role assignments of the user.

Note these very important points:

In the report templates, replace the “.” in virtual attribute names with “_”. For example, use “roles_assigned” rather than “roles.assigned”. The reason is that the Jasper report engine interprets this attribute so that it first tries to get the property “roles”, expects an object and then gets the property “assigned” from it. This action fails because the Service layer class does not return anything for the property “roles”. Behind the scenes, the DirX Identity custom data source transforms back ‘_’ to ‘.’ and passes the correct attribute name “roles.assigned” to the DirX Identity class.
Virtual attributes are always returned as a list even if they contain only one value. See the section “Utility Methods” for information on how you can easily extract the first value from this list.

Utility Methods

To simplify template definition, you can use utility methods delivered with the product. They leverage the Jaspersoft feature to call methods of Java classes from within a report.

First, you should define a parameter as an alias for the full class name of the utility class. This allows you to use the short alias rather the long class name later in the report.

<parameter name="Utils" class="siemens.dxm.storage.report.jasper.Utils"/>

Then in a text field you can access the method entering the alias followed by the method name, separated by ‘.’ like so:

$P{Utils}.firstElementOrEmptyStringFrom($F{manager.cn})

This example calls the method firstElementOrEmptyStringFrom passing the value of the virtual attribute manager.cn.

Here is the list of utility methods for the class siemens.dxm.storage.report.jasper.Utils:

firstElementOrEmptyStringFrom

The method firstElementOrEmptyStringFrom expects as the only parameter a list of objects. It returns either an empty string if the list is null or empty or the first element in the list.

firstElementOrNullFromList

The method firstElementOrNullFromList expects as the only parameter a list of objects. It returns either null if the list is null or empty or the first element in the list.

toStringOrNullFromObject

The method toStringOrNullFromObject expects as parameter an object and returns null if the object is null or returns the stringified value of the object: object.toString.

printObjectList

This method expects a list of objects and returns their stringified, comma-separated values.

printObjectArray

This method expects an array of objects and returns their stringified, comma-separated values.

createLocale

This method expects 3 string parameters for language, country and variant and returns the corresponding Java Locale. Default is Locale.UK.

formattedTime

The method formattedTime expects the following parameters:

A GeneralizedTime object.
The format string as used in Java class SimpleDateFormat. It gives the output pattern telling which part of the date and time should be included.
The locale affecting the output format.

The method returns the formatted date time string for the given time or null if the object is missing.

formattedTimeFromList

The method formattedTimeFromList expects the following parameters:

A list of GeneralizedTime objects.
The format string as used in Java class java.text.SimpleDateFormat. It gives the output pattern telling which part of the date and time should be included.
The locale affecting the output format.

The method returns the formatted date time string for the first element of the input list or null if the list is empty.

formatDateTime

This method expects the following parameters:

The format string as used in Java class java.text.SimpleDateFormat. It gives the output pattern telling which part of the date and time should be included.
The locale affecting the output format.
A java.sq.Timestamp to be formatted.

The method returns the formatted date time string for the given time or null if the timestamp is missing.

whyDetailsToString

This method expects a Java Set of strings and returns their values as comma-separated list.

getFirstValueFromDn

This method expects a DN string as an input parameter and returns the first RDN (relative DN); that is, the entry’s name or null if the DN is missing or in the wrong format.

convertDn2Path

This method expects a DN string and returns a string with the path notation as known from Unix file paths. For example: a DN “cn=users,cn=My-Company” would be returned as “My-Company/users”.

parseCommonName

This method expects a DN string and returns the leading cn RDN.

matchPattern

This method expects the following string parameters:

The string for which the pattern is to be applied.
A regular expression.

It returns the result of applying java.util.regex.Matcher on a pattern created from the regular expression on the input string.