Export

The Export Function provides a way to send data from AdapTable via saveable 'Reports' that can be run either manually or on a schedule.

note

AdapTable will always export the raw (i.e. underlying) value of any cell

Adaptable will popuplate the Export dropdown with your reports (and the shipped System reports) and allows you to export the data to a number of destinations.

Each Report has both Row and Column Scope to allow you define which Rows and Columns are contained in the Export

Reports

AdapTable allows you to create Reports which you can then send to multiple destinations.

There are 3 types of reports you can run:

  1. System Reports

  2. User Reports

  3. Custom Reports

Each report essentially contains 2 elements:

  1. Details of which Columns will be exported
  2. Details of which Rows will be exported

System Reports

AdapTable ships with 4 predefined reports designed for frequently used exports. These are:

ReportContainsNotes
All DataAll Data in the Grid's DatasetIncludes filtered columns and rows
Visible DataAll currently filtered columns and rowsIncludes data not in current viewport
Selected CellsCurrently selected cells in the GridDo not need to be contiguous
Selected RowsCurrently selected rows in the GridDo not need to be contiguous
note

By default all 4 System Reports will be present; use the SystemReportNames of Export Config to change this by providing a custom list.

export default {
Export: {
// Don't use the Selected Cells or Selected Rows System Reports
SystemReportNames: ['All Data', 'Visible Data'],
}
},as PredefinedConfig;
tip

Leave the property empty to see all 4 System reports, or provide an empty array to have none available

User Reports

User can provide at design-time (through Export State) or at run-time (via the Report Wizard) their own reports.

Each User Report will have its own column definition and row query.

export default {
Export: {
CurrentReport: 'My Team Big Invoice',
Reports: [
{
Name: 'My Team Big Invoice',
ReportRowScope: 'ExpressionRows',
Expression: '[currency]="EUR',
ReportColumnScope: 'ScopeColumns',
Scope: {
ColumnIds: [
'OrderId',
'ChangeLastOrder',
'ContactName',
'InvoicedCost',
'ItemCost',
'ItemCount',
'OrderCost',
'OrderDate',
],
}
},
],
}
}, as PredefinedConfig;

Custom Reports

Custom Reports are reports entirely generated at run-time by the User with no input from AdapTable.

caution

Custon Reports do not need to include data (or columns) present in the grid in the exported data set.

Instead the data in the export is fetched each time the report is run via a function provided in UserFunctions (and referenced in Export State).

This allows developers to provide their own reports but still to leverage AdapTable state, scheduling and report destinations.

To define a Custom Report you need to do 3 things:

  1. Set the ReportColumnScope to CustomColumns
  2. Set the ReportRowScope to CustomRows
  3. Provide an implementation of the Custom Report User Function in which the data is returned in the form of a ReportData object
// In Predefined Config define the Report
// and provide a name for the CustomReport Function
export default {
Export: {
Reports: [
{
ReportColumnScope: 'CustomColumns',
ReportRowScope: 'CustomRows',
Name: 'People Report',
CustomReportFunction: 'getDummyData',
},
],
CurrentReport: 'People Report',
}
}, as PredefinedConfig;
// In Adaptable Options / User Functions provide report implementation
adaptableOptions.userFunctions = [
{
type: 'CustomReportFunction',
name: 'getDummyData',
handler(reportName: string) {
// will typically run on server but here we just provide some dummy data
// note it takes the form of ReportData object, with 'columns' and 'rows' sections
const reportData: ReportData = {
columns: [
{
ColumnId: 'Name',
FriendlyName: 'Name',
DataType: 'String',
},
{
ColumnId: 'Age',
FriendlyName: 'Age',
DataType: 'Number',
},
{
ColumnId: 'Location',
FriendlyName: 'Location',
DataType: 'String',
},
],
rows: [
{ Name: 'Joe', Age: 52, Location: 'London' },
{ Name: 'Dawn', Age: 39, Location: 'New York' },
{ Name: 'Peter', Location: 'France' },
{ Name: 'Eleanor', Age: 525 },
],
};
return reportData;
},
},
]

Export Destinations

A report can be sent to a number of different locations including:

  • Excel
  • CSV
  • Clipboard
  • JSON
tip

The Export to JSON sends the data using the ReportData format

and also - depending on whether the appropriate plugin is loaded:

Custom Destinations

If the Export Destinations offered by AdapTable are insufficient, developers can easily add their own custom report destinations via a user function.

