api.v2.export
Interface Description

Overview

Mindbreeze InSpire enables the export of search results with a simple interface. This interface is based on HTTP and JSON.

Synchronous Export

Synchronous Export is only available for the Excel and CSV formats.

The Export can be downloaded with a HTTP/POST request directly with the URL <Client Service URL>/api/v2/export.

The  HTTP/POST request contains the search request and some options.

{
    "search_request": {
        "sort_date_facets_by_value": true,
        "content_sample_length": 300,
        "count": 10,
        "alternatives_query_spelling_max_estimated_count": 50,
        "properties": [{
                "formats": ["HTML", "VALUE"],
                "name": "title"
            }, {
                "formats": ["HTML", "VALUE"],
                "name": "mes:date"
            }, {
                "formats": ["HTML", "VALUE"],
                "name": "mes:size"
            }, {
                "formats": ["HTML", "VALUE"],
                "name": "action_0"
            }
        ],
        "user": {
            "query": {
                "and": [{
                        "unparsed": "ALL",
                        "id": "query"
                    }
                ]
            },
            "constraints": []
        },
        "source_context": {
            "constraints": [{
                    "unparsed": "ALL",
                    "id": "view_base"
                }
            ]
        },
        "generate_available_properties_and_facets": true
    },
    "id": "ALL_10:11",
    "name": "my testexport",
    "groupby_properties": [],
    "batch_size": 1000,
    "allow_duplicate": false,
    "currentTime": "10:11",
    "add_description_of_search_request": true,
    "export_format": "application/x-ms-excel"
}

The property export_format specifies the format of the exported query results.

The following export formats are supported:

• application/x-ms-excel Microsoft Excel XSLX file
• text/csv  CSV file

Asynchronous Export

The export takes place in two steps. First, an export request must be saved using persisted resources. This returns a path (ID) for the export, which can then be run and retrieved by accessing the export interface.

Saving the export request

The export request is sent as HTTP POST to a client service. The path for storing the export request is: <Client Service URL>/api/v2/persistedresources

The request takes the following form:

{
    "create": {
        "path": ["queryexports", "default"],
        "data": "<exportrequest>"
    }
}

The <exportrequest> is stored as a string in the data property and takes the following form:

{
    "search_request": {
        "sort_date_facets_by_value": true,
        "content_sample_length": 300,
        "count": 10,
        "alternatives_query_spelling_max_estimated_count": 50,
        "properties": [{
                "formats": ["HTML", "VALUE"],
                "name": "title"
            }, {
                "formats": ["HTML", "VALUE"],
                "name": "mes:date"
            }, {
                "formats": ["HTML", "VALUE"],
                "name": "mes:size"
            }, {
                "formats": ["HTML", "VALUE"],
                "name": "action_0"
            }
        ],
        "user": {
            "query": {
                "and": [{
                        "unparsed": "ALL",
                        "id": "query"
                    }
                ]
            },
            "constraints": []
        },
        "source_context": {
            "constraints": [{
                    "unparsed": "ALL",
                    "id": "view_base"
                }
            ]
        },
        "generate_available_properties_and_facets": true
    },
    "export_format": "undefined",
    "id": "ALL_10:11",
    "name": "my testexport",
    "groupby_properties": [],
    "batch_size": 1000,
    "allow_duplicate": false,
    "currentTime": "10:11",
    "add_description_of_search_request": true
}

In response, the status of the request is returned along with the path to run the export.

{
    "persisted_resources": [{
            "path": ["queryexports", "default", "4"],
            "data": "<exportrequest>"
        }
    ],
    "persisted_resource_request": {
        "create": {
            "path": ["queryexports", "default"],
            "data": "<exportrequest>"
        },
        "user_context": {}
    },
    "status": {
        "success": true
    }
}

In this example, the response returns the path queryexports/default/4.

Starting a saved export

The export request is sent as HTTP GET to a client service. The URL for starting the export request is:

<Client Service URL>/api/v2/exportAsync?resource_path=<path of the saved export>

In this example the URL is: <Client Service URL>/api/v2/exportAsync?resource_path= queryexports/default/4

The Export is started with this request. When it is ready to download the status changes from PROGRESS to SUCCESS.

Checking the status of the export

Every export and its status is saved. You can query the saved information about an export using the following request.

Url: <Client Service URL>/api/v2/persistedresources

The request takes the following form:

{
    "read": {
        "path": ["queryexports", "default", "4"]
    }
}

The path option identifies the export whose status is to be retrieved. The response returns status, status_description, and the downloaded_timestamp. Because this information is stored in persisted resources, it can be retrieved at any time.

{
    "persisted_resources": [{
            "path": [
                "queryexports",
                "default",
                "16"
            ],
            "data":  < exportrequest > ,
            "property": [{
                    "key": "status_description",
                    "value": ""
                }, {
                    "key": "downloaded_timestamp",
                    "value": "2017-05-18T09:24:47+02:00"
                }, {
                    "key": "status",
                    "value": "SUCCESS"
                }
            ],
            "created": "2017-05-18T09:24:43+02:00",
            "lastmod": "2017-05-18T09:24:47+02:00",
            "owner": "administrator@testlab.mindbreeze.fabagl.fabasoft.com",
            "operations": {
                "operations": [
                    "READ",
                    "UPDATE",
                    "REMOVE",
                    "CREATE"
                ]
            }
        }
    ],
    "persisted_resource_request": {
        "read": {
            "path": [
                "queryexports",
                "default",
                "16"
            ]
        },
        "user_context": {}
    },
    "status": {
        "success": true
    }
}

Downloading the Result

When the status changed from PROGRESS to SUCCESS the export can be downloaded with the URL:

<Client Service URL>/api/v2/export?resource_path=<path of the saved export>

In this example the URL is: <Client Service URL>/api/v2/export?resource_path=queryexports/default/4

Export options

Using the export options in the export request, you can configure the result.

Determining the properties to be exported per result

In the search query, all properties that appear as "columns" in the result must be specified as follows:

"properties": [{
        "formats": ["HTML", "VALUE"],
        "name": "title"
    }, {
        "formats": ["HTML", "VALUE"],
        "name": "mes:date"
    }, {
        "formats": ["HTML", "VALUE"],
        "name": "mes:size"
    }
]

In this example, the title, date, and size are exported.

Determining the export format

The format in which the result of the search request/query should be delivered can be determined using the option export_format. If no export_format or an unavailable export_format is set, the default export format from the export options of the client service configuration is used.

The following values and formats are available:

application/x-ms-excel => A Microsoft Excel xlsx document is created.

application/json => The results are exported as a JSON document.

application/zip => The data is exported as a ZIP file.

text/csv => The data is exported as CSV.

Configuring the batch size

The size of the requests can be configured to increase the performance. By default, 250 results are retrieved and processed by the query service until the next 250 results are retrieved. This batch size is selected to minimize the amount of memory required in the client service. The batch size can be increased to achieve better performance, but this requires more memory in the client service. The batch_size option allows the batch size to be increased up to the limit in the client service configuration.

Preventing duplicates in the result

Using the option allow_duplicate, you can prevent duplicates in the results. Duplicates can be removed in the results document with allow_duplicate: false

Grouping values

As with SQL, the results can be grouped according to individual properties. The groupby_properties option contains the properties used for grouping.

For example, to group by date and title, the groupby_properties option can be configured as follows:

groupby_properties : [“mes:date“, “title“]

It is important that the properties used for grouping are also requested in the search request.

Cancelling an export

An export can be cancelled by sending the original export request with the option "cancel_pending": true.

The export request is carried out via HTTP POST to the URL <Client Service URL>/api/v2/export.