Documentation

Appearance

Updated Sep 11, 2026 by Barča Dvořáková · Owner: analysisactivefeatureconfluence-migration Edit on GitHub

Report Builder ​

Business Context ​

Business-Level Definition ​

This page documents the manual block-assembly capability of report building. Print/export and scheduled automatic sending of reports are a related, larger capability that is deferred to a later update of this same page — not a separate feature.

Analogous to dashboard pinning (see Dashboard Management), but for reports: a user assembles a named report template by inserting blocks (chart / table / text) and arranging them in order. The result is a reusable, ordered structure that a later (not-yet-documented) pass will make printable/exportable and schedulable.

Requirements Definition ​

  • Create a report template and give it a name
  • Insert blocks of type chart, table, or text into the template
  • Reorder blocks within the template
  • Remove a block from the template
  • Report templates are visible to every user within a tenant, but only the template's creator may rename, edit, or delete it — other users in the tenant have view/use access only (unlike dashboardLayout, which is both private and fully owned per user)
  • A lightweight per-type config validation mechanism (required-key presence), independent of the Dashboard tile registry

Acceptance Criteria ​

  • A user can create a report template with a name
  • A user can insert a block of type chart/table/text into a template
  • A block's config is validated on save against a minimal per-type schema (required keys present) — same validation philosophy as Dashboard Management, independent registry
  • A user can reorder blocks; the new order is persisted as a whole
  • A user can remove a block without affecting anything else
  • Any user within the same tenant can view and use any report template in that tenant, regardless of who created it
  • Only the template's creator (createdBy) can rename, edit, or delete the template; other users in the tenant see it in read/use mode only, with no edit or delete controls available to them

N/A — not available in the source material.

Technical Context ​

User Stories / Use Cases ​

Create a report template: a user opens the report builder and names a new template → an empty reportTemplate is created, visible to everyone in the tenant, editable only by its creator.

Insert a block: the template's creator picks a block type (chart/table/text) → a block is appended to the template with default config for that type.

Reorder blocks: the template's creator drags a block to a new position → the whole block order for the template is saved.

Remove a block: the template's creator removes a block → it is soft-deleted; the template and other blocks are unaffected.

View a shared template: a user who did not create the template opens it from the tenant's shared list and can see its blocks in read/use mode, without edit or delete controls.

UI/UX Design ​

Pending UI/UX review. Functional proof of concept only, mirroring Dashboard Management's approach: placeholder chart/table types with mock data, independent of the Chart Engine.

Functional Requirements ​

Block type registry and validation — Independent from the Dashboard tile registry (confirmed decision — see Dashboard Management for the analogous but separate mechanism). Each type has a minimal required-key schema for its config. v1 types: placeholderChart, placeholderTable, text. The text type has no Dashboard equivalent — its config in this iteration is plain text only ({ "content": string }), not rich text; rich text formatting is a later extension of the same schema slot.

Report structure and ordering — A reportTemplate entity owns an ordered list of reportBlock records via an integer order attribute (not a 2D grid position — a report is a linear/vertical structure, so there is no resize or aspect ratio concept, unlike dashboardBlock). Reordering saves the full ordered list at once, the same "whole state saved on every change" pattern as Dashboard Management's layout PUT.

Sharing and edit rights — Report templates are visible to every user within a tenant (scoped by reportTemplate.tenantId), but only the template's creator (reportTemplate.createdBy) may rename it, edit its blocks, reorder its blocks, or delete it. Other users in the tenant have view/use access only — no edit or delete controls are shown to them. This is a v1 simplification; a finer-grained sharing/co-editing model is not in scope.

Insert action — Adding a block appends it at the end of the template's block list with the type's default empty config; the user can then reorder it.

Non-Functional Requirements ​

  • Reordering must persist the full new order atomically — a partial reorder must never be saved
  • The block type registry (type-to-schema) must be a single, centrally defined source, separate from but structurally parallel to the Dashboard tile registry
  • The backend must reject rename/edit/reorder/delete requests from any user other than the template's creator

Implementation Notes ​

This iteration deliberately excludes (all part of the broader report-building capability, to be documented in a later pass on this same page):

  • Print / export of an assembled report (PDF, etc.)
  • Scheduled automatic sending (monthly/yearly)
  • Superadmin-defined report templates / broader permissions model
  • Real Chart Engine integration — chart/table blocks use placeholder mock types, same approach as Dashboard Management
  • Any finer-grained sharing model beyond "creator can edit, tenant can view/use" (e.g. co-editors, per-user permission grants) — not requested for v1

API Analysis ​

GET    /v1/report-templates          List report templates in current tenant
GET    /v1/report-templates/:id      Get one template with its ordered blocks
POST   /v1/report-templates          Create a new template (name only)
PUT    /v1/report-templates/:id      Replace name + full ordered block list (creator only)
DELETE /v1/report-templates/:id      Delete a template (creator only)

Domain Model (ER diagram) & Data Attribute Table ​

No ER diagram in source material. Related entity pages (Confluence, not yet migrated into this repo's Entity DAT catalog):

  • reportTemplate — a named report, visible tenant-wide, editable only by its creator
  • reportBlock — a single ordered block (type, order, config) within a template

Data ​

No seed data required — users create their own report templates from scratch.

Test Data ​

N/A — not covered in source material.

Logging ​

.info

  • template created / renamed / deleted
  • block added / removed
  • block order updated
  • rejected edit/delete attempt by a non-creator user

.debug

  • block config validation failure (type, missing keys)

Monitoring ​

N/A — not covered in source material.

Caching ​

N/A — not covered in source material.

Backward Compatibility and Migration ​

No EM2 equivalent — manual block-based report assembly is new functionality for EM3, with no legacy precedent to migrate from.

N/A — not addressed in the source Confluence page; migrated as a reference copy without new legal analysis.

Cybersecurity Considerations ​

N/A — not addressed in the source Confluence page; migrated as a reference copy without new security analysis.

Risk Assessment ​

N/A — not addressed in the source Confluence page; migrated as a reference copy without new risk analysis.

Auditing, Reporting & Measurement ​

N/A — not addressed in the source Confluence page; migrated as a reference copy without new analysis.

Migrated as a reference copy from Confluence page "Report Builder" (id 682197028). Content reorganized to fit this repo's feature-doc template; not re-analyzed against the current codebase.