Report Configuration

Reports are defined as platform properties consumed by the reporting service at runtime. Each report has a unique report ID and a property value that specifies the query type, data source, and query to execute. You can override any report definition for a specific tenant without affecting the global default.

Prerequisites

Access to the Eclipse platform property store (via Admin Portal or API)
A valid database connection name configured in the reporting service

Report Definition Format

Reports are stored as platform properties under the reporting.config namespace. The property value is a comma-separated string in the format:

<type>,<connectionName>,<query>

Report types

Type	Description
`sql`	Executes a SQL `SELECT` against a named database connection
`pngw`	Executes a SQL query against the Postilion gateway database
`pb`	Sends an ISO 8583 message to the Postilion NID switch and parses the response

SQL and PNGW report format

sql,<connectionName>,<sql query>

Example:

sql,eclipse-db,SELECT wallet_id, balance, currency FROM wallet WHERE tenant_id = <tenantId> AND created >= ?D1?

Postilion (PB) report format

pb,<serviceName>,<commandId>

Property Keys

Report definition

Property	Description
`reporting.config.<reportId>`	Global report definition. Value is the comma-separated type/connection/query string.
`reporting.config.<tenantId>.<reportId>`	Tenant-specific override. Takes precedence over the global definition for that tenant.

Execution tuning

Property	Default	Description
`reporting.config.queryTimeoutSeconds`	`15`	Maximum seconds a SQL query may run before the reporting service cancels it.
`reporting.config.db.connection.maxAttempts`	`3`	Number of times the service retries a failed database connection before returning an error.
`reporting.config.db.connection.baseDelayInMillis`	`1000`	Base delay in milliseconds between connection retry attempts.
`reporting.deny.loose.queries`	`false`	When `true`, reports that do not include `<tenantId>` or `<organisationId>` template variables are blocked for non-system users. Set this to `true` in production to prevent cross-tenant data exposure.

Query Parameters and Template Variables

Report SQL queries support two types of runtime substitution.

Template variables (server-resolved)

These are replaced by the reporting service before the query executes.

Variable	Replaced with
`<tenantId>`	The tenant ID from the request parameter, or the authenticated user's tenant
`<userId>`	The authenticated user's ID
`<organisationId>`	The organisation ID from the request parameter, or the user's position's organisation

Typed placeholders (caller-supplied)

Callers pass values via query parameters on the report API call. The service binds them to the SQL as prepared statement parameters.

Placeholder	Query parameter	Type
`?S1?` – `?S20?`	`s1` – `s20`	String
`?N1?` – `?N8?`	`n1` – `n8`	Numeric (double)
`?D1?` – `?D8?`	`d1` – `d8`	Date (ISO 8601 string, parsed to timestamp)

Example query using both:

SELECT * FROM payment
WHERE tenant_id = <tenantId>
  AND status = ?S1?
  AND created >= ?D1?
  AND created < ?D2?
  AND amount >= ?N1?

Access Control

Default role-based access

The reporting service grants access to reports based on the authenticated user's role. The following roles have access to standard reports and dashboards by default:

GLOBAL_ADMIN, GLOBAL_FINANCE_L_1/L_2/L_3, GLOBAL_TECH_SUPPORT, GLOBAL_SUPPORT_L_1/L_2/L_3, INSTITUTION_ADMIN, INSTITUTION_FINANCE_L_1/L_2/L_3, INSTITUTION_TECH_SUPPORT, INSTITUTION_SUPPORT_L_1/L_2/L_3, INSTITUTION_INTEGRATOR, LEVEL_01 through LEVEL_05, TENANT_SYSTEM

Per-report permission override

To restrict a specific report to a named set of roles or positions, set the following tenant config item:

Report.<reportId>.READ.Allowed = GLOBAL_ADMIN,INSTITUTION_ADMIN

The value is a comma-delimited list of role or position names. Only users holding one of those roles can execute the report.

Post-Logic Handlers

After a report executes, the service invokes a configurable post-logic handler. The default handler is a no-op. You can assign a custom implementation per report.

Property	Description
`report.<reportId>.config.reportPostLogicHandlerClass`	Fully qualified class name of the `IReportPostLogicHandler` implementation to invoke after this report runs. Defaults to `com.ukheshe.services.reporting.post.handler.DefaultReportPostLogicHandler`.