Reports & Custom Reports API

Eviworx has two separate report systems: (1) predefined standard reports (cost/budget/invest analyses, executed synchronously in the backend) and (2) a custom report builder executed asynchronously via the dedicated report-generator container with READ-ONLY database access (CSV/XLSX/PDF export, scheduling, live preview).

🔐 Auth: All report endpoints are for signed-in users only: they accept a cookie session but no X-API-Key. Permissions are checked against the caller's role matrix. See RBAC →.

Standard Reports

Predefined cost/budget analyses over contracts, licenses and assets. All endpoints are GET and return JSON synchronously. Each cost source is filtered by the permission of its OWN entity (viewAll / viewOwn / reporting on contracts, licenses, assets), following the same rules as the list, the search and custom reports: restricted asset types without a grant stay out, a viewOwn manager sees the contracts of their direct reports, and viewOwn on licenses follows the assignment. A report therefore shows the same costs the caller finds in the corresponding list.

Query Parameters

Every parameter is validated against a schema. An unknown or unsuitable value returns 400 VALIDATION_ERROR with a field path. Parameter sets differ per route: the renewal calendar knows neither year nor assetCostMode, and the invest plan takes years instead of year.

Export language: Exports follow the profile language of the caller, then the system language (general-settings.defaultLanguage), then English — the same chain as license, asset and contract exports. The responses themselves carry no translated text: months are keys (2026-01), and unassigned buckets carry name: null. The file name comes from the Content-Disposition header of the response.

Structure of the cost figures

• Three named sources on every level: month, quarter and year each carry contracts, licenses and assets separately; their sum is total.
• Invest plan: baseline (existing stock, = q1+q2+q3+q4), forecast (of which projected: the projected renewals of that year, 0 in non-forecast years) and total = baseline + forecast. Projections cover contract and license renewals, not new asset purchases.
• Item counter: month and quarter nodes carry itemCount (number of individual items). Detailed rows are only returned by the renewal calendar and the cost-center budget.

# Yearly overview for contracts+licenses only, capex mode
GET /api/reports/yearly-overview?year=2026&sources=contracts,licenses&assetCostMode=capex

# Export budget plan as XLSX
GET /api/reports/export?type=budget&format=xlsx&year=2026

Custom Report Builder

Freely definable reports over one or more data sources with columns, filters, grouping, sorting and visualization. Execute, export and preview are ASYNCHRONOUS: the backend creates an execution with status PENDING and answers 202; the report-generator processes the query with read-only access. The client polls the status endpoint for progress.

ASYNC EXECUTION FLOW:
1. POST /api/custom-reports/:id/execute|export  (or /preview)
2. Backend creates ReportExecution (status: PENDING) → 202
3. Backend enqueues BullMQ job → Queue "report-execution" (+ _trace)
4. report-generator picks up job, runs query READ-ONLY5. report-generator reports the status to the backend (RUNNING/COMPLETED/FAILED)
6. On export: file is stored as an attachment (virusScanStatus PENDING)
7. Frontend polls GET .../executions/:execId/status → COMPLETED
8. Frontend GET .../executions/:execId/download

Report Management

The copy always belongs to the caller and deliberately starts private: createdById = caller, isShared=false, sharedWithRoles=[], isScheduled=false, recipients=[]. Without a name in the body, "(copy)" is appended. A shared report therefore never accidentally becomes a second shared or scheduled report.

Only holders of customReports.share may set or change isShared, sharedWithRoles and sharedWithAllRoles on create or edit — so nobody without that right discloses data. customReports.deleteAll is a critical action: when deleting a FOREIGN report or a foreign generation, the permission is checked directly against the database, so a right just revoked takes effect immediately. PUT is a true partial update: fields not sent stay untouched, and description can be cleared with null.

Sharing with roles

A report is shared with ROLES, not individual users. Three fields control it:

Empty role list: An empty sharedWithRoles list means NOBODY. "Share with all roles" requires the explicit flag sharedWithAllRoles=true. This way an accidentally empty distribution list cannot grant anyone unintended access.

