# Processing Reports

Canonical page: https://www.adaptabletools.com/docs/handbook-exporting-processing

- 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](https://www.adaptabletools.com/docs/dev-guide-row-models-server-overview/index.md))
- configure whether the Export should take place
- provide a changed (or, indeed, entirely different) set of report data

Processing should be avoided when using the `VisualExcel` Report Format

Processing is configured using the `processExport` property in [`Export Options`](https://www.adaptabletools.com/docs/reference/exportoptions.md) 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](https://www.adaptabletools.com/docs/adaptable-ql-expression/index.md))
- `false` - the export will be cancelled and no report will run

### `processExport`

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.

This is most typically the case when using the [Server-Side Row Model](https://www.adaptabletools.com/docs/dev-guide-row-models-server-overview/index.md)

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:

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

The function receives a [`processexportcontext`](https://www.adaptabletools.com/docs/reference/processexportcontext.md) object, which is defined as follows:

| Property | Type | Description |
| --- | --- | --- |
| [convertToCsv](https://www.adaptabletools.com/docs/reference/processexportcontext.md#converttocsv) | `(reportData: `[`ReportData`](https://www.adaptabletools.com/docs/reference/reportdata.md)`) => string` | Converts the Report Data to CSV format |
| [convertToExcel](https://www.adaptabletools.com/docs/reference/processexportcontext.md#converttoexcel) | `(reportData: `[`ReportData`](https://www.adaptabletools.com/docs/reference/reportdata.md)`) => Blob` | Converts the Report Data to Excel format |
| [getReportColumns](https://www.adaptabletools.com/docs/reference/processexportcontext.md#getreportcolumns) | `() => `[`ReportColumn`](https://www.adaptabletools.com/docs/reference/reportcolumn.md)`[]` | Returns Columns to export based on Report&#39;s `ReportColumnScope` |
| [adaptableContext](https://www.adaptabletools.com/docs/reference/processexportcontext.md#adaptablecontext) | `any` | 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](https://www.adaptabletools.com/docs/adaptable-ql-expression/index.md))
- `false` - the export will be cancelled and no report will run

The [`ExportResultData`](https://www.adaptabletools.com/docs/reference/exportresultdata.md) object defines the shape of the returned data:

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

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

<b>Cancelling an Export</b>

```ts {4}
// 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**.

This most typically happens when using the [Server-Side Row Model](https://www.adaptabletools.com/docs/dev-guide-row-models-server-exporting/index.md)

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

**Example: Processing: Creating Reports on Server**

Report processing to run report on server

 

- This demo illustrates how to use the `processExport` property in [Export Options](https://www.adaptabletools.com/docs/technical-reference-exporting/index.md) 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](https://www.adaptabletools.com/docs/dev-guide-row-models-server-overview/index.md) 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

- 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

Demo project (Vanilla); the files without a marker are shown below:

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts
  gridOptions.ts
  index.ts             [template]
  onAdaptableReady.ts
  rowData.ts           [template]
  styles.css           [template]
index.html             [template]
package.json           [template]
tsconfig.json          [template]
```

Files marked `[template]` are the same in every demo; see the [demo template](https://www.adaptabletools.com/llms/demo-template.md#vanilla).

**`src/adaptableOptions.ts`**

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

const API_BASE: string = process.env.NEXT_PUBLIC_ATHLETES_API_URL!;

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.Expression) {
        reportConfig.reportQueryAST =
          context.adaptableApi.expressionApi.getASTForExpression(report.Expression);
      }

      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',
          Expression: '[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},
          },
        },
      ],
    },
  },
};
```

**`src/onAdaptableReady.ts`**

```ts
import {AdaptableReadyInfo, AdaptableApi} from '@adaptabletools/adaptable';
import {
  ColDef,
  IServerSideDatasource,
  IServerSideGetRowsParams,
} from 'ag-grid-enterprise';

export const onAdaptableReady = ({
  adaptableApi,
  agGridApi,
}: AdaptableReadyInfo) => {
  agGridApi.setGridOption(
    'serverSideDatasource',
    createDataSource(adaptableApi)
  );
};

const API_BASE: string = process.env.NEXT_PUBLIC_ATHLETES_API_URL!;

function toServerFilterFields(adaptableApi: AdaptableApi) {
  const filterState = adaptableApi.stateApi.getAdaptableFilterState();
  const astNodes: unknown[] = [];
  if (filterState.gridFilterAST) {
    astNodes.push(
      ...(Array.isArray(filterState.gridFilterAST)
        ? filterState.gridFilterAST
        : [filterState.gridFilterAST])
    );
  }
  for (const columnFilter of filterState.columnFilters ?? []) {
    if (!columnFilter.Expression) {
      continue;
    }
    const ast = adaptableApi.expressionApi.getASTForExpression(
      columnFilter.Expression
    );
    astNodes.push(...(Array.isArray(ast) ? ast : [ast]));
  }
  return {
    adaptableFilters: [],
    gridFilterAST: astNodes.length ? astNodes : undefined,
  };
}

function createDataSource(adaptableApi: AdaptableApi): IServerSideDatasource {
  return {
    getRows(params: IServerSideGetRowsParams) {
      const customSorts = adaptableApi.customSortApi.getActiveCustomSorts();
      const serverFilters = toServerFilterFields(adaptableApi);

      const sortModel = params.request.sortModel.map(sort => {
        const customSort = customSorts.find(
          customSort => customSort.ColumnId === sort.colId
        );
        if (customSort) {
          return {
            ...sort,
            sortedValues: customSort.SortedValues,
          };
        }
        return sort;
      });

      const request = {
        ...params.request,
        sortModel,
        ...serverFilters,
        includeSQL: true,
      };

      fetch(API_BASE, {
        method: 'post',
        body: JSON.stringify(request),
        headers: {'Content-Type': 'application/json; charset=utf-8'},
      })
        .then(httpResponse => httpResponse.json())
        .then(response => {
          params.success({
            rowData: response.rows,
            rowCount: response.lastRow ?? 0,
          });

          adaptableApi.systemStatusApi.setInfoSystemStatus(
            `SQL: ${response.sql.slice(0, 40)}`,
            response.sql
          );
        })
        .catch(error => {
          params.fail();
        });
    },
  };
}
```

**`src/gridOptions.ts`**

```ts
import {GridOptions, themeBalham} from 'ag-grid-enterprise';

import {columnDefs} from './columnDefs';

export const gridOptions: GridOptions = {
  theme: themeBalham,
  defaultColDef: {
    sortable: true,
    filter: true,
    floatingFilter: true,
    enableRowGroup: true,
  },
  rowModelType: 'serverSide',
  columnDefs: columnDefs,
  sideBar: ['adaptable', 'columns', 'filters'],
};
```

**`src/columnDefs.ts`**

```ts
import {ColDef} from 'ag-grid-enterprise';

export const columnDefs: ColDef[] = [
  {field: 'id', hide: true, cellDataType: 'text'},
  {
    field: 'athlete',
    cellDataType: 'text',
    enableRowGroup: true,
    resizable: true,
  },
  {
    field: 'country',
    cellDataType: 'text',
    enableRowGroup: true,
    resizable: true,
  },
  {
    field: 'sport',
    cellDataType: 'text',
    enableRowGroup: true,
    resizable: true,
  },
  {
    field: 'year',
    cellDataType: 'number',
    enableRowGroup: true,
    resizable: true,
  },
  {
    field: 'gold',
    aggFunc: 'sum',
    cellDataType: 'number',
    enableValue: true,
    resizable: true,
  },
  {
    field: 'silver',
    aggFunc: 'sum',
    cellDataType: 'number',
    enableValue: true,
    resizable: true,
  },
  {
    field: 'bronze',
    aggFunc: 'sum',
    cellDataType: 'number',
    enableValue: true,
    resizable: true,
  },
];
```

## 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.

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

**Example: Processing: Stopping Export**

Report processing to stop Exports

 

- This demo illustrates how to use the `processExport` property in [Export Options](https://www.adaptabletools.com/docs/technical-reference-exporting/index.md) 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)

- 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

Demo project (Vanilla); the files without a marker are shown below:

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts        [template]
  gridOptions.ts       [template]
  index.ts             [template]
  onAdaptableReady.ts  [template]
  rowData.ts           [template]
  styles.css           [template]
index.html             [template]
package.json           [template]
tsconfig.json          [template]
```

Files marked `[template]` are the same in every demo; see the [demo template](https://www.adaptabletools.com/llms/demo-template.md#vanilla).

**`src/adaptableOptions.ts`**

```ts
import {
  AdaptableOptions,
  ProcessExportContext,
} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Process Prevent Export',
  exportOptions: {
    processExport: async (context: ProcessExportContext) => {
      if (context.report.Name === 'Current Layout') {
        context.adaptableApi.systemStatusApi.setWarningSystemStatus(
          'Cannot Run Report'
        );
        return false;
      }
      return true;
    },
  },
  initialState: {
    Dashboard: {
      Tabs: [
        {
          Name: 'Demo',
          Toolbars: ['Export', 'SystemStatus'],
        },
      ],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['Export'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Export: {
      CurrentReport: 'Current Layout',
      CurrentFormat: 'Excel',
    },
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'language',
            'week_issue_change',
            'github_stars',
            'created_at',
            'updated_at',
            'pushed_at',
            'license',
            'has_wiki',
            'github_watchers',
            'description',
            'open_issues_count',
            'closed_issues_count',
            'open_pr_count',
            'closed_pr_count',
            'has_projects',
            'has_pages',
            'topics',
          ],
          Name: 'Standard Layout',
          AutoSizeColumns: true,
        },
      ],
    },
  },
};
```

## Changing Report Data

The `processExport` function can also be used to change the data that will be displayed in the Report.

Use it to build the rows and columns for a Report and return them as an [`ExportResultData`](https://www.adaptabletools.com/docs/reference/exportresultdata.md) object.

AdapTable exports that data to the selected destination.

- A Layout with [Row Summaries](https://www.adaptabletools.com/docs/handbook-summarising-rows/index.md) is a common use case, as AG Grid includes those pinned rows in the All Data report
- If that is unwanted, use this function to strip out Row Summaries and return remaining data so export continues

**Example: Processing: Excluding Row Summaries**

Report processing to leave Row Summaries out of an export

- This demo shows a Layout with a Top and a Bottom Row Summary
- The Export toolbar is open, and the current report is `All Data` (CSV)
- For the `All Data` report, `processExport` keeps every data row, skips each Row Summary, and returns the report in the selected format
- Any other report returns `true`, so AdapTable exports it in the normal way, Row Summaries included

- Run the `All Data` report and open the file: the two summary rows are absent
- Switch to `Current Layout` and run it again: the summary rows are in the file

Demo project (Vanilla); the files without a marker are shown below:

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts        [template]
  gridOptions.ts       [template]
  index.ts             [template]
  onAdaptableReady.ts  [template]
  rowData.ts           [template]
  styles.css           [template]
index.html             [template]
package.json           [template]
tsconfig.json          [template]
```

Files marked `[template]` are the same in every demo; see the [demo template](https://www.adaptabletools.com/llms/demo-template.md#vanilla).

**`src/adaptableOptions.ts`**

```ts
import {
  AdaptableOptions,
  ExportResultData,
  ProcessExportContext,
  ReportData,
} from '@adaptabletools/adaptable';
import {IRowNode} from 'ag-grid-enterprise';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Process Skip Row Summaries',
  exportOptions: {
    processExport: async (context: ProcessExportContext) => {
      // Leave every report other than All Data to AdapTable.
      // VisualExcel keeps the grid's own export, including pinned rows.
      if (context.report.Name !== 'All Data' || context.reportFormat === 'VisualExcel') {
        return true;
      }

      const agGridApi = context.adaptableApi.agGridApi;
      const rows: WebFramework[] = [];

      const addRow = (node?: IRowNode | null) => {
        if (!node?.data || context.adaptableApi.gridApi.isSummaryNode(node)) {
          return;
        }
        rows.push(node.data);
      };

      // Body rows, then the pinned rows AG Grid would add to the export.
      agGridApi.forEachNode(addRow);
      for (let index = 0; index < agGridApi.getPinnedTopRowCount(); index++) {
        addRow(agGridApi.getPinnedTopRow(index));
      }
      for (let index = 0; index < agGridApi.getPinnedBottomRowCount(); index++) {
        addRow(agGridApi.getPinnedBottomRow(index));
      }

      const reportData: ReportData = {
        columns: context.getReportColumns(),
        rows,
      };

      if (context.reportFormat === 'JSON') {
        const jsonReport: ExportResultData = {type: 'json', data: reportData};
        return jsonReport;
      }
      if (context.reportFormat === 'CSV') {
        const csvReport: ExportResultData = {
          type: 'csv',
          data: context.convertToCsv(reportData),
        };
        return csvReport;
      }
      const excelReport: ExportResultData = {
        type: 'excel',
        data: context.convertToExcel(reportData),
      };
      return excelReport;
    },
  },
  initialState: {
    Dashboard: {
      Tabs: [
        {
          Name: 'Demo',
          Toolbars: ['Export'],
        },
      ],
    },
    Theme: {CurrentTheme: 'dark'},
    Export: {
      CurrentReport: 'All Data',
      CurrentFormat: 'CSV',
    },
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'language',
            'week_issue_change',
            'github_stars',
            'github_watchers',
            'created_at',
            'license',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'open_issues_count',
            'closed_issues_count',
            'open_pr_count',
            'closed_pr_count',
            'has_projects',
            'has_pages',
          ],
          RowSummaries: [
            {
              Position: 'Top',
              ColumnsMap: {
                github_watchers: 'SUM',
                github_stars: 'SUM',
                created_at: 'MIN',
              },
            },
            {
              Position: 'Bottom',
              ColumnsMap: {
                week_issue_change: 'AVG',
                language: 'COUNT',
              },
            },
          ],
          AutoSizeColumns: true,
        },
      ],
    },
  },
};
```
