Export Technical Reference
Summary
- The Live Data Changed Event is fired when data is changed in a Live Report (e.g. ipushpull)
- The Export API contains functions to manage exporting and reports programmatically
Export State
The Export section of Initial Adaptable State contains details of the current Report and Report Format Type, and a collection of User-provided Report objects:
| Property | Type | Description |
|---|---|---|
| CurrentFormat | ReportFormatType | Selected Report Format - in Export Toolbar & Tool Panel |
| CurrentReport | ReportNameType | Selected Report Type - in Export Toolbar & Tool Panel |
| Reports | Report[] | User-created Reports; each has Name and Row and Column Scope |
| ReportSchedules | ReportSchedule[] | Scheduled Exports for System and Custom Reports |
Report
The Report object is defined as follows:
| Property | Type | Description |
|---|---|---|
| Name | ReportNameType | Name of the Report as displayed in the Export toolbar and tool panel |
| Query | AdaptableBooleanQuery | Query to use; only required if ReportRowScope is 'ExpressionRows' |
| ReportColumnScope | ReportColumnScope | Columns to display: AllColumns, VisibleColumns, SelectedColumns, ScopeColumns |
| ReportRowScope | ReportRowScope | Rows to export: AllRows, VisibleRows, SelectedRows, ExpressionRows |
| Scope | ColumnScope | Columns Scope; only required if ReportColumnScope is 'ScopeColumns' |
| IsReadOnly | boolean | Sets Entity to ReadOnly (overwriting a Strategy Entitlement of 'Full') |
Schedules
The ReportSchedule object contains information about the object being scheduled and is defined as follows:
| Property | Type | Description |
|---|---|---|
| ExportDestination | ExportDestinationType | Destination of Report to run on Schedule |
| Name | string | Unique display name for this scheduled report |
| ReportFormat | ReportFormatType | Format of Report to run on Schedule |
| ReportName | ReportNameType | Name of Report to export |
| Schedule | Schedule | When the export should run |
| IsReadOnly | boolean | Sets Entity to ReadOnly (overwriting a Strategy Entitlement of 'Full') |
| IsSuspended | boolean | Suspends (i.e. turns off) an Adaptable Object |
The actual scheduling is provided in the Schedule object, which is defined as follows:
| Property | Type | Description |
|---|---|---|
| CronExpression | string | Standard 5-field cron (minute hour day-of-month month day-of-week); e.g. weekdays at 09:30 → 30 9 * * 1-5 |
| IsOneOff | boolean | If true, the schedule runs once (using RunAt) |
| RunAt | string | ISO datetime for a one-off run (local time); set when IsOneOff is true |
Export Options
The Export Options section of Adaptable Options contains these properties:
| Property | Type | Description | Default |
|---|---|---|---|
| appendFileTimestamp | boolean | Whether to add a timestamp as a suffix to exported file name | false |
| csvSeparator | string | ((csvSeparatorContext:BaseExportContext) => string) | Separator for CSV exports | ',' |
| customDestinations | CustomDestination[] | ((context:CustomDestinationsContext) =>CustomDestination[]) | User-provided Report Destinations (in addition to those shipped in AdapTable) | |
| excelSheetName | string | ((excelSheetNameContext:BaseExportContext) => string) | Provides a custom name for the Excel sheet when exporting to Excel | 'Sheet 1' |
| exportDataFormat | DataFormatType|DataFormatDataType| ((context:ExportDataFormatContext<TData>) =>DataFormatType) | Sets 'rawValue' or 'formattedValue' as Data format in Reports; can be set for whole grid, per Data Type, or per Column (via a function) | rawValue |
| exportDateFormat | string | ((context:ExportDateFormatContext<TData>) => string) | Optional custom format for Date columns when exporting | undefined |
| getDetailRows | (context:GetDetailRowsContext<TData>) => CsvDetailRow[] | ExcelDetailRow[] | undefined | Function to provide the Detail Rows when exporting in Master-Detail grids. This function will be invoked for each master row node. | |
| isColumnExportable | (context:AdaptableColumnContext) => boolean | Whether a Column is included in System Reports and available in UI for selection | true |
| processExport | (processExportContext:ProcessExportContext) => Promise<ExportResultData | boolean> | Provides custom handling of the Export process before the default export is executed. | |
| reportFilename | (reportFileNameContext:ReportFileNameContext) => string | Provide a bespoke file name for the Report | |
| skipColumnHeaders | boolean | ((skipColumnHeadersContext:BaseExportContext) => boolean) | Whether to exclude Column Headers from the exported data | false |
| systemExportDestinations | SystemExportDestination[] | ((context:SystemExportDestinationsContext) =>SystemExportDestination[]) | Export destinations to use; leave unset for all, empty array for none | 'Download', 'Clipboard' |
| systemReportFormats | SystemReportFormat[] | ((context:SystemReportFormatsContext) =>SystemReportFormat[]) | System Report Formats to use; leave unset for all, empty array for none | 'Excel', 'VisualExcel', 'CSV', 'JSON' |
| systemReportNames | SystemReportName[] | ((context:SystemReportNamesContext) =>SystemReportName[]) | System Reports to use; leave unset for all, empty array for none | 'All Data', 'Current Layout', 'Selected Data', |
Export API
The Export API section of Adaptable API contains a number of functions enabling Reports to be run - and managed more generally - at run-time:
| Method | Returns | Description |
|---|---|---|
| addScheduledReport(reportSchedule) | void | Adds a scheduled report |
| applyScheduledReport(reportSchedule) | void | Runs a scheduled export and records the job-run action |
| canExportToCsv() | boolean | If this AdapTable instance can to export to CSV; if false, the Export to Csv option will not be visible |
| canExportToExcel() | boolean | If this AdapTable instance can to export to Excel; if false, the Export to Excel option will not be visible |
| clearFormat() | void | Sets the Report Format to null |
| clearReport() | void | Sets the Report to null |
| deleteScheduledReport(reportSchedule) | void | Deletes a scheduled report |
| editScheduledReport(reportSchedule) | void | Edits a scheduled report |
| ensureScheduledReportUuids() | void | Ensures every scheduled report has a unique Uuid (legacy state may omit them). |
| exportReport(reportName, format, destination, exportConfig) | Promise<void> | Exports the Report with the given Name and Format to the given Destination |
| getActiveScheduledReports(config) | ReportSchedule[] | All active scheduled reports (custom reports and system reports) |
| getAllExportDestinations() | ExportDestinationType[] | Retrieves the available export destinations |
| getAllFormats() | ReportFormatType[] | Retrieves all Report Formats that are available |
| getAllReports() | Report[] | Retrieves all available Reports - System and User-created Reports |
| getAvailableCustomDestinations() | CustomDestination[] | Retrieves available Custom Destinations (configured in Export Options) |
| getAvailableSystemDestinations() | SystemExportDestination[] | Retrieves available System Export Destinations (configured in Export Options) |
| getAvailableSystemFormats() | SystemReportFormat[] | Retrieves available System Report Formats (configured in Export Options) |
| getAvailableSystemReports() | SystemReportName[] | Retrieves available System Reports (configured in Export Options) |
| getCurrentReport() | Report | undefined | Retrieves currently selected Report in Adaptable State |
| getCurrentReportFormat() | ReportFormatType | undefined | Retrieves name of currently selected Report |
| getCurrentReportName() | ReportNameType | undefined | Retrieves name of currently selected Report |
| getCustomReports() | Report[] | Retrieves all Custom Reports that have been created by the User |
| getDestinationByName(destinationName) | SystemExportDestination|CustomDestination | undefined | Retrieves Destination with the given name |
| getExportDestinationForm(destinationName) | AdaptableForm<ExportFormContext> | undefined | Form Data entered by the User in the UI for a Custom Destination |
| getExportState() | ExportState | Retrieves Export section from Adaptable State |
| getReportById(id) | Report | Retrieves Report by Id |
| getReportByName(reportName) | Report | undefined | Retrieves Report with the given name |
| getReportData(reportName, format, config) | Promise<ExportResultData> | Gets the data for the Report with the given Name in the given Format |
| getScheduledReportById(reportScheduleId, config) | ReportSchedule | undefined | Retrieves a scheduled report by its Uuid |
| getScheduledReports(config) | ReportSchedule[] | All scheduled reports (custom reports and system reports) |
| getSupportedExportDestinations(reportFormat) | ExportDestinationType[] | Retrieves the Export Destinations that are supported for the given Report Format |
| isColumnExportable(adaptablColumn) | boolean | Returns whether the given column is exportable |
| isExportDestinationSystem(destinationName) | boolean | If the given destination is a System one |
| openExportSettingsPanel() | void | Open Settings Panel with Export section selected |
| selectFormat(reportFormat) | void | Selects the Report Format for Export |
| selectReport(reportName) | void | Selects the Report in the Adaptable State |
| suspendScheduledReport(reportSchedule) | void | Suspends a scheduled report |
| unSuspendScheduledReport(reportSchedule) | void | Unsuspends a scheduled report |
| updateReport(report) | Report | Updates an existing report |
| updateReports(reports) | Report[] | Updates existing reports |
Report Schedule Ran Event
The Report Schedule Ran Event is published whenever any report runs on a Schedule.
The ReportScheduleRanInfo provides full information on the Report and the Schedule:
| Property | Type | Description |
|---|---|---|
| RanAt | string | ISO datetime when Schedule ran (useful for logging) |
| reportSchedule | ReportSchedule | Report schedule that was triggered (if applicable) |
| adaptableContext | any | Custom application Context provided in AdaptableOptions.adaptableContext |
Live Data Changed Event
The Live Data Changed Event is published whenever any report which contains Live Data (i.e. if using ipushpull or OpenFin plugins) is changed.
Live Report
The Live Report defines which Adaptable Reports are 'Live' (i.e. they will update the destination as the data in Adaptable ticks or changes):
Note
When Adaptable creates a Live Report it will take care of updating the destination as the data in the Report changes (based on the throttle time it is given).
| Property | Type | Description |
|---|---|---|
| pageName | string | For OpenFin this is the workbook name; for iPushpull the page name |
| report | Report | The underlying Report |
| reportDestination | 'OpenfinExcel' | 'ipushpull' | Where the live data is being sent |