Skip to main content

Custom Report Export Pattern

Overview​

A report page and a Home dashboard report widget show Export to CSV and Export to Excel buttons in the report header. By default the platform builds the file from the report configuration. For a custom widget report this does not always fit: for example, a Program that returns running totals per month can end up with the months added together in the file.

A custom widget can give the header its own export data. The header keeps drawing the buttons, and both buttons write the data the widget gave. If the widget gives nothing, the export is the standard one.

The widget does this with pageContext.registerExport.

When to Use​

  • The file the platform builds from the report configuration has the wrong numbers or the wrong layout for your widget.
  • You want the file to look like the standard report export (for example one row per month and one column per category).
  • You do not need this when the standard export is already correct. A widget that never calls registerExport is exported exactly as before.

Applicable Layout Types​

TargetNotes
ReportLayoutReport pages, and report widgets shown on the Home dashboard. registerExport is in pageContext.

Other targets do not get registerExport.

How It Works​

PartWho does it
Drawing the Export to CSV and Export to Excel buttonsThe platform (report header). The widget draws no button.
Showing or hiding each buttonThe platform, by the layout template widget settings Export to CSV (config.allowExportToCsv) and Export to Excel (config.allowFilterExportInExcel).
The rows, the headers and the file nameThe widget, through registerExport.
The Excel filter details sheetThe platform (it is not changed).
The CSV button inside a drill-down popupThe widget, with ExportCSVButton (see Bucket-Based Drill-Down Report).

registerExport — Signature​

pageContext.registerExport(getter); // give the export data
pageContext.registerExport(null); // remove it again

// getter() returns:
{
data, // Array of row objects, keyed like the headers
headers, // Array of { label, key } (the order is the column order)
fileName, // Optional. File name without extension. Default: the platform's name
}
  • The getter is called by the header each time it draws the buttons, so it always reads the current rows.
  • data and headers are both required. If one is missing, the platform exports the standard way.
  • registerExport is undefined on a page that does not support it (an older SPA, or a target that is not a report). Always check it before calling.

Code Example — Long Layout (one row per bucket)​

Month, category and count in three columns, built from the Program's rows in pageContext.totalData.

function MyReportWidget(pageContext) {
const { totalData = [], registerExport } = pageContext;

// One export row per bucket.
const exportRows = React.useMemo(
() =>
totalData.map((row) => ({
month: row.monthLabel,
category: row.category,
count: row.instanceCount,
})),
[totalData]
);

const exportHeaders = [
{ label: 'Month', key: 'month' },
{ label: 'Category', key: 'category' },
{ label: 'Count', key: 'count' },
];

React.useEffect(() => {
if (typeof registerExport !== 'function') {
return undefined; // older SPA: the platform keeps its own export
}
registerExport(() => ({
data: exportRows,
headers: exportHeaders,
fileName: 'My_Report',
}));
return () => registerExport(null); // widget removed: back to the standard export
}, [registerExport, exportRows]);

// ...render the report as usual. No export button is needed here.
}

The file:

Month,Category,Count
"Oct-2025","Keys",1874
"Nov-2025","Keys",2194

Code Example — Wide Layout (one row per month, one column per category)​

Same layout as a standard pivot table export. The headers are built from the data, so a new category becomes a new column without a code change.

const categories = React.useMemo(
() => [...new Set(totalData.map((row) => row.category))],
[totalData]
);
const months = React.useMemo(
() => [...new Set(totalData.map((row) => row.monthLabel))],
[totalData]
);

const exportHeaders = React.useMemo(
() => [
{ label: 'Month', key: 'month' },
...categories.map((category) => ({ label: category, key: category })),
],
[categories]
);

const exportRows = React.useMemo(
() =>
months.map((month) => {
const row = { month };
totalData
.filter((r) => r.monthLabel === month)
.forEach((r) => {
row[r.category] = r.instanceCount;
});
return row;
}),
[months, totalData]
);

The file:

Month,Keys,Certificates
"Oct-2025",1874,52
"Nov-2025",2194,121

Notes​

  • One registration is enough for both buttons. The CSV and the Excel export write the same rows and headers. The Excel file also keeps the platform's filter details sheet.
  • Fallback. With no registration, with registerExport(null), or with an incomplete export (no data or no headers), the platform exports the standard way. An existing widget needs no change and no recompile.
  • Re-register when the data changes. Put the rows and the file name in the useEffect dependencies, as in the examples. The cleanup (registerExport(null)) puts the report back on the standard export when the widget is removed.
  • Headers. The CSV removes HTML tags from a header label (a label Device <br/> Classes becomes Device Classes); the Excel keeps the label as it is. This is the same as the standard export.
  • Date columns. Use the platform's own MMM-yyyy Month format and the tenant time zone for a month label, as described in Bucket-Based Drill-Down Report. If a header has attributeType Date, DateTime or Picklist, also give prefix: '' and suffix: '' (see ExportCSVButton).
  • File name. Build it like the platform: type name, report name, then the date and time in the tenant time zone, for example ResourcesReport-Resources Report Annual V1-13-10-2026 00_26. The platform adds the extension.
  • Buttons. Do not draw your own button for the main report export. Show or hide of the buttons is the layout template setting, the same as for every standard report.

Components Used​

ExportCSVButton (only for a button inside a drill-down popup, not for the main report export).