> 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/operate-the-report-service.md).

# Operate the report service

What the report builder runs on — the report service, its database and source databases, the shared file store, the run queue, the nightly purge, every report.\* property with its default, the audit ac

## What this is, and when you need it

This page is for the operator who installs, configures and keeps the report builder running: the `report-manager` service, the `reporting` database, the read-only access it needs to the other OpenIAM databases, the volume it writes files to, the queue it runs on, the batch tasks it depends on, and every property it reads. Report builders and report readers do not need it; they start at the [Report builder overview](/administration-guide/reports/overview.md).

Installation and upgrade mechanics (images, Helm values, RPM packages) are in the [Installation Guide](/installation/installation.md). This page says what those mechanics have to provide and what to check when something is off.

## The moving parts <a href="#operate-service" id="operate-service"></a>

| Part                     | What it is                                                                                                                                                                                                                                                                                           |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `report-manager`         | A Spring Boot service of its own, like `certification-manager` or `privacy-manager`. It owns the catalog, validates definitions, runs reports, writes files, fires schedules and purges. Several instances may run; they share the queue and the file store                                          |
| The `reporting` database | The service's own schema: `RPT_CATALOG_OBJECT`, `RPT_CATALOG_PROPERTY`, `RPT_CATALOG_ASSOCIATION` (the catalog), `RPT_DATA_SOURCE_DEF`, `RPT_REPORT_DEF`, `RPT_SCHEDULE`, `RPT_JOB_RUN` (the queue and the history). Created and migrated by the conf Flyway image like every other OpenIAM database |
| Source databases         | The OpenIAM databases the catalog reads, through a read-only user: see [Source databases](#operate-databases)                                                                                                                                                                                        |
| OpenSearch               | The indexes behind the OpenSearch entities (audit events, SoD violations, orphaned accounts, provisioning results), read through a client of the service's own                                                                                                                                       |
| RabbitMQ                 | The service listens on its own virtual host, `openiam_report`; the Webconsole facade and the batch tasks talk to it through that host                                                                                                                                                                |
| The Webconsole facade    | `/webconsole/rest/api/report-builder/*` in `openiam-webconsole`: every screen calls it, it checks who you are and what you own, writes the audit entries for user actions, and streams downloads from the file store                                                                                 |
| `batch-task-manager`     | Fires each schedule's batch task and the nightly purge task; see [Schedules](#operate-schedules) and [The nightly purge](#operate-purge)                                                                                                                                                             |
| The file store           | One volume shared by every `report-manager` instance and the Webconsole: see [The file store](#operate-artifact-store)                                                                                                                                                                               |

## Source databases <a href="#operate-databases" id="operate-databases"></a>

`report.source.databases` lists the databases the catalog may read; it ships as `openiam,certification,privacy,pbac,batchtasks,activiti`. The service opens one read-only connection pool per listed database, of at most `report.source.pool.max-size` (5) connections, and fails to start when a listed database has no resolvable URL, so never ship the key empty.

Each pool connects to `jdbc.reporting.source.<db>.url`. In the shipped `datasource.properties` every one of these points at the database's primary URL (`${jdbc.url}` for `openiam`, `${jdbc.certification.url}` and so on). Point one at a **read replica** to take reporting load off the primary; the service accepts any replica that answers the same SQL dialect. On Oracle, where all databases are schemas of one instance, the pool switches to `<db>.databaseSchema.name` when `org.openiam.hibernate.query.include.schema=true`.

The service's own database is `jdbc.reporting.url` with schema `reporting.databaseSchema.name` (`reporting`), pool size `org.openiam.jdbc.connection.pool.size.max` (5).

{% hint style="info" %}
Only the `openiam` and `certification` databases have catalog entities today. `privacy`, `pbac`, `batchtasks` and `activiti` are listed, granted and pooled so that later catalog seeds can read them without a configuration change; no shipped entity reads them in 2026.10.1.
{% endhint %}

### The reporting database user <a href="#operate-reporting-user" id="operate-reporting-user"></a>

All reads go through one database user, `reporting`, whose credentials come from the vault as `vault.secret.reporting.jdbc.username` and `vault.secret.reporting.jdbc.password` (with the usual environment-variable fallback). It owns the `reporting` schema and holds **SELECT only** on every source database. SQL data sources run as this user too, which is what makes a vetted SELECT safe: the user cannot write, and the statement checker refuses anything but a single SELECT.

* **MySQL, MariaDB, PostgreSQL, SQL Server:** the conf migrations and the RPM scripts create the user and the grants on all six databases. On RDS-style managed databases where the migration user may not grant, apply the same grants by hand.
* **Oracle:** cross-schema grants cannot be made by the migration and are a manual step of the 2026.10.1 upgrade. The statements are in the release-specific upgrade steps for [RPM](/installation/rpm/rpm-upgrade/release-specific-steps.md) and [Kubernetes](/installation/kubernetes/kubernetes-upgrade/release-specific-steps.md). Until they are applied every report on an Oracle installation fails with `SOURCE_UNAVAILABLE` or `QUERY_FAILED` naming a missing table.

## The file store <a href="#operate-artifact-store" id="operate-artifact-store"></a>

Every CSV and Excel file a run produces is written under `report.artifact.path`, which ships as `${confpath}/report-artifacts`. The Webconsole reads the same key to stream downloads. The directory therefore has to be **one shared, writable volume** mounted on every `report-manager` instance and on every `openiam-webconsole` instance: with separate local directories, a file written by one instance is "not found" on the others and downloads answer 404 or 410 at random. On Kubernetes that is a `ReadWriteMany` claim; on RPM hosts in a cluster, an NFS mount.

Layout under the root:

| Path                                                 | Holds                                                                                                                                                                                                                                                                                                       |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<tenant>/<report name>/<rendered name>.<csv\|xlsx>` | Files of saved reports; `<tenant>` is the fixed segment `report.artifact.tenant` (`default`), `<report name>` the report's name made file-safe and cut at 100 characters, `<rendered name>` the [file name pattern](/administration-guide/reports/output-file-names.md) rendered. A clash gets `_2`, `_3` … |
| `<tenant>/_adhoc/`                                   | Files of runs started through the API without a report                                                                                                                                                                                                                                                      |
| `<run id>/`                                          | Spools of grid-format runs (API only; the Webconsole produces files, not grids)                                                                                                                                                                                                                             |

Sizing: a file is capped at `report.limits.max-artifact-bytes` (500 MB); the store at `report.artifact.max-store-bytes` (20 GB, `0` for unlimited); deployment charts that bundle an NFS provisioner may set a lower cap in their values. Excel rendering also needs temporary space in `java.io.tmpdir` of a couple of times the file's size: rows beyond the hundred kept in memory go to compressed temporary files that are deleted when the export ends.

What leaves the store, and when, is decided by the [nightly purge](#operate-purge).

## The queue and the workers <a href="#operate-queue" id="operate-queue"></a>

There is no message queue for runs: `RPT_JOB_RUN` **is** the queue. A submission inserts a row with status `QUEUED` and a priority (manual 30, scheduled 20, export 10). Each instance polls the table every `report.worker.poll-interval-ms` (5 s), claims runs with an atomic update that names the instance in `WORKER_ID`, and executes at most `report.worker.pool-size` (4) at a time, with a bounded hand-off queue of `report.worker.queue-capacity` (50) accepted-but-not-started runs; one more is refused rather than blocking the caller. The worker writes progress every `report.worker.progress-rows` (1,000) rows and re-reads the cancel flag at the same moment.

Liveness is a heartbeat, written every `report.worker.heartbeat-interval-ms` (15 s) on a thread of its own. At every poll every instance fails the running runs whose heartbeat is older than `report.worker.stale-after-ms` (90 s) with `WORKER_LOST`, deletes their partial file and lets their schedule fire again. The service refuses to start when `stale-after-ms` is not more than three heartbeat intervals.

An instance names itself `report.worker.instance-id` when set, else `<host name>-<pid>`, unique per process. Set the property only when you want a restarted instance to fail its own leftover runs at once (`WORKER_RESTARTED`) under a stable name; leave it unset otherwise, so that a replaced instance never inherits a predecessor's name.

The job monitor counts instances from the broker: every instance listens on the management queue with exactly `report.mq.listener-consumers` (6) consumers, no scaling, so consumers ÷ 6 is the instance count and the **Workers** tile reads pool size × instances. A preview holds one of those six listener threads while it reads, which is why `report.limits.preview-concurrency` (4) stays below six.

## Schedules <a href="#operate-schedules" id="operate-schedules"></a>

Each report schedule is one `BATCH_CONFIG` row in the `batchtasks` database, category `REPORT`, named `Report: <report name>`, Spring bean `reportScheduleInitializer`, method `perform`, with the schedule id as its first parameter, enabled while the schedule is active. The category hides these rows from the default Batch Tasks list. `batch-task-manager` plans their fire times during its sweep (every 5 minutes by `org.openiam.batch.task.sweep.time`) and executes due rows every 20 seconds; the service reads the planned rows back to show **Next runs**. Two consequences for operators: a schedule saved less than five minutes before its time misses that time (every save purges the planned rows and the sweep never back-fills), and a stopped `batch-task-manager` stops every report schedule and the purge, see [Restart batch tasks that have all stopped](/administration-guide/automation/batch-tasks/diagnose-stalled-batch-tasks.md).

The `CATEGORY` and `TIME_ZONE` columns on `BATCH_CONFIG` are 2026.10.1 additions (`batchtasks` migrations `V2026.10.1.0.001` and `.003`).

## The nightly purge <a href="#operate-purge" id="operate-purge"></a>

The batch task `REPORT_ARTIFACT_PURGE` (*Report artifact purge*, category `REPORT`, bean `reportArtifactPurgeInitializer`, cron `0 30 1 * * *`, 01:30 every night) runs under a cluster lock in batches of 500 rows, in this order:

1. **Expire** every file whose `EXPIRES_AT` has passed and that is not kept. Audit `REPORT_ARTIFACT_EXPIRE`.
2. **Purge history**: delete run rows that finished more than `report.run.history-retention-months` (12) ago and are not kept (`0` keeps history for ever). Audit `REPORT_RUN_PURGE`.
3. **Evict** while the store is over `report.artifact.max-store-bytes`: oldest unkept files first, never a file finished in the last 24 hours. Audit `REPORT_ARTIFACT_EVICT`.
4. **Sweep orphans**: files on the volume that no run row references and that have not been touched for a day.

Expiry itself is computed when a run finishes: the report's retention days or `report.artifact.retention-days` (365), cut to `report.artifact.pii-retention-days` (7) when an output column carries a permission mark or the source is SQL, capped at `report.artifact.max-retention-days` (365). A report set to keep its files forever gives them no expiry date. A kept file (`IS_KEPT`) is exempt from all three steps until released.

## The catalog refresh

The approximate record counts on the Data Catalog cards come from database statistics or the index document count, never `COUNT(*)`, refreshed by `report.catalog.count-refresh.cron` (`0 0 */6 * * *`, every six hours) under a cluster lock, plus once at startup when `report.catalog.count-refresh.on-startup` is `true`. The catalog's content itself (entities, fields, relationships, display names) is seeded by conf migrations on the `reporting` schema and changes only with a release; display names are i18n keys resolved by the Webconsole.

## OpenSearch <a href="#operate-opensearch" id="operate-opensearch"></a>

The service talks to OpenSearch through an HTTP client of its own, built from the platform's `opensearch.*` host and credentials and `org.openiam.opensearch.connection.timeout`, but with its own socket timeout, so that a long report search is never cut off by the short platform-wide timeout. Rows are read with a point-in-time and `search_after`:

| Property                                  | Shipped           | Meaning                                                                                                                              |
| ----------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `report.opensearch.page-size`             | `1000`            | Hits (or composite buckets) per request, 1 to 10,000                                                                                 |
| `report.opensearch.pit-keep-alive`        | `2m`              | Point-in-time keep-alive, renewed with every page, 1 m to 5 m                                                                        |
| `report.opensearch.request-timeout`       | `60s`             | Per-request timeout after which the search is cancelled and the run fails; never a partial result                                    |
| `report.opensearch.socket-timeout`        | `75s`             | How long the client waits for an answer and for a pooled connection; must not be shorter than `request-timeout` (checked at startup) |
| `report.opensearch.tiebreaker-field`      | `id`              | A unique keyword field that ends every sort                                                                                          |
| `report.opensearch.string-agg-max-values` | `100`             | Distinct values collected per group by a `STRING_AGG`                                                                                |
| `report.opensearch.instance-id`           | the worker's name | Owner of open point-in-time ids, so a restart closes only its own                                                                    |

An OpenSearch entity whose index does not exist on an installation (a stack without `audit-log-manager` has no `auditlog` index) fails runs with `SOURCE_UNAVAILABLE`; the catalog still lists the entity.

## Properties reference <a href="#operate-properties" id="operate-properties"></a>

All keys live in `report-manager`'s `application.properties` and may be overridden the usual way (environment, `confpath`). Shipped values; the code default is the same unless noted. Never ship a key empty: an empty value defeats the default in code.

| Property                                      | Shipped                                                  | Meaning                                                                                     |
| --------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `report.source.databases`                     | `openiam,certification,privacy,pbac,batchtasks,activiti` | Source databases, one read-only pool each                                                   |
| `report.source.pool.max-size`                 | `5`                                                      | Connections per source pool                                                                 |
| `report.worker.pool-size`                     | `4`                                                      | Runs executed at once per instance                                                          |
| `report.worker.queue-capacity`                | `50`                                                     | Accepted-but-not-started runs per instance before refusal                                   |
| `report.worker.poll-interval-ms`              | `5000`                                                   | Queue poll interval                                                                         |
| `report.worker.progress-rows`                 | `1000`                                                   | Rows between progress writes and cancel-flag reads                                          |
| `report.worker.heartbeat-interval-ms`         | `15000`                                                  | Heartbeat of a running run                                                                  |
| `report.worker.stale-after-ms`                | `90000`                                                  | Heartbeat age after which any instance fails the run; must exceed three heartbeats          |
| `report.worker.instance-id`                   | unset (`<host>-<pid>`)                                   | Stable instance name; set only to recover a restarted instance's runs at once               |
| `report.catalog.count-refresh.cron`           | `0 0 */6 * * *`                                          | Record-count refresh                                                                        |
| `report.catalog.count-refresh.on-startup`     | `true`                                                   | One refresh when the service is ready                                                       |
| `report.query.max-joins`                      | `5`                                                      | Related entities per definition                                                             |
| `report.query.max-fields`                     | `100`                                                    | Selected fields per definition                                                              |
| `report.query.max-filter-depth`               | `5`                                                      | Nesting of filter groups, the top group counting as 1                                       |
| `report.query.max-conditions`                 | `50`                                                     | Conditions across filters, join conditions and related-record conditions                    |
| `report.query.max-formula-length`             | `2000`                                                   | Characters in one calculated-field formula                                                  |
| `report.query.max-formula-depth`              | `32`                                                     | Nesting of parentheses, calls and unary minus                                               |
| `report.query.max-calculated-fields`          | `50`                                                     | Calculated fields per definition                                                            |
| `report.query.max-formula-size`               | `5000`                                                   | Parts of one formula once the fields it reads are expanded                                  |
| `report.query.max-logic-references`           | `4`                                                      | Times one condition may be referenced in custom logic                                       |
| `report.query.max-formula-emission`           | `50000`                                                  | Formula parts written into one statement, summed over every use                             |
| `report.query.max-sql-length`                 | `262144`                                                 | Hard stop on the compiled statement, in characters                                          |
| `report.opensearch.*`                         | see above                                                | OpenSearch paging, timeouts, tiebreaker                                                     |
| `report.sql.query-timeout-seconds`            | `300`                                                    | Per statement, per page of a paged run                                                      |
| `report.sql.fetch-size`                       | `500`                                                    | Cursor fetch size                                                                           |
| `report.sql.max-rows`                         | `1000000` (code default `100000`)                        | Hard row stop of the SQL adapter; keep it at or above `export-max-rows`                     |
| `report.sql.keyset-page-size`                 | `10000`                                                  | Rows per statement of a paged full run                                                      |
| `report.access.open-when-permissions-unknown` | `true`                                                   | Opens permission-marked fields while the Webconsole sends no permissions; RB28 turns it off |
| `report.limits.grid-max-rows`                 | `10000`                                                  | Rows of a grid-format run (API only)                                                        |
| `report.limits.export-max-rows`               | `1000000`                                                | Rows of a CSV or Excel file; Excel also stops at 1,048,575                                  |
| `report.limits.preview-rows`                  | `100`                                                    | Most rows a preview returns                                                                 |
| `report.limits.max-artifact-bytes`            | `524288000`                                              | 500 MB per file                                                                             |
| `report.limits.max-page-size`                 | `500`                                                    | Rows per page of a grid result                                                              |
| `report.limits.preview-concurrency`           | `4`                                                      | Previews in flight per instance; keep below `report.mq.listener-consumers`                  |
| `report.limits.preview-concurrency-per-user`  | `2`                                                      | Previews in flight per user per instance                                                    |
| `report.artifact.path`                        | `${confpath}/report-artifacts`                           | The shared file store; the Webconsole reads the same key                                    |
| `report.artifact.tenant`                      | `default`                                                | First path segment under the store                                                          |
| `report.artifact.retention-days`              | `365`                                                    | Default expiry of a file when the report sets none                                          |
| `report.artifact.pii-retention-days`          | `7`                                                      | Expiry of a file with personal data or from an SQL source                                   |
| `report.artifact.max-retention-days`          | `365`                                                    | Longest expiry a report may ask for                                                         |
| `report.artifact.max-store-bytes`             | `21474836480`                                            | 20 GB store cap; `0` = unlimited                                                            |
| `report.run.history-retention-months`         | `12`                                                     | Age of unkept run rows the purge deletes; `0` = never                                       |
| `report.distribution.attachment-max-bytes`    | `10485760`                                               | 10 MB; larger files are linked                                                              |
| `report.distribution.link-url-prefix`         | empty                                                    | Public Webconsole URL for download links; empty logs a warning per delivery                 |
| `report.mq.listener-consumers`                | `6`                                                      | Consumers per instance on the management queue; the instance count is derived from it       |
| `org.openiam.jdbc.connection.pool.size.max`   | `5`                                                      | Pool of the service's own `reporting` database                                              |
| `logging.file.name`                           | `${confpath}/logs/report-manager.log`                    | The service log                                                                             |

Datasource keys, in `datasource.properties`:

| Key                                                  | Shipped                                                   | Meaning                                                      |
| ---------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------ |
| `jdbc.reporting.url`                                 | the `reporting` database on the platform host             | The service's own database                                   |
| `reporting.databaseSchema.name`                      | `reporting`                                               | Its schema                                                   |
| `jdbc.reporting.source.<db>.url`                     | `${jdbc.url}` for `openiam`, `${jdbc.<db>.url}` otherwise | Where the pool for `<db>` connects; a read replica goes here |
| `vault.secret.reporting.jdbc.username` / `.password` | from the vault                                            | The read-only reporting user                                 |

The platform-wide properties that this page mentions (`org.openiam.batch.task.sweep.time`, `opensearch.*`, `org.openiam.opensearch.connection.timeout`) are in the [System property reference](/administration-guide/reference/system-properties.md).

## Audit actions <a href="#operate-audit-actions" id="operate-audit-actions"></a>

Every entry names objects by **name**, never by id — the report, the view or SQL source, the file, the recipients — and a save records what changed per section (fields, calculated fields, filters, sort, grouping and totals, parameters, output, retention, schedule, subscribers) with the old and new values. A preview writes nothing.

| Group            | Actions                                                                                                           | Written by                                                                                           |
| ---------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Reports          | `REPORT_CREATE`, `REPORT_UPDATE`, `REPORT_CLONE`, `REPORT_DELETE`                                                 | Webconsole facade                                                                                    |
| Views            | `REPORT_VIEW_CREATE`, `REPORT_VIEW_UPDATE`, `REPORT_VIEW_DELETE`                                                  | Webconsole facade                                                                                    |
| SQL data sources | `REPORT_SQL_DATA_SOURCE_CREATE`, `_UPDATE`, `_DELETE`, `_VALIDATE`, `_RUN`                                        | Webconsole facade (create, update, delete, validate); `report-manager` (run)                         |
| Schedules        | `REPORT_SCHEDULE_CREATE`, `_UPDATE`, `_PAUSE`, `_RESUME`, `_DELETE`, `_FIRE`                                      | `report-manager`                                                                                     |
| Runs             | `REPORT_RUN`, `REPORT_EXPORT`, `REPORT_QUERY_RUN`, `REPORT_RUN_CANCEL`, `REPORT_RUN_RETRY`, `REPORT_RUN_FINISHED` | Webconsole facade, except `REPORT_RUN_FINISHED`, written by `report-manager` for scheduled runs only |
| Delivery         | `REPORT_DISTRIBUTION_SEND`                                                                                        | `report-manager`                                                                                     |
| Files            | `REPORT_ARTIFACT_DOWNLOAD`, `_KEEP`, `_RELEASE`, `_DELETE`, `_EXPIRE`, `_EVICT`                                   | Webconsole facade (download); `report-manager` (the rest)                                            |
| Purge            | `REPORT_RUN_PURGE`                                                                                                | `report-manager`                                                                                     |

`REPORT_SCHEDULE_SAVE` and `REPORT_SQL_DATA_SOURCE_SAVE` exist only to read entries written by pre-release builds. Retention of the entries follows the platform's rules: [Audit actions and retention](/administration-guide/reference/audit-actions-and-retention.md).

## Which log answers which question <a href="#operate-logs" id="operate-logs"></a>

| Question                                                             | Log                                                                                                                                                     |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Why did a run fail, what did the database say, which instance ran it | `report-manager.log` (`logging.file.name`), by run id                                                                                                   |
| Why did a schedule not fire, or fire for nothing                     | `report-manager.log` (*Schedule … is paused / gone / skipped*), then `batch-task-manager`'s log for the sweep and the task execution                    |
| Why a download answered 403, 404 or 410                              | `openiam-webconsole`'s log: the facade logs the refusal with the requester, the run and the report                                                      |
| Why the service did not start                                        | `report-manager.log` at startup: a source database without URL, a socket timeout shorter than the request timeout, a stale-after below three heartbeats |
| Who did what                                                         | The audit log, see [Find audit evidence](/administration-guide/operations/find-audit-evidence.md)                                                       |

[Which log answers which question](/administration-guide/operations/which-log-to-read.md) covers the platform's other logs.

## When it goes wrong <a href="#operate-troubleshooting" id="operate-troubleshooting"></a>

| Symptom                                                                  | Likely cause                                                                                                                                                                     |
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `report-manager` does not start; the log names `report.source.databases` | A listed database has no `jdbc.reporting.source.<db>.url` and no `jdbc.<db>.url` to fall back on                                                                                 |
| It does not start; the log names `report.opensearch.socket-timeout`      | The socket timeout is shorter than `report.opensearch.request-timeout`                                                                                                           |
| It does not start; the log names `stale-after-ms`                        | `report.worker.stale-after-ms` is not more than three times `heartbeat-interval-ms`                                                                                              |
| Every run fails with `SOURCE_UNAVAILABLE`                                | A source database is down or the reporting user cannot connect; on Oracle, the manual grants are missing                                                                         |
| Runs over an OpenSearch entity fail with `SOURCE_UNAVAILABLE`            | The index does not exist on this installation (no `audit-log-manager`, no SoD service) or OpenSearch is down                                                                     |
| Runs over an OpenSearch entity fail after exactly 60 seconds             | `report.opensearch.request-timeout`; raise it and `socket-timeout` together                                                                                                      |
| Downloads answer 404 or 410 for files that exist in Run history          | `report.artifact.path` is not one shared volume across every `report-manager` and `openiam-webconsole` instance                                                                  |
| Many runs fail with `WORKER_LOST` at once                                | An instance died, was killed, or lost its database connection; the sweep failed its runs. Check the instance and retry the runs                                                  |
| Runs stay `QUEUED` with idle workers                                     | The instances cannot read or update `RPT_JOB_RUN`, or no instance is running; `report-manager.log` shows the poll errors                                                         |
| The store is over its cap and files vanish before their expiry           | Eviction. Raise `report.artifact.max-store-bytes`, give the volume more space, or shorten retention on the heaviest reports                                                      |
| Delivery mails carry a path instead of a link                            | `report.distribution.link-url-prefix` is empty; set it to the public Webconsole URL                                                                                              |
| Every **Next runs** reads *Not planned yet* and nothing fires            | `batch-task-manager` is down or its sweep stopped; see [Restart batch tasks that have all stopped](/administration-guide/automation/batch-tasks/diagnose-stalled-batch-tasks.md) |
| The Job Monitor's **Workers** tile reads *0 of 0*                        | No instance is connected to RabbitMQ; check the service and the `openiam_report` virtual host                                                                                    |
| Files with no personal data expire after 7 days                          | The report reads an SQL data source, whose output always counts as personal data                                                                                                 |

## Related

* [Report builder overview](/administration-guide/reports/overview.md) — the vocabulary and the limits as users see them
* [Job Monitor](/administration-guide/reports/job-monitor.md) — the queue, cancel and retry
* [Run a report and download the file](/administration-guide/reports/run-and-download.md) — retention as users see it, the error codes
* [Schedule and deliver a report](/administration-guide/reports/schedule-and-deliver.md) — the schedule sheet, delivery
* [Create a batch task](/administration-guide/automation/batch-tasks.md) and [Shipped batch tasks](/administration-guide/reference/shipped-batch-tasks.md) — where the schedule and purge tasks live
* [System property reference](/administration-guide/reference/system-properties.md) — platform-wide properties
* [Audit actions and retention](/administration-guide/reference/audit-actions-and-retention.md) — how long audit entries are kept


---

# 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/operate-the-report-service.md?ask=<question>&goal=<user_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.