Processing Reports

Summary

Developers can "process" (i.e. intercept) a report before it is evaluated and exported
This is used in 3 main use cases:
- running the report on the server and sending the data back to AdapTable
- cancelling a proposed Export
- providing entirely new column and row data

All AdapTable reports can be processed before they are exported.

This allows developers to provide a function implementation enabling them to:

evaluate the Report on the server (typically when using the Server-Side Row Model)
configure whether the Export should take place
provide an entirely different set of report data

Caution

Processing should be avoided when using the VisualExcel Report Format

Procesing is configured using the processExport property in Export Options which can return 3 values:

ExportResultData object (provided on Server) - will be used as data for Report and exported by AdapTable
true - Report will be evaluated by AdapTable as normal, using Grid data (provided by AdapTableQL)
false - the export will be cancelled and no report will run

processExport

Promise<ExportResultData | boolean>

Function invoked before a Report is run, enabling users to evaluate on the server or cancel the export

Typically AdapTable will take care of all that is required to run a Report and export the data to the specified destination.

However sometimes users might want to intercept this process to modify, or provide all, the data themselves.

Note

This is most typically the case when using the Server-Side Row Model

This property enables developers to check what data is about to be exported.

If this function is provided, it will be invoked when a Report is run, enabling users to preload the data prior to an export.

The function definition is as follows:

processExport?: (processExportContext: ProcessExportContext) => Promise<ExportResultData | boolean>;

The function receives a processexportcontext object, which is defined as follows:

Property	Description
convertToCsv	Converts the Report Data to CSV format
convertToExcel	Converts the Report Data to Excel format
getReportColumns	Returns Columns to export based on Report's `ReportColumnScope`
adaptableContext	Custom application Context provided in `AdaptableOptions.adaptableContext`

and it can return 3 values:

ExportResultData object - will be used as the data for the Report and will be exported by AdapTable
true - the Report will be evaluated by AdapTable as normal, using the data from the Grid (provided by AdapTableQL)
false - the export will be cancelled and no report will run

The ExportResultData object defines the shape of the returned data:

export type ExportResultData =
| {
    type: 'csv';
    data: string;
  }
| {
    type: 'json';
    data: ReportData;
  }
| {
    type: 'excel';
    data: Blob | string;
  };

Hint

The ExportResultData is returned asyncronously via a Promise (and so can the boolean values if required)

Cancelling an Export

// Don't allow Current Layout report to be run
const adaptableOptions: AdaptableOptions = {
    exportOptions: {
      processExport: async (context: ProcessExportContext) => {
        if (context.report.Name === 'Current Layout') {
          return false;
        }
      },
    }
}

Exporting via the Server

The most common use case for processing reports is when running export on the server.

Hint

This most typically happens when using the Server-Side Row Model

Developers can evaluate the report on the server, and return the report data to AdapTable for it to export to the selected destination.

Processing: Creating Reports on Server

Fork Fork

This demo illustrates how to use the processExport property in Export Options to create report data on the Server and return to AdapTable to export
It is taken from the more extensive Server-Side Row Model Demo focussing purely on Export
Both the (System) 'All Data', and the (Custom) 'US Golden Athletes' Reports are evaluated on the server, and the data is sent back to AdapTable to export

Try It Out

Run the 'All Data' or 'US Golden Athletes' Reports and note how the data is provided 'on the server' and then send back to AdapTable

import {
  AdaptableColumnBase,
  AdaptableOptions,
  ProcessExportContext,
  Report,
  ExportResultData,
  ReportData,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

const API_BASE: string = 'https://serverside-demo.adaptabletools.com/.netlify/functions/athletes'!;

interface RequestReportConfig {
  report: Report;
  reportColumns: AdaptableColumnBase[];
  reportQueryAST?: any;
}

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  userName: 'Server-side Demo',
  adaptableId: 'Process Run on Server',
  exportOptions: {
    processExport: async (context: ProcessExportContext) => {
      const {report, reportFormat} = context;
      const reportConfig: RequestReportConfig = {
        report,
        reportColumns: context.getReportColumns(),
      };
      if (report.Query?.BooleanExpression) {
        reportConfig.reportQueryAST =
          context.adaptableApi.expressionApi.getASTForExpression(
            report.Query.BooleanExpression
          );
      }

      const serverSideResponse = await fetch(`${API_BASE}/report`, {
        method: 'post',
        body: JSON.stringify(reportConfig),
        headers: {'Content-Type': 'application/json; charset=utf-8'},
      });

      const jsonReportData: ReportData = await serverSideResponse.json();

      if (reportFormat === 'JSON') {
        const serverSideReportData: ExportResultData = {
          type: 'json',
          data: jsonReportData,
        };
        return serverSideReportData;
      }
      if (reportFormat === 'CSV') {
        const csvReportData = context.convertToCsv(jsonReportData);
        const serverSideReportData: ExportResultData = {
          type: 'csv',
          data: csvReportData,
        };
        return serverSideReportData;
      }
      if (reportFormat === 'Excel' || reportFormat === 'VisualExcel') {
        const excelReportData = context.convertToExcel(jsonReportData);
        const serverSideReportData: ExportResultData = {
          type: 'excel',
          data: excelReportData,
        };
        return serverSideReportData;
      }

      context.adaptableApi.alertApi.showAlertWarning(
        'Cannot Run Report',
        `Report Format ${reportFormat} not supported`
      );
      return false;
    },
    systemReportNames: ['All Data'],
  },
  initialState: {
    Dashboard: {
      Tabs: [
        {
          Name: 'Main',
          Toolbars: ['Export'],
        },
      ],
    },
    Theme: {
      CurrentTheme: 'dark',
    },
    Export: {
      CurrentReport: 'US Golden Athletes',
      CurrentFormat: 'Excel',
      Reports: [
        {
          Name: 'US Golden Athletes',
          ReportColumnScope: 'ScopeColumns',
          Scope: {
            ColumnIds: ['athlete', 'gold', 'sport', 'year', 'country'],
          },
          ReportRowScope: 'ExpressionRows',
          Query: {
            BooleanExpression: '[country]="United States" AND [gold]>0',
          },
        },
      ],
    },
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'athlete',
            'gold',
            'silver',
            'bronze',
            'totalMedals',
            'country',
            'sport',
            'year',
          ],
          ColumnSizing: {
            athlete: {Width: 175},
            bronze: {Width: 100},
            country: {Width: 125},
            gold: {Width: 100},
            silver: {Width: 100},
            sport: {Width: 175},
            totalMedals: {Width: 100},
            year: {Width: 115},
          },
        },
      ],
    },
  },
};

Cancelling an Export

Because the function can return a boolean, this can be leveraged to set whether the proposed Report runs.

This allows developers to decide dynamically whether or not the user can run the given report.

Hint

The boolean value can be returned asynchronously if required, allowing server permission checks

Processing: Stopping Export

Fork Fork

This demo illustrates how to use the processExport property in Export Options to stop a particular Report from being run.
We do not allow the Current Layout report to be run (and output a System Status Message to that effect)

Try It Out

Run the 'Current Layout' Report and note that the export is prevented (with a System Status Message displayed)
Switch to a different Report and this time the export works as normal

Processing Reports

(Recorded with AdapTable v18.0)

PreviousFormatting Reports NextScheduling Reports