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.

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",
  }
}

warning

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

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

Listens to

event	action	emits	on error
change-query	updates internal representation of current query	-	-
export-data	triggers data export	-	-

Emits

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