Server data exporting

Entity view data can be exported to a file by the server, either through the export API endpoints or directly from the client side of a cluster.

Execute an export

To execute an export, you need to do a request to the following API endpoint: POST /exports/execute

In the request body, you must pass a JSON object with several properties:

EntityViewName (string, required): Name of the entity view to obtain the data to be exported.
FileName (string, required): Name of file to generate
Format (string, required): Format of file to export. Only Csv is supported.
Properties (string[], optional): Array of property names to export. If this is not set, all the entity view properties will be exported.
Filter (string, optional): Filter (ODATA format) to apply to the query to obtain the data.
OrderBy (string, optional): Sort (ODATA format) to apply to the query to obtain the data.
EntityViewParameters (Dictionary<string, object>, optional): Parameters to send to the entity view to obtain the data.
Culture (string, optional): Culture to format the values. If this is not set, it will use the value of the Accept-Language request header.
CsvOptions (object, optional): CSV-specific options (only used when the format is Csv):
- Delimiter (string, optional): Delimiter used to separate the fields. If this is not set, the delimiter of the export culture is used.

Request body example

{
  "entityViewName": "PartyListView",
  "fileName": "Parties.csv",
  "format": "Csv",
  "properties": ["LastName", "FirstName"],
  "filter": "PartyType eq 'Supplier'",
  "orderBy": "LastName ASC",
  "entityViewParameters": {
    "OnlyActive": true
  },
  "culture": "en",
  "csvOptions": {
    "delimiter": "|"
  }
}

The API call will execute asynchronous export processing and return a 202 response with the export identifier in the response:

{
  "identifier": "6db53638-4c32-4222-af53-4b8cd9ecdf6d"
}

Obtain the export status

To obtain the status of an export, you need to do a request to the following API endpoint: GET /exports/status/{identifier}

The various possible responses are as follows:

Pending

{
  "state": "Pending"
}

Running

{
  "state": "Running"
}

Succeeded

{
  "state": "Succeeded"
}

Failed

{
  "state": "Failed",
  "errorMessage": "Error message",
  "errorDetails": "Error details"
}

Download the export file

To download the export file, you need to do a request to the GET /exports/download/{identifier} API endpoint.

Execute an export from the client

On the client side of the cluster, you can execute a server side data export using the following method: Task ExportServerDataAsync(ServerDataExportOptions options)

This method is accessible in code of UI view, UI component and menu item.

The options correspond to the JSON object to be passed to the API request to execute the export:

ServerDataExportOptions options = new ServerDataExportOptions("PartyListView", "Parties.csv", ExportFormat.Csv)
    .WithProperties(new[] { "LastName", "FirstName" })
    .WithFilter("PartyType eq 'Supplier'")
    .WithOrderBy("LastName ASC")
    .WithEntityViewParameters(new Dictionary<string, object>()
    {
        ["OnlyActive"] = true
    })
    .WithCulture("en")
    .WithCsvOptions(new CsvOptions().WithDelimiter("|"));

await ExportServerDataAsync(options);

When the export is complete, a notification toast will be displayed to download the export file.

Create the options from the current state of the UI view

In the UI view code, options can be created from the current state of the UI view using the following method: ServerDataExportOptions CreateServerDataExportOptions(string fileName, ExportFormat format)

The options will be initialized with:

The exported properties are those coming from the entity view, visible in the data grid and sorted according to data grid position.
The current filter.
The current sort.
The current entity view parameters.

Rather than creating the action yourself, you may use the default export button provided by the toolbar: simply add the export attribute.

The default export is performed according to the client user settings provided by the operating system and/or the browser, in particular:

in their language and culture
for their time-zone.

The "General" tab of the NeosDataExportUI provided by the NeosDataExchange module reflects this behavior and is pre-filled accordingly.

Localizing dates and times

Date and time values are converted to the time-zone of the client before being written to the export file.

To export them in another time-zone, use the ServerDataExportOptions WithTimeZone(string timeZone) method, which accepts a Windows or an IANA time zone identifier:

ServerDataExportOptions options = CreateServerDataExportOptions("Employees.csv", ExportFormat.Csv)
    .WithTimeZone("Europe/Paris");

await ExportServerDataAsync(options);

To export them in UTC, set the time-zone to null:

ServerDataExportOptions options = CreateServerDataExportOptions("Employees.csv", ExportFormat.Csv)
    .WithTimeZone(null);

await ExportServerDataAsync(options);

Specify the CSV delimiter

By default, the delimiter used in a CSV export is the one of the culture used for the export.

To use another delimiter, pass CSV-specific options to the export options using the ServerDataExportOptions WithCsvOptions(CsvOptions csvOptions) method, and set the delimiter using the CsvOptions WithDelimiter(string delimiter) method:

ServerDataExportOptions options = CreateServerDataExportOptions("Employees.csv", ExportFormat.Csv)
    .WithCsvOptions(new CsvOptions().WithDelimiter("|"));

await ExportServerDataAsync(options);

Setting the delimiter to null (or not calling WithCsvOptions) restores the culture default delimiter.

Table of Contents