For the role selection in the share dialog, GET /share-targets returns the active roles with derived hints — canViewShared (does the role hold the viewShared right?) and missingSources (which of the report's data sources may the role not evaluate?). The response contains only these flags, not the roles’ permissions themselves. The endpoint requires customReports.share, so non-admins holding that right can share as well.

What "sharing" means — use it deliberately: Sharing covers not only the definition but also the RESULT view. Whoever may see the report AND holds customReports.export sees the results and downloads of OTHER people's runs — in the data scope of whoever triggered that run. If an administrator runs the report with their full visibility, everyone with export rights sees that result, not their own narrower one. The export right applies uniformly to all three result paths: the inline data (/status), the file download and the generic attachment path. Whoever may only view the report sees status and row count, but no payload data.

This is intentional and consistent with scheduled reports, whose emails likewise deliver the creator's scope to authorized recipients: sharing IS the data disclosure; what counts is who may see the report. DELETING results, by contrast, is reserved for whoever triggered the run, owns the report, or holds deleteAll — viewing and cleaning up are two different things.

Execution & Export (async)

generate creates one execution per configured format and is capped at 25 stored generations per report → 409 EXECUTION_LIMIT_REACHED (delete old versions first).

Scheduling & Execution History

Data Sources & Report Definition

GET /schema returns the data sources available to the caller with their permitted fields (permission: customReports.create, editOwn or editAll — editing also needs the schema for field labels and filters). The offering is DYNAMIC and depends on two conditions at once: the caller holds the domain’s reporting right (assets additionally viewAllHandovers ‖ viewOwnHandovers) AND their visibility in that domain is not empty from the outset. Someone with reporting on changes but no right to see changes is therefore not offered changes — such a source could only return 0 rows on execution. Fields and report rows always follow the caller’s permissions; without a matching permission nothing is shown.

Sub-entities inherit their domain's reporting permission: changes.reporting unlocks changes AND changeTasks, assets.reporting unlocks assets AND handovers (the latter additionally with the handover view right). There is no separate reporting permission for changeTasks/handovers.

Besides the label, every field also carries a translation key (labelKey); enum fields additionally carry their enum group (enumKey) — the builder shows fields, values and joins in the UI language, while the stored column label remains the text chosen when it was added.

Fields with an additional permission

A few fields require an additional domain permission beyond the reporting right. They do not appear in the schema offering at all; referencing them anyway via the API yields 400 with issue code FIELD_NOT_ALLOWED, and at run time such a definition fails as well (execution FAILED). Affected:

Deliberate asymmetry: this makes the report STRICTER here than the incident detail, which shows the GDPR block to anyone who can view the incident. That is intended — a mass-export channel (CSV/XLSX, schedules, mail) justifies a higher bar than the single view. Roles without incidents.viewPIR do not see the GDPR columns in their reports until an admin grants the role that right.

Aggregation & row counters

Aggregates (COUNT/SUM/AVG/MIN/MAX) work with AND without groupBy: without grouping, all rows form ONE total group — the result is a single row with the totals (which is what makes the KPI visualization useful). Aggregation runs over the loaded rows, capped at 10,000.

SLA fields (on the tickets entity)

SLA data is available as additional columns of the tickets entity. As a result, the same visibility rules and joins apply to them as to the ticket itself.

A report over tickets shows ALL tickets — the SLA columns are an extra dimension. For compliance numbers, filter on slaExcludedFromReporting = false and slaStatus ≠ CANCELLED; the shipped template "SLA compliance by priority" does exactly that as a visible filter. Two builder templates are included: "SLA breaches last month" and "SLA compliance by priority". Cross-check for numbers: GET /api/sla/report.

Sub-ticket fields (on the tickets entity)

This makes the parent/child relationship directly reportable: parentTicket.ticketNumber with isNull returns all tickets without a parent ticket, with isNotNull only the sub-tickets; childTicketCount > 0 returns the parent tickets. As a computed field, childTicketCount follows the rule for all computed fields — filterable on the primary entity only, and filtering runs after the query (see countIsExact).

Definition (CustomReport): dataSources (entity/alias/joinOn/joinType inner|left, max 5), columns (source/field/label, aggregate COUNT|SUM|AVG|MIN|MAX, max 50), filters (see below, max 20 conditions), sorting, groupBy (max 5 each), visualization (table|bar|line|pie|kpi), chartConfig, pdfOptions, exportLocale (de|en|fr|es|it), isShared/sharedWithRoles/sharedWithAllRoles, exportFormats (csv|xlsx|pdf), recipients.

Filters: operators & OR groups

The filters field has EXACTLY ONE shape: the group form with "version": 2, even for a report with a single AND group. Any other shape in the request (such as a flat array) is rejected with 400 VALIDATION_ERROR — so a malformed filter can never quietly become an unrestricted report. The field is required on create; "no filters" is groups: [].

// (status=OPEN UND prio=CRITICAL) ODER (älter als 30 Tage)
"filters": {
  "version": 2,
  "groupLogic": "OR",        // Verknüpfung ZWISCHEN Gruppen  — Default OR
  "conditionLogic": "AND",   // Verknüpfung INNERHALB Gruppen  — Default AND
  "groups": [
    { "conditions": [
        { "source": "t", "field": "status",   "operator": "eq", "value": "OPEN" },
        { "source": "t", "field": "priority", "operator": "eq", "value": "CRITICAL" }
    ] },
    { "conditions": [
        { "source": "t", "field": "createdAt", "operator": "relative", "value": "last_30_days" }
    ] }
  ]
}

// Ein einfacher Report = genau eine UND-Gruppe:
"filters": { "version": 2, "groups": [ { "conditions": [
  { "source": "t", "field": "status", "operator": "in", "value": ["OPEN", "IN_PROGRESS"] }
] } ] }

Security: permission scoping (deleted records, ownership, visibility rights) is ALWAYS applied additionally with AND, outside the groups — so an OR group cannot widen visibility. Two conditions on the same field are merged in AND mode (e.g. into a range); in OR mode each stays its own branch, so switching conditionLogic yields the expected result.

One quirk of AND mode is worth mentioning: two conditions with the same operator on the same field (status = A AND status = B) overwrite each other — the last one wins instead of producing an empty set. If you mean "A or B", use the in operator or an OR group.

Conditions on joined sources: rows vs. items

A condition on a joined source (e.g. "asset status = IN_USE") normally acts at the level of the PRIMARY entity: it decides whether a ticket enters the report at all ("has at least one matching asset") — which of its assets then appear as rows is a separate question. Once a computed condition joins in (e.g. an SLA field), the engine evaluates the whole predicate per EXPANDED row instead. The set of tickets stays identical, the set of rows can differ:

Filter: (assets.status = IN_USE) OR (priority = CRITICAL)
Ticket matches via group 1 only and carries assets [IN_USE, RETIRED]
without a computed condition  → 2 rows (IN_USE + RETIRED)with a computed condition  → 1 row  (IN_USE only)

Special case: under item-precise evaluation, isNull on a joined field also catches records with no linked items at all.

Joins are INNER joins: A report "A + linked B" shows only A rows with at least ONE B entry visible to the caller. If all linked entries lie outside their visibility (e.g. exclusively assets of locked types without a grant), the A row drops out of the report entirely. This is intended, but not always obvious. The data source picker points this out in the UI.

API Examples

Create Custom Report

POST /api/custom-reports

{
  "name": "Open Tickets by Category",
  "description": "Number of open tickets per category and priority",
  "dataSources": [{ "entity": "tickets", "alias": "t" }],
  "columns": [
    { "source": "t", "field": "category.name", "label": "Category" },
    { "source": "t", "field": "priority", "label": "Priority" },
    { "source": "t", "field": "ticketNumber", "label": "Count", "aggregate": "COUNT" }
  ],
  "filters": {
    "version": 2,
    "groups": [ { "conditions": [
      { "source": "t", "field": "status", "operator": "in", "value": ["OPEN", "IN_PROGRESS"] }
    ] } ]
  },
  "groupBy": [
    { "source": "t", "field": "category.name" },
    { "source": "t", "field": "priority" }
  ],
  "sorting": [{ "source": "t", "field": "priority", "direction": "desc" }],
  "visualization": "bar",
  "exportFormats": ["csv", "xlsx"],
  "exportLocale": "en",
  "isShared": true,
  "sharedWithRoles": ["AGENT"]
}

Export language (exportLocale)

A report has ONE export language (de, en, fr, es, it — default en, selectable in the builder below the format tiles; a new report adopts the UI language of its creator). It controls everything the worker writes into the file: framing texts (cover page, "generated at", footer, chart legend), yes/no values, and number and date formats (de-DE, en-GB, fr-FR, es-ES, it-IT — English therefore writes dates as day/month/year).

If a text has no translation in the chosen language, English applies (chain: chosen language → English → key). The preview without a saved report also runs in English. Exports use the same translations as the user interface.

Execute Report (async)

POST /api/custom-reports/:id/execute

// Response 202 Accepted — async!{
  "executionId": "clx...",
  "status": "PENDING"
}

