Skip to main content
Version: 13.x (Current)

CRUD Export

<bk-export></bk-export>

The CRUD Export client is a business-logic webcomponent that handles the export of an entire collection from a backend Mia-Platform CRUD Service resource. It works as ndjson fetcher as well as native file downloader which uses browser download native API.

If export must be performed on a CRUD Service resource, an export route is available at <collection-name>/export and supports mongoDB queries as per CRUD Service specifications, along with __STATE__ filtering.

The CRUD Export listens to any filtering done on the plugin in which it is mounted by accessing any change-query event and by keeping an internal representation of all applied filter.

When the Export CRUD picks up a request for data export (that is, when it listens to an export-data event), it initiates the data export.

How to configure

For its most basic usage, the CRUD Export requires properties basePath and dataSchema to be specified.

{
"tag": "bk-export",
"properties": {
"basePath": "/orders/export",
"dataSchema": {
"type": "object",
"properties": {
"_id": {"type": "string"},
"__STATE__": {"type": "string"},
"name": {"type": "string"}
}
}
}
}

basePath is the targeted endpoint for performing data export, while dataSchema provides information on the structure of the data of the associated CRUD Service collection.

Export With User Config

It is possible to use the bk-export-modal component with the bk-export by setting userConfig to true. A primary key should be specified for the targeted collection via property primaryKey, which defaults to _id.

It is not possible to use the nativeDownload property when userConfig is true.

It provides 2 modes:

  1. CSV
  2. Excel

To open an export transaction it listens to an export-data event and return an export-data/awaiting-config event which carries along the following payload

export type AwaitUserConfig = {
total?: number
selected?: number
columns: Option[]
}

where

  • total is the last count of queried items,
  • selected is the count of currently selected items and
  • columns are selectable columns from the data-schema

a Meta contains the transactionId and must be re-cast when options are selected. An export-data/user-config event must then follow with payload

export type ExportUserConfig = {
exportType: 'csv' | 'xlsx'
csvSeparator?: 'COMMA' | 'SEMICOLON'
filters: 'all' | 'filtered' | 'selected'
columns: string[]
}

Example of configuration:

{
"tag": "bk-export",
"properties": {
"basePath": "/orders/export",
"userConfig": true,
"dataSchema": {
"type": "object",
"properties": {
"_id": {"type": "string"},
"__STATE__": {"type": "string"},
"name": {"type": "string"}
}
}
}
}

Stream Saver

In order to handle large sized file, on CRUD export data, a service worker is registered to perform local storage persistence operations instead of using large chunks of memory. To do so an external resource is needed. You can also use the same resource hosted with back-kit JS bundle available at <back-kit endpoint>/export-service-worker.html. In the latter case set streamSaverIFrameSrc to the resource endpoint.

{
"tag": "bk-export",
"properties": {
"basePath": "/orders/export",
"dataSchema": {
"type": "object",
"properties": {
"_id": {"type": "string"},
"__STATE__": {"type": "string"},
"name": {"type": "string"}
}
},
"streamSaverIFrameSrc": "/back-kit/{{BACK_KIT_VERSION}}/export-service-worker.html",
}
}
danger

The stream saver doesn't work properly on Firefox browser because of a known bug. It is actually marked as fixed but sometimes the first download doesn't work. The only way to bypass this problem is using the nativeDownload prop set to true (but remember that large files could freeze the browser).

Export Modes

Export modes are controlled by the boolean prop nativeDownload:

  • when false (default), it performs an HTTP GET and parses the content as ndjson
  • when true, it delegates to the browser API by creating and clicking an anchor tag with the url specified by the basePath property. It can't be used when userConfig is set to true.

The CRUD Export notifies the outcome of the export to other components, emitting success or error events. If native-download is not enabled (nativeDownload property is set to false), the events are emitted after the export is over (or on failure). Otherwise, a result event is emitted right after the download request has been issued, rather than after the download has been completed. This limitation arises due to the nature of native downloads, as there is no built-in mechanism to determine when a download is complete. As a result, the CRUD Export is unable to confirm download completion.

API

Properties & Attributes

propertyattributetypedefaultdescription
basePath-string-the URL base path to which to send HTTP requests
headers-{[key: string]: string}-headers to add when an HTTP request is sent
credentials-'include'|'omit'|'same-origin'-credentials policy to apply to HTTP requests
dataSchema-ExtendedJSONSchema7Definition-data-schema describing which field to retrieve from CRUD collection
nativeDownloadnative-downloadboolean-when true it skips frontend blob parsing and uses browser native download API
shouldIncludeProjectionsshould-include-projectionsbooleanfalseshould append projection when exporting from CRUD service
streamSaverIFrameSrcstream-saver-iframe-srcstring-location where stream saver service worker files are served
userConfiguser-configbooleanfalsewhether to listen to awaiting-for-export-configuration or not. It must be true to use it with bk-export-modal.
primaryKeyprimary-keystring_idprimary key to filter selected data when selected only export in bk-export-modal option is enabled. userConfig must be true.

Listens to

eventactionemitson error
change-queryupdates internal representation of current query--
export-datatriggers data export--
export-data/user-configaccording to config, triggers an exportsuccesserror
count-datanotifies on how many items would be exported on filtered export option--
select-data-bulkkeeps track of items selections to prompt selected export option configuration--

Emits

eventdescription
successnotifies successful export if nativeDownload property is false
errorcontains error messages when something goes wrong