Skip to Content
This documentation is provided with the HEAT environment and is relevant for this HEAT instance only.
APIFacadeReport setup guide

Report setup guide

This document explains how reporting is configured for the legacy facade and how to add or update reports.

Overview

The legacy report endpoints load configuration from platform configuration keys under the report prefix.

The current model separates report selection metadata from report implementation details:

  • report.Settings.Reports: list of reports the UI can show.
  • report.Settings.Default: the default report key when no report is explicitly requested.
  • report.Configurations.<configurationKey>.*: the actual configuration used to build a report.

This allows one UI report key to point to one specific configuration block.

Configuration shape

1. Report list shown to the UI

Create report.Settings.Reports as a JSON array.

[
  {
    "key": "afv-all",
    "name": "AFV All",
    "configurationKey": "afvAll"
  },
  {
    "key": "afv-summary",
    "name": "AFV Summary",
    "configurationKey": "afvSummary"
  }
]

Meaning of each field:

  • key: external key used by the UI and query parameters.
  • name: display name for the settings UI.
  • configurationKey: the configuration block used at runtime.

2. Default report

Create report.Settings.Default as a string.

afv-all

If no option or report query parameter is passed, the legacy facade will use this report.

Runtime selection order

When /v1/Report or /v1/Report/download is called, the legacy facade resolves the report in this order:

  1. ?option=<report-key>
  2. ?report=<report-key>
  3. report.Settings.Default
  4. the first report available in report.Settings.Reports

Create a report configuration

Each report implementation lives under:

report.Configurations.<configurationKey>

For example:

report.Configurations.afvAll.FileName
report.Configurations.afvAll.Main.Filter.DimensionName
report.Configurations.afvAll.Columns.Date
report.Configurations.afvAll.Columns.Account
report.Configurations.afvAll.Filters.ScenarioName

Required and optional keys

File name

Optional, but recommended.

Key

report.Configurations.afvAll.FileName

Type

string

Example

AFV_Report

This becomes the prefix of the exported file name.

Dimension pre-filter

Optional, but useful for performance.

Key

report.Configurations.afvAll.Main.Filter.DimensionName

Type

string

Example

AFV Recognition

This is applied before the report rows are built, so the DB/runtime only returns the dimensions you want.

Columns

Columns are stored one key per column under:

report.Configurations.<configurationKey>.Columns.<columnKey>

Each value is JSON.

Example columns

Date

Key

report.Configurations.afvAll.Columns.Date

Type

{"name":"Date","expression":"from","type":"datetime","format":"yyyy-MM-dd","source":"scenarioInstance","order":1}
Time

Key

report.Configurations.afvAll.Columns.Time

Type

{"name":"Time","expression":"from","type":"datetime","format":"HH:mm:ss","source":"scenarioInstance","order":2}
Account

Key

report.Configurations.afvAll.Columns.Account

Type

{"name":"Account Name","expression":"username","type":"string","source":"user","order":3}
Dimension name

Key

report.Configurations.afvAll.Columns.DimensionName

Type

{"name":"Dimension Name","expression":"dimensionName","type":"string","source":"scenarioInstance","order":4}

Available column JSON properties

A column definition can use these fields:

  • name: output column header.
  • expression: JMESPath-like expression evaluated against the selected source.
  • type: string, numeric, or datetime.
  • format: used for datetime columns.
  • source: one of:
    • dimension
    • metadata
    • scenarioInstance
    • user
  • order: column order in export.
  • regex: optional regex applied after the expression result.
  • regexGroup: optional capture group index or group name.

Filters

Filters are stored under:

report.Configurations.<configurationKey>.Filters.<filterKey>

Each value is JSON.

Example filter

Key

report.Configurations.afvAll.Filters.ScenarioName

Type

{"name":"AFV All","expression":"scenario_type","value":"AFV","source":"metadata"}

Full example

Below is a small but complete report setup:

report.Settings.Reports

[
  {
    "key": "afv-all",
    "name": "AFV All",
    "configurationKey": "afvAll"
  }
]

report.Settings.Default

afv-all

report.Configurations.afvAll.FileName

AFV_Report

report.Configurations.afvAll.Main.Filter.DimensionName

AFV Recognition

report.Configurations.afvAll.Columns.Date

{"name":"Date","expression":"from","type":"datetime","format":"yyyy-MM-dd","source":"scenarioInstance","order":1}

report.Configurations.afvAll.Columns.Account

{"name":"Account Name","expression":"username","type":"string","source":"user","order":2}

report.Configurations.afvAll.Columns.DimensionName

{"name":"Dimension Name","expression":"dimensionName","type":"string","source":"scenarioInstance","order":3}

report.Configurations.afvAll.Filters.ScenarioName

{"name":"AFV All","expression":"scenario_type","value":"AFV","source":"metadata"}

Query parameters supported by the legacy facade

Select a report

/v1/Report/download?option=afv-all

or

/v1/Report/download?report=afv-all

Filter by user

userId is optional.

If it is provided, the facade:

  • sends externalHeatId=<userId> to dimension lookup,
  • keeps only dimensions that actually contain that user in dimensionUsers.

Example:

/v1/Report/download?from=2026-02-01T00:00:00.000Z&to=2026-02-27T23:59:59.999Z&userId=7bd8d6f2-864f-486c-b258-51ab3

How to add a new report

  1. Add a new entry to report.Settings.Reports.
  2. Set configurationKey to a unique value.
  3. Create:
    • report.Configurations.<configurationKey>.FileName
    • report.Configurations.<configurationKey>.Main.Filter.DimensionName if needed
    • report.Configurations.<configurationKey>.Columns.*
    • report.Configurations.<configurationKey>.Filters.*
  4. If you want it to be the default, update report.Settings.Default.
  5. Test with /v1/Report and /v1/Report/download.

Troubleshooting

Report downloads with no rows

Check:

  • the Main.Filter.DimensionName value,
  • the report filters under Filters.*,
  • whether the selected userId exists in dimensionUsers.

Export headers are wrong

Check the JSON stored in Columns.*, especially:

  • name
  • order
  • type

JSON parsing warnings

If the facade logs errors such as:

Invalid JSON for report.Configurations.afvAll.Columns.Date

then the stored config value is malformed JSON and must be corrected.

Session Query APIHEAT.Common Client (C#)