Reports

Reports can be configured to generate CSV files based on SQL queries executed against either the relational database or the data warehouse.

Configure a report on FSP-level

See FINANCIAL_SP_REPORTING module.

Reports are executed and saved on FSP-level, so the data contained in the report should always be scoped to the same level.

Report parameters

Each report declares the filter parameters it accepts in the reports setting of the FINANCIAL_SP_REPORTING module.

• A parameter's key must match a :key named binding in the report's SQL. A query can only be run with the parameters it is meant to use.
• :idFinancialSp is always injected automatically and does not need to be declared.
• :fromDate and :tillDate are examples of common date-range parameters, but any parameter your query needs can be declared. They cannot be used in combination with a scheduled report provider.

Parameters are required by default; set required: false on the configuration to force a parameter to be optional (be aware that the report must support an incoming null value).

Only value types the report engine can bind are allowed: fieldType must be BOOLEAN, CURRENCY, DATE, DATE_TIME, DECIMAL, INTEGER, LIST or STRING, and inputType must be a single-value component (AUTOCOMPLETE, BOOLEAN_CHECKBOX, BOOLEAN_RADIO, BOOLEAN_TOGGLE, DATE, DATE_TIME, DROPDOWN, NUMBER_INPUT, RADIO_LIST or TEXT_INPUT). The configuration is rejected when it uses something else, so a parameter that could never be bound is caught when you save the module rather than when a user runs the report.

A parameter can take its allowed values from a fixed list or from a configured list. Both are set on the parameter's fieldDefinitions:

• options is a fixed list of values (for a DROPDOWN or RADIO_LIST). The values are shown as configured, so use it for values that need no translation.
• autocomplete points at a list whose elements are the allowed values (for an AUTOCOMPLETE with fieldType: LIST). The parameter then shows each element's translated label while binding its identifier, so the filter and the report data read from one source of truth.

A list-backed parameter names the list in autocomplete.listIdentifier and the endpoint serving it in autocomplete.endpoint:

{
  "key": "channel",
  "translationKey": "channel",
  "fieldDefinitions": {
    "inputType": "AUTOCOMPLETE",
    "fieldType": "LIST",
    "autocomplete": {
      "listIdentifier": "communicationChannels",
      "endpoint": "application/field-definitions/lists/communicationChannels/autocomplete"
    }
  }
}

A parameter takes its values from one source or the other: configuring both is rejected when you save the module. A submitted value is always checked against options when that list is filled, so a leftover options list next to an autocomplete block would reject every element the list offers.

The parameter's label comes from its translationKey, resolved as BACK_END.FIELDS.<translationKey>.label, with an optional info text at BACK_END.FIELDS.<translationKey>.extra.description.

Report filename

The csvFilename setting of FINANCIAL_SP_REPORTING is the template used to name the generated CSV; the file extension is added automatically and must not be included. Leave it unconfigured or blank to fall back to csv_report_{{reportIdentifier}}_{{currentDate}}; any other value has to be able to produce a name, so a template of only separators is rejected.

The template supports the following placeholders:

• {{reportIdentifier}} — the identifier of the report being run.
• {{currentDate}} — the run date in YYYY-MM-DD, or {{currentDate:<pattern>}} for the run's timestamp in any DateTimeFormatter pattern.
• {{fspName}} / {{fspIdentifier}} — the name/identifier of the FSP the report was run on.
• {{fspExternalReference}} — that FSP's external reference, the code the client's own systems use. It renders empty when the FSP has none.
• {{param:<key>}} — the value submitted for that report parameter. The key must match a declared parameter.

Each placeholder renders at most 64 characters and is reduced to letters, digits, underscores and hyphens; the template's own literal text is kept as written. A colon is only valid inside a placeholder; any other use is rejected when you save the module. A report's own reports[].csvFilename overrides the FSP-wide template for that report only (same placeholders) — leave it blank to keep using the FSP-wide one.

CSV delimiter

The delimiter offered when running a report is not a module setting: its options come from the field definition of the report's delimiter field. Comma and semicolon are offered by default with comma preselected; a client's field-definition provider narrows that, and a single remaining option hides the choice and is applied as it is. A report run with a delimiter its field definition does not offer is rejected. The GenerateReport and GenerateReportV2 actions take their delimiter from their own action settings and are not restricted by it.

Report Engine: RELATIONAL

When using engine RELATIONAL, reports are executed against the relational database of the Harmoney application.

These reports are developed and maintained by the Harmoney product/custom team. They are automatically imported on application startup. It's not possible to create, edit or delete these reports via the admin UI.

The reports are shared and can therefore be used by all organizations in the environment. However, these reports are developed for a specific organization, so they should not be reused to avoid regression. The goal is to replace these reports with DATA_WAREHOUSE reports over time, so they can be properly scoped to an organization (see below).

Report Engine: DATA_WAREHOUSE

Use engine DATA_WAREHOUSE to execute SQL queries against the Data Warehouse (StarRocks). To use this engine, the DWH connection must be configured in the vault and environment variables (see Data Warehouse for more details).

Instructions on how to consume the gold layer in the data warehouse can be found here.