Howto: Generate CSV or PDF reports with univention-directory-reports

Knowledge Base Community
, , , , ,
1

How to: Generate CSV or PDF reports with univention-directory-reports

Summary

The tool univention-directory-reports can be used to generate structured reports for UCS directory objects such as users, groups, or computers.
Depending on the selected template, reports can be created for example in CSV or PDF format.

This article explains how to list available report types and how to generate a report for a large number of objects via the command line.

Environment

Verified with:

ii  python3-univention-directory-reports  14.4.0
ii  univention-directory-reports          14.4.0

Introduction

univention-directory-reports uses UDM modules as input (e.g. users/user, groups/group, computers/computer).
A report definition (e.g. CSV Report or PDF Document) determines the output format and layout.

Reports are typically written to /tmp unless another output directory is specified.

Command reference (--help)

For completeness, below is the help output of the tool:

Usage: univention-directory-reports -m <module> [options] dn1 dn2 ...

Options:
  -h, --help            show this help message and exit
  -u USERDN, --user=USERDN
                        User-DN for simple LDAP access
  -p PASSWORD, --password=PASSWORD
                        Password for simple LDAP access
  -H HEADER, --header=HEADER
                        File containing the header for the report
  -F FOOTER, --footer=FOOTER
                        file containing the footer for the report
  -s SERVER, --server=SERVER
                        LDAP server [ucs5primary.univention.intranet]
  -b BASE, --base=BASE  LDAP base [dc=univention,dc=intranet]
  -m MODULE, --module=MODULE
                        admin module defining the report to generate
  -r REPORT, --report=REPORT
                        Name of the report to use [PDF Document]
  -l, --list            List names of available reports
  -c CONFIG, --config=CONFIG
                        location of the configuration file
                        [/etc/univention/directory/reports/config.ini]
  -d DEBUG, --debug=DEBUG
                        if given then debugging is activated and set to the
                        specified level
  --output-dir=OUTPUT_DIR
                        location of the output report file
  --output-name=OUTPUT_NAME
                        custom output report file name

List available reports

To see which reports are available per module, run:

univention-directory-reports -l

Example output:

Reports for module: computers/computer
 - CSV Report
 - PDF Document
Reports for module: groups/group
 - CSV Report
 - PDF Document
Reports for module: users/user
 - CSV Report
 - PDF Document

Basic command structure

univention-directory-reports -m <module> -r "<report name>" <DNs>

Where:

  • module → UDM module (e.g. users/user)
  • report name → template to use (e.g. "CSV Report")
  • DNs → one or more LDAP distinguished names

Example: Create a CSV report for all users

On the reference system, the following UCR variable is set by default:

directory/reports/templates/csv/user1: users/user "CSV Report" /etc/univention/directory/reports/default users.csv

With this template in place, a CSV export of all users can be generated as follows:

univention-directory-reports -m users/user -r "CSV Report" \
$(udm users/user list | grep DN: | sed -ne 's/^DN: \(.*\)$/\1/p')

Example result:

The CSV Report has been created: /tmp/univention-directory-reports-mpcu5i18.csv

This works well even for environments with several thousand objects (e.g. ~2000 test users).

Example: Create a PDF report

univention-directory-reports -m users/user -r "PDF Document" \
$(udm users/user list | grep DN: | sed -ne 's/^DN: \(.*\)$/\1/p')

Optional parameters

Commonly used options include:

Option Description
--output-dir Define where the file will be written
--output-name Custom filename
-s LDAP server
-b LDAP base
-d Enable debugging

Example with custom path and filename:

univention-directory-reports -m users/user -r "CSV Report" \
--output-dir /root --output-name users.csv \
$(udm users/user list | grep DN: | sed -ne 's/^DN: \(.*\)$/\1/p')

Notes & Best Practices

  • The command requires access rights to read the corresponding LDAP objects.
  • For very large environments, command substitution with many DNs may hit shell limits. In such cases, process objects in batches.
  • Templates can be customized under /etc/univention/directory/reports/ - How-to: Create own directory reports
1 Like