Reporting Implementation Runbook

This page is the practical rollout guide for implementing reporting in a tenant from a clean or recently reset state.

Use it when you need more than feature-by-feature reference material. It is written for implementation leads, support teams, finance teams, and administrators who must make reporting work end to end.

Who This Runbook Is For

Use this page if you are responsible for any of the following:

• standing up the reporting module in a new tenant
• rebuilding reporting after cleanup or redesign
• validating financial statements before go-live
• handing the module from implementation to operations
• supporting report failures in production

Reporting Operating Model

PinkApple reporting works best when each responsibility stays in the right layer:

• backend procedures produce governed datasets
• system procedure registry controls which procedures are available to the reporting catalog
• report catalog controls report identity, grouping, visibility, and runtime behavior
• financial statement setup controls statement structure and mapping
• operations runtime is where users execute, review, export, schedule, and preserve output

If any one of those layers is weak, the user experience will feel inconsistent even when the other layers are correct.

Delivery Phases

Implement reporting in these phases:

1. Backend readiness
2. Registry and catalog setup
3. Financial statement modeling
4. Runtime validation
5. Operational rollout
6. Support and controlled change

Phase 1: Backend Readiness

Before touching the admin screens, confirm the backend is ready.

Checklist

• required dataset procedures exist in the tenant database
• the procedures run successfully with realistic payloads
• report output shape is understood: ROWSET or REPORT_JSON
• the system procedure registry source of truth is updated
• the registry rows in the tenant match the source of truth
• procedure names referenced by report definitions actually exist

What To Validate

For each candidate procedure, test:

• minimal valid payload
• expected date and business-unit filters
• approval or access constraints
• missing-data behavior
• output stability across repeated runs

If a procedure fails here, do not hide the problem by adjusting the frontend. Fix the procedure or fix the registry entry.

Phase 2: Registry And Catalog Setup

Open Administration -> Reporting.

Procedure Registry

Make sure every intended reporting procedure is:

• active
• approved
• allowed for reporting
• described clearly enough for report-definition authors

The registry should include the core accounting statement procedures, not only ad-hoc datasets.

Report Groups

Create groups that reflect how users browse reports, not how developers think about procedures.

Good examples:

• FINANCIAL_STATEMENTS
• ACCOUNTING
• LENDING
• DEPOSITS
• RISK
• HR
• TREASURY

Do not create one-off implementation groups for temporary testing.

Report Definitions

For each report definition, confirm:

• report group is correct
• dataset procedure is correct
• report type is correct
• output mode matches the procedure contract
• assignments are intentional
• active status is correct

Common failure pattern:

• a report is visible in admin but missing in operations because the definition is active while the group filter or assignments do not line up

Phase 3: Financial Statement Modeling

Open Administration -> Reporting -> Financial Statements.

This phase is where most financial reporting quality problems are created or prevented.

Minimum Build Order

1. Templates
2. Lines
3. Account mappings
4. Column definitions
5. Column sets
6. Notes
7. Manual amounts
8. Financial-statement report definitions

Build Rules

• keep template names business-readable
• keep line ordering deliberate and stable
• map accounts only after line structure is settled
• use column definitions as reusable building blocks
• use column sets as curated layouts for runtime users
• use manual amounts sparingly and under governance

Validation Rules

At this stage, validate:

• statement lines appear in the expected reading order
• mappings land in the correct lines
• totals and subtotals behave correctly
• comparative columns reconcile
• notes attach to the intended lines

If a financial statement runs but looks structurally wrong, the defect is usually in lines, mappings, or column configuration rather than the viewer.

Phase 4: Runtime Validation

Open Reporting -> Reports.

Do not sign off implementation from admin screens alone.

UAT Checklist

For every important report, confirm:

• the group appears
• the report appears inside the intended group
• the parameter form is understandable
• lookup fields display labels correctly in create and edit flows
• the report runs without raw backend errors
• totals reconcile
• drilldowns open where designed
• exports match the rendered output

For financial statements, also confirm:

• the statement uses the intended template
• the intended column set is applied
• comparison periods are correct
• notes and manual amounts appear where expected

Phase 5: Operational Rollout

Once manual execution is stable, move into normal business usage.

Introduce These In Order

1. Saved presets
2. Snapshots
3. Schedules

Do not schedule a report that has not already passed manual validation.

Recommended Ownership

• finance owns statement reconciliation
• operations owns day-to-day report usage
• administration owns catalog governance
• technical support owns registry and procedure health

Phase 6: Support And Change Control

After go-live, treat reporting as a governed product area.

When A Report Breaks

Check in this order:

1. Does the dataset procedure still exist?
2. Does the registry point to the correct procedure?
3. Does the report definition use the correct procedure and output mode?
4. Is the report visible through the right group and assignments?
5. Is the runtime payload valid?
6. Is the financial-statement setup still complete?

High-Risk Change Areas

• renaming procedures without updating the registry
• changing procedure contracts without adjusting output mode
• cleaning report data without reseeding the required catalog and FS setup
• editing mappings during period-end reporting without revalidation

Production Hardening Checklist

Before declaring the tenant stable, confirm:

• registry source and tenant data match
• seeded core reports are present
• core accounting reports run successfully
• statement templates and lines are not empty
• reporting admin forms behave correctly in create and edit mode
• lookups hydrate labels instead of raw IDs
• errors surface through the snackbar and not only the browser console
• documentation is available to admins and end users

Recommended Companion Pages

• Overview
• Administration & Setup
• Financial Statements
• Operations & Usage
• Running Reports