Check Status (Polling)

GET /api/custom-reports/executions/:execId/status

// execute/preview after COMPLETED — data inline:{
  "executionId": "clx...",
  "status": "COMPLETED",
  "errorMessage": null,
  "result": { "...": "resultData" }
}

// export after COMPLETED — fetch the file via /executions/:execId/download:{
  "executionId": "clx...",
  "status": "COMPLETED",
  "errorMessage": null
}

The status endpoint is deliberately lean — it gets polled. Row count, format and timestamps live in the history (/:id/executions); file metadata comes from the download via its headers.

Export & Download

POST /api/custom-reports/:id/export

{ "format": "csv" }   // csv | xlsx | pdf

// Response 202{ "executionId": "clx...", "status": "PENDING" }

# After COMPLETED:GET /api/custom-reports/executions/:execId/download

Configure Scheduling

POST /api/custom-reports/:id/schedule

{
  "isScheduled": true,
  "cronExpression": "0 8 * * 1",
  "exportFormats": ["csv", "pdf"],
  "recipients": ["userId-1", "userId-2"]
}

// Response: saved report + the next 3 due dates (UTC){
  "id": "clr...",
  "isScheduled": true,
  "cronExpression": "0 8 * * 1",
  "nextRuns": ["2026-07-20T08:00:00.000Z", "2026-07-27T08:00:00.000Z", "2026-08-03T08:00:00.000Z"]
}

