107 lines
5.1 KiB
Markdown
107 lines
5.1 KiB
Markdown
# Reporting Administration Guide
|
|
|
|
## Definition graph
|
|
|
|
Reporting definitions form an exact graph:
|
|
|
|
```text
|
|
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.
|
|
|
|
Each definition also records system, tenant, group, or user governance scope,
|
|
whether it is inherited, and whether lower scopes may run, reuse, or automate
|
|
it. A child may tighten but never broaden any effective ancestor limit. System
|
|
definitions require system governance permission; tenant definitions are bound
|
|
to the active tenant; group and user definitions require the matching subject
|
|
unless a Reporting administrator performs the operation. Policy is consulted
|
|
for view, edit, run, reuse, and automation decisions.
|
|
|
|
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.
|
|
For a Dataflow source, `source_run_ref` optionally pins one successful run that
|
|
published an immutable Datasource materialization. Reporting passes this pin
|
|
through rather than re-executing the pipeline. The current principal must still
|
|
be authorized for the Dataflow definition and the exact Datasource output.
|
|
|
|
On PostgreSQL installations, Reporting compiles bounded semantic filters,
|
|
grouping, measures, calculated measures, ordering, offsets, and limits into a
|
|
parameterized PostgreSQL plan over the already authorized provider rows. Field
|
|
paths and values are bound parameters and result limits remain mandatory. Pivot
|
|
plans retain the safe provider-neutral engine fallback. SQLite development and
|
|
other database engines use the same typed semantics through the bounded runtime
|
|
engine.
|
|
|
|
## 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.
|
|
|
|
Reporting ships two optional adapters. `reporting.publication.files` calls
|
|
`files.artifact_store` and stores an idempotent managed artifact with execution,
|
|
revision, output-hash, and file-version evidence. `reporting.publication.mail`
|
|
calls `mail.notificationDelivery` and submits an idempotent report notice to the
|
|
Mail outbox. The latter does not bypass Mail profile, credential, or transport
|
|
policy. Adapter availability is evaluated at runtime, so Reporting remains
|
|
usable with neither Files nor Mail installed.
|
|
|
|
Drill contexts expire after 20 minutes, are bound to the creating account, store
|
|
only token and context hashes, and must match the original execution output and
|
|
source fingerprints. Resolution re-runs definition and row-level authorization.
|
|
Treat a fingerprint mismatch as a required report rerun, not as a recoverable
|
|
client warning.
|
|
|
|
## 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:
|
|
|
|
```json
|
|
{
|
|
"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.
|