As with all instances where a JavaScript function needs to be provided to AdapTable, this is done in 2 steps:

note

Predefined Config is stored as JSON so cannot include JavaScript functions (as they cannot be stringifed)

  1. Provide a custom, named implementation of the CustomExportDestination User Function in the User Functions section of Adaptable Options.

  2. Reference that function by name in the CustomDestinations property (in Export section of Config).

AdapTable will then call this function whenever a report needs to be sent to that destination.

// In Predefined Config add the Custom Destinaation (here 'REST Endpoint')
export default {
Export: {
CustomDestinations: [
{
Name: 'REST Endpoint',
},
],
}
}, as PredefinedConfig;
// In Adaptable Options / User Functions provide function implementation
adaptableOptions.userFunctions = [
{
name: 'REST Endpoint',
type: 'CustomExportDestinationFunction',
handler(report: Report, reportData: ReportData) {
// handle the report data sending it to your email client
},
},
]

Custom Destination Forms

Sometimes you might wish to send additional information to the custom destination e.g. an email address.

This can be done by providing DynamicFormDef information in your Predefined Config.

warning

This functionality is only availaible in AdapTable v7.1 and later

note

AdapTable will read this form definition metadata and create a form dynamically (including default values).

It will then send the completed form data as part of the user function args.

// In Predefined Config add the Custom Destinaation (here 'Email')
export default {
Export: {
CustomDestinations: [
{
Name: 'Email',
Form: {
Title: 'Email Settings',
Description: 'Provide email details ',
Fields: [
{
Name: 'emailAddress',
Label: 'Email Address',
Type: 'text',
DefaultValue: 'support@adaptabletools.com',
},
{
Name: 'subject',
Label: 'Email Subject',
Type: 'text',
DefaultValue: 'AdapTable Report Data',
},
{
Name: 'body',
Label: 'Email Body',
Type: 'text',
},
],
},
},
],
}
}, as PredefinedConfig;
// In Adaptable Options / User Functions provide function implementation
// Note that it receives a customDestinationData arg containing completed form data
adaptableOptions.userFunctions = [
{
name: 'Email',
type: 'CustomExportDestinationFunction',
handler(report: Report, reportData: ReportData, customDestinationData) {
console.log(report.Name);
console.log(
'will export to email:',
reportData,
customDestinationData
);
},
},
]
tip

If the Custom Destination forms part of a Schedule export, the same dynamic form and form fields will be displayed in the Schedule Wizard

Schedules

You can schedule your exports to run at at time of your choosing or export manually whenever you want, e.g. you can create an 'End of Day' Report to run every weekeday at 17:30.

note

Details of the schedule are stored in the Schedule section of Adaptable State.

