govoplan-reporting/docs/ADMIN_GUIDE.md

Reporting Administration Guide

Definition graph

Reporting definitions form an exact graph:

Dataset revision -> Semantic-model revision -> Report revision
                 -> Quality-plan revision

Create parents before children. An active child may reference only an active, existing parent revision. Editing creates a new immutable revision and requires the currently observed revision number. Existing runs continue to reference the historical revisions they used.

Datasets may bind a static fixture, a pinned Dataflow output, or a capability published by a source-owning module. Do not expose another module's ORM or an unbounded SQL connection as a report source. Configure an explicit schema, freshness policy, source fingerprint expectations, purpose, privacy, retention, and a row-policy provider where source access alone is not enough.

Access and publication

Tenant-visible definitions are readable by principals with Reporting read permission. Restricted reports use normalized account, identity, group, role, function, assignment, organization-unit, or service-account grants. The creator and Reporting administrators retain management access.

Scheduled output publication requires an installed capability implementing the Reporting publication-target contract. The target receives one immutable execution payload and an idempotency key. It must return bounded evidence and must not expose credentials in that evidence.

Cross-module provider governance

Source modules register reporting.report_provider.<provider-id> capabilities; do not grant Reporting direct table access to those modules. Review every descriptor's result schema, required privacy transforms, retention class, export formats, and re-identification risk before enabling it in production. Provider authorization remains mandatory even when the Reporting role allows the user to run reports.

When Policy is enabled, configure reporting_governance_policy in system or tenant settings. Tenant settings may only tighten the system result. Supported fields are:

{
  "reporting_governance_policy": {
    "allow_exports": true,
    "allowed_export_formats": ["json"],
    "allow_high_reidentification_risk": false,
    "max_retention_days": 30,
    "required_privacy_transforms": ["small_cell_suppression"]
  }
}

Malformed explicit policy fails closed. The ordinary privacy-retention setting stored_report_detail_retention_days is an additional ceiling. A tenant cannot re-enable an export format, high-risk report, or longer retention period that the system policy denied.

Import assessments

Import assessment accepts declarative metadata only. Native datasets, dimensions, hierarchies, measures, parameters, tables, pivots, charts, quality assertions, and saved views map exactly. Provider-specific formatting, dialect functions, and dashboard layouts require explicit approximation acceptance. Raw SQL, procedures, scripts, implicit authorization, unchecked functions, and unknown features block activation.