api.v2.export
Interface Description
Copyright ©
Mindbreeze GmbH, A-4020 Linz, July 2020.
All rights reserved. All hardware and software names are brand names and/or trademarks of their respective manufacturers.
These documents are strictly confidential. The submission and presentation of these documents does not confer any rights to our software, our services and service outcomes or other protected rights.
The dissemination, publication or reproduction hereof is prohibited.
For ease of readability, gender differentiation has been waived. Corresponding terms and definitions apply within the meaning and intent of the equal treatment principle for both sexes.
.
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.