export default {
//Define the Report in the Export Section
Export: {
CurrentReport: 'My Team Big Invoice',
Reports: [
{
Name: 'End of Day',
ReportColumnScope: 'ScopeColumns',
ReportRowScope: 'VisibleRows',
ReportColumnScope: 'AllColumns',
},
],
},
// Define the Schedule in the Schedule Section - the Report Name should match
Schedule: {
ReportSchedules: [
{
ScheduleType: 'Report',
ReportName: 'End of Day',
ExportDestination: 'Excel',
Schedule: {
DaysOfWeek: [1, 2, 3, 4, 5],
Hour: 17,
Minute: 30,
},
},
],
}, as PredefinedConfig;

UI Elements

Export includes the following UI Elements:

  • Popup - Shows all the available Reports together with an option to export to a destination of the User's choice. Plus an Add button to start the Export Wizard.

  • Toolbar - Shows all the available Reports together with an option to export to a destination of the User's choice. Also includes a Schedule button to enable reports to be run on Schedules.

  • Tool Panel - Same as Toolbar above.

Entitlements

Export Entitlement Rules:

  • Full: All Reports can be run and User Reports can be created / updated / deleted

  • Hidden: Reports can be run but not edited

  • ReadOnly: N/A

Export Predefined Config

The Export Predefined Config allows developers to pre-populate their State with Reports, Custom Destinations and much else.

export default {
Export: {
CurrentReport: 'My Team Big Invoice',
SystemReportNames: ['All Data', 'Visible Data', 'Selected Cells'],
Reports: [
{
Expression: '[currency]="EUR',
Name: 'My Team Big Invoice',
ReportColumnScope: 'AllColumns',
ReportRowScope: 'ExpressionRows',
},
{
Name: 'End of Day',
ReportColumnScope: 'ScopeColumns',
ReportRowScope: 'VisibleRows',
Scope: {
ColumnIds: [
'OrderId',
'ChangeLastOrder',
'ContactName',
'InvoicedCost',
'ItemCost',
'ItemCount',
'OrderCost',
'OrderDate',
],
}
},
],
},
Schedule: {
ReportSchedules: [
{
ScheduleType: 'Report',
ReportName: 'End of Day',
ExportDestination: 'Excel',
Schedule: {
DaysOfWeek: [1, 2, 3, 4, 5],
Hour: 17,
Minute: 30,
},
},
],
}, as PredefinedConfig;

In this example we have created 2 Reports

  • 'My Team Big Invoice' (the currently selected one) - which exports ALL Columns and any rows where the 'InvoicedCost' Column > 1000 AND the 'Employee' column value is one of 'Robert King', 'Margaret Peacock' or 'Anne Dodsworth'
  • 'End of Day' - which exports 8 named Columns and ALL Rows. Note: we have also defined a Schedule so that the 'End of Day' Report will export to Excel automatically every weekday at 17:30

Export Options

There are a few export-related options in the Export Options of Adaptable Options:

Exporting Styles

Export is a Data Export and not a WYSIWYG operation.

This means that AdapTable exports the raw values in the cells in the Report (and not the display values).

It also means that - with one exception - AdapTable does not export AdapTable Styles in a report.

The one exception is when Exporting the Visible Data System Report to Excel - which will include any Cell Styles that have been set in AdapTable functions (e.g. Conditional Styles, Formmat Column etc.).

tip

To turn this off, set the exportToExcelWithStyles property to false in Export Options

Date Format

AdapTable exports the underlying raw data of the Grid.

This is by design as exporting a numeric cell which had been formatted in AdapTable with '$' for example would cause problems in the export destination.

However for dates this can cause a problem as the JavaScript date format might not be readily understood by the Export destination (e.g. Excel).

AdapTable therefore formats all dates prior to Export, using the format set in the exportDateFormat property of Export Options.

note

The default value for this property is 'dd-MM-yyyy'

Export API

The Export Api section of Adaptable API has a number of useful export-related functions:

MethodDescription
canExportToExcel()If this AdapTable instance can to export to Excel; if false, the Export to Excel option will not be visible
editReport(report)Edits an existing report
exportDataToExcel(reportData, fileName)Exports data to Excel
getAllCustomDestination()Retrieves all Custom Destinations in Export State
getAllReports()Retrieves all Reports in State - both System and User-created Reports
getAvailableSystemReports()Retrieves System Reports section of Export State
getCurrentReport()Retrieves currently selected Report
getCurrentReportName()Retrieves name of currently selected Report
getExportState()Retrieves Export section from Adaptable State
getFormDefForExportDestination(destinationName)Form Data entered by the User in the UI for a Custom Destination
getReportByName(reportName)Retrieves Report with the given name
getReportSchedules()Retrieves all Report Schedules
isDataChangeInReport(dataChangedInfo, report)Whether given data change affects given report
isExportDestinationCustom(destinationName)If the given destination is a Custom one
sendReport(reportName, destination, destinationData)Sends a Report to a given destination
showExportPopup()Opens Export popup screen

FAQ

Is the export 'live' - will it update when the grid data changes?

No - export is a one time only snapshot.

However AdapTable does have other Functions (all available as Plugins) which do offer Live Data e.g. ipushpull, Glue42 and OpenFin

Do you include column names in the exported data?

Yes, column names are always included in the report.

Is there an option when just copying to the clipboard to exclude column names?

Not at present but this feature will be added in future releases.

Is there a limit on the number of reports that I can create?

No, reports like all other Adaptable Objects are unlimited.

Can I export the display formatted cell value in the column and not the raw value?

No, not at present. Export is a Data export and not a WYSIWYG function. However this will be addressed in future versions.

Why can I not see the Excel destination?

If you are using ag-Grid then you need to be using either ag-Grid Enterprise or have the 'Excel' module loaded for this option to be available.

Can I run a Report even though it will display data not in AdapTable?

Yes, use a Custom Report. Simply provide the function that will called each time the function runs and it can include any data you want.

Can I remove some System Reports?

Yes, via the SystemReportNames property in Export Predefined Config which was introduced in v7.2

More Information