Reporting Implementation Model

This page explains how PinkApple reporting works end to end, from configuration in administration to execution in the reporting workspace.

Use it when you are:

• designing a fresh reporting rollout
• rebuilding the report catalog after cleanup
• implementing new dataset procedures
• troubleshooting why a report does not render correctly in the frontend

Product Shape

PinkApple reporting is one feature with two working surfaces:

Surface	Navigation	Purpose
Administration	Administration -> Reporting	Define report groups, report definitions, financial statement setup, builder assets, schedules, and procedure governance
Operations	Reporting -> Reports	Run reports, drill into detail, export output, save presets, save snapshots, and review schedules

This split is deliberate:

• administration defines what exists and who can use it
• operations is where business users actually consume reports

Core Design Approach

PinkApple uses a catalog-driven reporting model.

A report is not primarily a custom screen or a Node route. It is a governed catalog item that points to a backend dataset procedure and renders through a generic viewer.

The practical chain is:

Report Group
  -> Report Definition
     -> Dataset Procedure
        -> Output Contract
           -> Report Viewer
              -> Export / Drilldown / Snapshot / Schedule

For financial statements the chain becomes:

FS Template
  -> FS Lines
     -> Account Mappings
     -> Column Definitions
     -> Column Sets
     -> Notes / Manual Amounts
  -> Financial Statement Report Definition
  -> Run Reports

What Lives Where

Administration

The admin side is the reporting control plane.

It contains:

• Report Catalog
  • report groups
  • report definitions
  • definition-level access and governance
• Financial Statements
  • templates
  • line items
  • account mappings
  • column definitions
  • column sets
  • notes
  • manual amounts
• Report Builder
  • safe sources
  • builder definitions
  • run builder validation
• System Settings
  • procedure registry
  • schedules
  • elimination rules
  • system admin actions

Operations

The operations side is the user workspace.

It contains:

• Run Reports
• Snapshots & Presets
• Schedules

Backend Flow

At runtime the backend resolves a report definition and dispatches to the configured stored procedure.

The high-level flow is:

1. The frontend sends report_code plus a JSON payload of parameters.
2. The backend looks up the report definition.
3. The backend validates that the report is active and accessible.
4. The backend calls the registered dataset procedure.
5. The result is normalized into a common viewer shape.
6. The frontend renders the output generically.

That is what makes it possible to keep adding reports without creating a new frontend page every time.

Output Modes

Every report definition must deliberately choose how the output should be interpreted.

Output mode	Use when	Typical examples
ROWSET	The procedure returns normal tabular rows	lists, ledgers, exception reports, operational tables
REPORT_JSON	The procedure returns structured report payloads	financial statements, dashboards, KPI reports, composite outputs

Use the wrong output mode and the report may still run, but the viewer, exports, and drilldowns become unreliable.

Frontend Rendering Model

The viewer in Reporting -> Reports -> Run Reports is intentionally generic.

It renders:

• KPI cards
• series or chart-oriented sections
• one or more tables
• statement-style financial layouts
• drilldown actions
• export actions

That means the frontend is not supposed to know the business logic of every report. The report definition and dataset procedure are supposed to carry most of that intent.

Drilldown Model

Drilldown is a governed extension of a summary report.

The expected rule is:

• the parent report decides what drilldowns are allowed
• the backend validates the target procedure
• the frontend only consumes the allowed drilldown action

This is important because drilldown is not the same thing as letting the UI call any procedure directly.

Financial Statement Engine

Financial statements are not ordinary rowset reports. They are a statement engine sitting on top of:

• template structure
• ordered line definitions
• GL account mappings
• comparative or analytical columns
• optional notes
• optional manual adjustments

The financial statement report definition acts as the runtime bridge between that setup model and the report viewer.

That is why a financial statement report is incomplete unless both of these exist:

• the FS configuration itself
• the linked report definition in the catalog

Builder Engine

The builder is the controlled self-service reporting path.

It is appropriate when:

• the business need is real but still evolving
• the output is tabular
• the logic does not justify a dedicated reporting procedure yet

It is not the right place for:

• statutory statements
• board-critical curated outputs
• reports whose logic must be tightly controlled in backend SQL

Automation Model

Automation in reporting is built on top of manual execution, not instead of it.

The normal maturity path is:

1. define the report
2. validate it manually
3. save a preset if needed
4. schedule it if the output is trusted
5. retain snapshots where historical preservation matters

This sequence matters because schedules should automate a proven report, not a draft one.

Recommended End-To-End Rollout

If you are standing up reporting from a clean tenant, use this order:

1. Confirm business units, roles, accounting setup, and fiscal dates are stable.
2. Register approved procedures in the procedure registry.
3. Create report groups.
4. Create report definitions for standard rowset and JSON reports.
5. Build financial statement templates and lines.
6. Add account mappings, columns, column sets, notes, and manual amounts.
7. Create any builder safe sources and builder definitions.
8. Validate every report in Run Reports.
9. Add presets, snapshots, and schedules only after validation.

Operating Model

The cleanest reporting operating model is:

• admins own groups, definitions, procedures, and access
• finance leads own financial statement structure and mapping correctness
• operations users run, export, and review reports
• system owners manage schedules, cleanup, and procedure governance

Do not blur those roles too much. Most reporting problems come from weak ownership rather than weak technology.

Change Management

When introducing a new report, change all affected layers together:

1. dataset procedure
2. procedure registry
3. report definition
4. access assignments
5. runtime validation
6. export and drilldown validation
7. user documentation

When introducing a new financial statement, add:

1. template
2. lines
3. mappings
4. columns and column set
5. notes and manual amounts where needed
6. financial statement report definition
7. runtime validation

Common Failure Patterns

These are the reporting issues you should expect to catch during implementation:

Issue	Usually means
Report card does not appear	definition inactive, wrong group, or access not assigned
Report runs but renders badly	output mode does not match procedure output
Financial statement opens as a flat table	report definition is not correctly linked to FS template or uses the wrong output style
Drilldown does nothing	drilldown is not configured or the target is not allowed
Export differs from screen output	report contract is inconsistent or the viewer is compensating for backend shape drift
Schedule fails repeatedly	the report was never fully validated manually or the payload is no longer valid

Implementation Standard To Aim For

A solid PinkApple reporting feature should have all of the following:

• stable report groups with clear names
• report definitions pointing only to approved procedures
• correct output mode on every definition
• financial statements built from real FS configuration, not ad-hoc exceptions
• explicit role and business-unit visibility where needed
• successful manual runs before any schedule is activated
• snapshots used for preservation, not as a workaround for bad runtime behavior

Related Pages

• Overview
• Administration & Setup
• Report Catalog
• Financial Statements
• Operations & Usage