The job system sets the pace: the action report_schedule_check runs every minute, starts due schedules (one execution per configured export format) and finalises finished runs with the completion mail. ⚠ Without this job, scheduled reports do NOT run; the report-generator only executes. Running or exporting manually does not shift the schedule, and a newly enabled schedule first fires at the next cron time. On completion the recipients receive ONE email with all format attachments plus a note on formats that could not be produced. Recipients are individual users; the suggestion list in the dialog (GET /:id/recipient-candidates) contains ONLY users who may see the report. Dispatch checks this again (RECIPIENTS_NOT_ALLOWED).

Execution Status

format = pdf | csv | xlsx | PREVIEW (null for a plain execute); the row count is recordCount. Both live in the history, not in the status response.

Retention

Report retention is part of the bundled retention_purge job (job-worker, nightly 03:00) — it keeps the execution history small, otherwise it would grow without bound:

• Stuck runs first: A run stuck on RUNNING for more than 30 minutes has seen a worker crash; one PENDING for more than 24 hours has lost its queue event. Both are set to FAILED — otherwise they would permanently block the 25-run limit, since nothing else would ever touch them again.
• Preview executions (without a report) older than 24 hours are deleted.
• Stored result data of completed runs older than 30 days is cleared — metadata (status, recordCount, timestamps) is kept.
• FAILED executions without a file older than 30 days are deleted, including the stuck runs set to FAILED in the step above.
• Export FILES (the generated attachments) older than 30 days are soft-deleted — an export is a pick-up artifact, not an archive. The physical deletion is then handled by the attachment_cleanup job.

The periods are parameters of the retention_purge-job; it runs ENABLED by default.

Error Codes

Issue codes of the definition check

Every entry in details[] carries the path of the offending spot (e.g. columns[2].aggregate or filters.groups[1].conditions[0].operator) and one of these codes:

Both aggregate rules are already blocked by the builder (selection disabled with an explanation) — the backend check is the second line of defense for definitions built via the API.

Ineffective filter conditions abort

A filter condition that cannot be resolved (e.g. because its field no longer exists after a schema change) produces a named error — a 400 when run via the API, and a failed execution naming the affected condition for scheduled runs.

Why: a condition that silently drops out makes a report return too many rows (the group becomes true) or too few rows (the empty branch drops out of the OR). Both look plausible — especially for scheduled reports nobody checks any more. A named abort gets noticed.

Permissions (customReports)

Standard reports use their own feature: reports.viewReports / reports.viewBudget / reports.viewInvestPlan / reports.exportReports. Report ROWS are additionally filtered by the reporting/viewAll/viewOwn rights of the respective data source.

🔔 Notifications: Report runs trigger REPORT_READY, REPORT_FAILED (user-triggered) or REPORT_SCHEDULED_COMPLETE (scheduled, email with attachments). For channels/templates see Notifications →.

Report Generator Container

Custom reports are executed not in the backend but in the dedicated report-generator container. It has READ-ONLY database access and processes jobs via the BullMQ queue report-execution.

📘 Details: See Container Architecture → for report-generator container details and Environment Variables → for configuration (COMPANY_NAME, CSV_DELIMITER, BACKEND_URL).