> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/administration-guide/reports/overview.md).
# Report builder overview
What the report builder is made of — entities, backends, data sources, reports, runs, schedules and retention — the rules every report obeys, the limits, and who sees what. No settings on this page.
This page is for anyone who has just heard of the report builder: the analyst who will build reports, the manager who will receive them, the operator who will keep the service running. It gives you the vocabulary the other pages use, the handful of rules every report obeys, and the limits. It changes nothing; every setting is on a task page linked from here.
## What this is, and when you need it
The report builder answers questions about identity and access data without anyone writing a query: who holds which role, which logins have not been used for 60 days, which accounts in a managed system belong to nobody. You pick the data in a catalog, choose fields, filters and grouping in a wizard, and OpenIAM produces a CSV (comma-separated values) or Excel file, on demand or on a schedule, and e-mails it if you ask.
You are in the wrong place if you want one of the **shipped reports** of the older reporting engine, which still run from **Reports** in SelfService and are listed in [Shipped reports](/administration-guide/reference/shipped-reports.md). The report builder is a separate feature with its own menu under Webconsole → **Audit & Reports** → **Reports**, its own `reporting` database and its own service, `report-manager`. Nothing described here touches the older engine.
## The vocabulary
### Entities and fields
An **entity** is one kind of record a report can be about: a **User**, a **Login**, a **Role**, a **User role membership**, a **Certification item**, an **Audit event**. Each entity has **fields** (First name, Employee type, Last login, Risk) and **relationships** to other entities (a User role membership points to one User and one Role). The entities, their fields and their relationships are the **Data Catalog**. They are a facade over the underlying storage: a User is read from the `USERS` table and an Audit event from the `auditlog` index, but a report author never sees a table or an index, only the entity.
Every field has one of five types, which decides which filter operators and which calculations it accepts: **Text**, **Number**, **Yes/No**, **Date** and **Date and time**. The catalog also marks each field as filterable, sortable and groupable, and marks a few as personal data. See [Browse the Data Catalog](/administration-guide/reports/data-catalog.md).
### Two backends
Every entity lives on one of two backends, shown as a chip on its catalog card:
| Backend | What it reads | Entities on it |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| **Database** | A relational source database (`openiam`, `certification`, and others an operator lists), through a read-only reporting user, in any of the four supported dialects | User, Login, Role, Group, Resource, the memberships between them, Certification campaign and item, and more |
| **OpenSearch** | A search index, read page by page with a point-in-time cursor | Audit event, SoD violation, Orphan account, Provisioning result |
The backend is why some entities cannot be combined: a report is compiled into one SQL (Structured Query Language) statement or one OpenSearch search, never both. See the rules below.
### Data sources
A **data source** says which entities a report reads, how they are joined, and which rows are kept before the report's own fields and filters are applied. There are three kinds:
| Kind | Who builds it | Where it lives | Use it when |
| --------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| **Entities** (inline) | Anyone, in the wizard or the designer | Inside one report; never listed | The report is the only thing that needs this combination |
| **View** | Anyone, from the Data Catalog or with **Save as view** in the designer | The Data Catalog's **Views** tab, with its own name and owner | Several reports should share the same entities, joins and filters; changing the view changes them all |
| **SQL data source** | Super administrators only | The **Views** tab, with a **Not subject to field and row filters** badge | The question cannot be expressed in the catalog and an administrator vets the statement |
The catalog's access rules apply to the first two. An SQL data source runs as written, so its files always count as personal data for retention. See [Views and SQL data sources](/administration-guide/reports/views-and-sql-sources.md).
### Reports and layouts
A **report** is a data source plus a **layout**: the fields in order with their column headings, the sort order, up to three grouping levels, the totals per column, calculated fields, the report's own filters, the file format (CSV or Excel), the file name pattern and the retention period. A report has one **owner**, the person who created it or cloned it. The wizard creates a report in ten steps; the designer changes one. See [Create a report](/administration-guide/reports/create-a-report.md) and [Design a report](/administration-guide/reports/design-a-report.md).
A **system template** is a report OpenIAM ships, owned by the system user and read-only for everyone: you run it as it is, or **Clone to my reports** and change the copy. See [System templates](/administration-guide/reports/system-templates.md).
### Runs and files
A **run** is one execution of a report. It is queued, claimed by a worker of the report service, streamed row by row into a file in the shared file store, and recorded in the report's **Run history** with its trigger (manual, scheduled or export), status, duration, row count and the file. The file is what you download, from Run history or from the **Download center**, which lists every file generated for you across all reports.
A **preview** is not a run: the details page reads up to 100 rows live, stores nothing and writes no history. See [Run a report and download the file](/administration-guide/reports/run-and-download.md).
### Schedules and delivery
A report has at most one **schedule**: a frequency (daily, weekly, monthly or a cron expression), a time, a time zone and a file format. Each schedule is one batch task in the platform's batch task manager, which is what fires it. A schedule can carry **subscribers**: OpenIAM groups, OpenIAM users and external e-mail addresses that receive the file after every completed scheduled run, attached when it is 10 MB or smaller, as a sign-in link otherwise, and it can upload the file to SFTP servers, which has no subscribers at all. See [Schedule and deliver a report](/administration-guide/reports/schedule-and-deliver.md).
### Retention
Every file expires unless its report says otherwise. A report says for how many days it keeps its files (365 unless you change it) or keeps them forever; a file that holds personal data, or that an SQL data source produced, expires after at most 7 days whatever the report says. A nightly purge removes expired files, prunes run history older than 12 months and, when the store is over its size cap, evicts the oldest files first. A file you **Keep** is exempt from all three until you stop keeping it. See [Retention](/administration-guide/reports/run-and-download.md#retention-policy).
### Job Monitor
The **Job Monitor** is the super administrator's view of the queue: which runs are running, which are waiting and in what order, what failed in the last 24 hours, and a **Cancel** for any run. See [Job Monitor](/administration-guide/reports/job-monitor.md).
## How a report is produced
1. You save a report. The definition is validated on the server: every entity and field exists, every join follows a catalog relationship, every operator fits its field type, nothing exceeds a limit.
2. You choose **Run**, an **Export**, or the schedule fires. A run row is queued with a priority: manual runs first, scheduled runs next, exports last. A schedule that fires while its previous run is still active skips that fire and audits the skip.
3. A worker on any instance of the report service claims the run, validates the definition again as the person who requested it, and streams rows from the database or OpenSearch straight into a CSV or Excel file under the shared file store. Nothing is held in memory; a run over the row or size limit fails rather than producing a partial file.
4. The run is marked completed, with its row count and file. For a scheduled run, the delivery mail goes out to the subscribers. You download the file from Run history or the Download center.
5. Every night the purge expires files past their date, prunes old history and evicts files if the store is over its cap.
The run queue is the `RPT_JOB_RUN` table in the `reporting` database, so every instance of the service sees the same queue and a run that loses its instance is failed as **Worker lost** by another instance after 90 seconds without a heartbeat. The operator's side of this is on [Operate the report service](/administration-guide/reports/operate-the-report-service.md).
## The rules every report obeys
### One main entity, related entities through relationships
Every row of a report is one record of its **main entity** (the wizard's word) or **primary entity** (the builder's word). Other entities join to it only through a relationship the catalog declares, and each entity appears once in a data source. A User role membership report has one row per membership; joining User and Role to it adds the person's name and the role's name to that row. You cannot start a report on two entities at once, and you cannot join two entities the catalog does not relate. At most five related entities join one data source.
### No joins across backends
A report reads either the database or OpenSearch. A User (Database) cannot be joined to an Audit event (OpenSearch), and the catalog shows such relationships as **Cannot be joined: different backend**. The wizard and the builder disable an entity on the other backend and say why. This is also why the shipped **Orphaned accounts** and **Provisioning failures** templates show a managed system ID rather than its name: the name lives in the database, the event in OpenSearch.
### No joins across databases
Database entities join only inside one source database. The certification entities live in the `certification` database and cannot be joined to User in `openiam`; the Certification item entity carries the person's name and login for that reason. The wizard and the builder disable an entity in another database and say **Different database**.
### One OpenSearch entity per data source
An OpenSearch report reads one index and has no joins at all: no related entities, no related-record conditions. A second OpenSearch entity is refused as **Multiple indexes**. Filters, sorting, grouping, totals and calculated fields all work; a calculated field there can only be shown, not filtered or grouped on.
### Once you group or summarize, every field is grouped
A report that groups rows, or that computes a total, shows one row per group. Every field it shows must therefore be a grouping field or a calculation; a plain field left over has no single value for the group. The wizard warns on its **Group by** step and the designer marks the column **Not grouped** until you add it to **Group by** or remove it. Up to three grouping levels are allowed, on fields the catalog marks groupable.
### Filters are combined, never replaced
A view's filters always apply. A report over a view adds its own filters on top; it cannot loosen the view's. A report over inline entities owns all its filters. Filters can use **All**, **Any** or custom logic such as `1 AND (2 OR 3)`, and nest up to five levels deep.
## Limits
These are the shipped values. An operator can change most of them; the Job Monitor shows the ones that matter to authors.
| What | Limit | What happens past it |
| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| Rows in one CSV or Excel file | 1,000,000 (an Excel sheet also stops at 1,048,575 rows) | The run fails with **Limit exceeded**; add filters or grouping |
| Size of one file | 500 MB | The run fails with **Limit exceeded** |
| Rows in a preview | 100 (the page offers 10, 50 or 100) | — |
| Previews at the same time | 4 per service instance, 2 per user | The preview answers "busy"; try again |
| Related entities in one data source | 5 | The definition is refused |
| Fields in one definition | 100 | The definition is refused |
| Filter nesting depth | 5 levels | The definition is refused |
| Conditions in one definition, joins and related-record conditions included | 50 | The definition is refused |
| Calculated fields per report | 50, each formula at most 2,000 characters | The definition is refused |
| Recipients of one schedule, groups, users and addresses together | 200 | The schedule is refused |
| Attachment size | 10 MB | The mail carries a sign-in link instead of the file |
| File retention | 365 days by default; a report may shorten it or keep files forever; 7 at most for personal data | Personal data files still expire after 7 days |
An on-screen result grid also exists in the service, capped at 10,000 rows; this release produces files only, so the figure matters to nobody but API callers.
## Who sees what
A report is visible to its owner and to super administrators; a system template is visible to everyone. Only the owner or a super administrator edits, schedules or deletes a report, and nobody can share one yet. The Data Catalog badges each entity with your access to it, and the file a run produces can be downloaded by the person who ran it, the report owner, the subscribers listed on the schedule and super administrators. The full rules, including what is not enforced yet, are on [Access and permissions](/administration-guide/reports/access-and-permissions.md).
## Related
* [Browse the Data Catalog](/administration-guide/reports/data-catalog.md) — the entities, fields and relationships
* [Create a report](/administration-guide/reports/create-a-report.md) — the wizard, step by step
* [Run a report and download the file](/administration-guide/reports/run-and-download.md) — Run, Export, Preview, Run history, retention
* [Schedule and deliver a report](/administration-guide/reports/schedule-and-deliver.md) — schedules and subscribers
* [Access and permissions](/administration-guide/reports/access-and-permissions.md) — owners, super administrators, entity permissions
* [Operate the report service](/administration-guide/reports/operate-the-report-service.md) — the service behind all of this
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.openiam.com/administration-guide/reports/overview.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.