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 persistance 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

property	attribute	type	default	description
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
nativeDownload	native-download	boolean	-	when true it skips frontend blob parsing and uses browser native download API
shouldIncludeProjections	should-include-projections	boolean	false	should append projection when exporting from CRUD service
streamSaverIFrameSrc	stream-saver-iframe-src	string	-	location where stream saver service worker files are served
userConfig	user-config	boolean	false	whether to listen to awaiting-for-export-configuration or not. It must be true to use it with bk-export-modal.
primaryKey	primary-key	string	_id	primary key to filter selected data when selected only export in bk-export-modal option is enabled. userConfig must be true.

Listens to

event	action	emits	on error
change-query	updates internal representation of current query	-	-
export-data	triggers data export	-	-
export-data/user-config	according to config, triggers an export	success	error
count-data	notifies on how many items would be exported on filtered export option	-	-
select-data-bulk	keeps track of items selections to prompt selected export option configuration	-	-

Emits

event	description
success	notifies successful export if nativeDownload property is false
error	contains error messages when something goes wrong