Sure, you can handle it. But should you?
Let our experts manage the tech maintenance while you focus on your business.
Let our experts manage the tech maintenance while you focus on your business.
Documentation
Export and Integration of Personalization and Analytics Data with External Platforms
Introduction
Mindbreeze InSpire tracks search events and user interactions, storing this data within app.telemetry. This information is accessible via the Management Center under Reporting Telemetry Details Client Service Query Log.
To facilitate integration with external business intelligence (BI) platforms and analysis tools, Mindbreeze InSpire provides a dedicated Query Log API. This API offers a uniform view of telemetry data, providing detailed insights into the following user-triggered events:
- Search queries: The terms and filters used by users.
- Pagination: Navigation through result sets.
- Search results: Data regarding the results returned.
- Search answers: Data regarding the answers (semantic search) returned.
- Result actions: Interactions with specific search results.
- Application events: Other general interactions within the application.
- AI conversations and answers: User feedback for generated answers
In addition to its built-in app.telemetry capabilities, the Insight Application supports integration with third-party web analytics platforms, including Google Analytics, through the QueryProfiler implementation. This enables organizations to export search event data for advanced analysis, custom reporting, and integration with existing analytics and BI solutions.
Configuration
For the Query Log API to be available, the Personalized Relevance Transformer needs to be configured. The following minimal configuration needs to be done:
- Open the tab "Indices" in the menu "Configuration" of the Mindbreeze Management Center. Add a new service in the "Services" section by clicking on the "+ Add Service" button. Select the plugin "PersonalizedRelevanceTransformer" from the list "Service".
- For the analytics data to be recorded, personalization must be activated in the Client Service. This logs all user searches and actions in the app.telemetry. This option is active by default. Check this by opening the tab "Client Services" in the menu "Configuration" in the Mindbreeze Management Center, activate the "Advanced Settings" and see under "Personalization Settings" that the option "Enable Personalization" is active.
API Access from localhost
With the configuration above, the API can be reached from localhost without any authentication (inside the inspire Docker container):
http://localhost:23916/api/mindbreeze.plugins.querylog.v1.QueryLogService/ListEvents
API Access from Remote
The API can be accessed from remote via
https://<appliance-hostname>:8443/realm/master/api/service/<service-id>/api/ mindbreeze.plugins.querylog.v1.QueryLogService/ListEvents.
To access the API, you need a valid OAuth 2.0 token. You can fetch it by performing a HTTP POST request to with a body of type “x-www-form-urlencoded”:
- grant_type: password
- client_id: mindbreeze-inspire-public
- username: <username>
- password: <password>
The user must have the role “InSpire Administrator”. If you want to use a different role, you need to configure this in the reverse proxy (see chapter “Reverse Proxy Configuration”, Require claim "roles:<my-role>"). More information generally about users and roles can be found in the documentation Configuration of Back-End Credentials.
Copy the “access_token” from the response JSON. Now you can access the API by sending the “access_token” in the HTTP header “Authorization”: “Bearer <access_token>”, e.g. when requesting https://inspire.mycompany.com:8443/realm/master/api/service/bcaba17d-6873-44ee-a130-cab4417c2be3/api/mindbreeze.plugins.querylog.v1.QueryLogService/ListEvents
QueryLogService API ListEvents
The Query Log events are available at:
GET /api/mindbreeze.plugins.querylog.v1.QueryLogService/ListEvents
This returns multiple events (queries, paging, result actions), ordered by startTime ascending.
Request Headers
Please always set the header X-Requested-With with value XMLHttpRequest in the request in order to get the correct HTTP status codes. Otherwise you will always get the generic error “An unknown error occured. Go back to the Management Center.”
URL Parameters
Parameter | Description |
application | Filters events by application. If defined, only matching applications are returned. The application is the Name of the Application configured in “Application Definitions” in the PersonalizedRelevanceTransformer |
pageSize | Limits the number of events in the response (default: 1000) |
lastEventId | Filters events newer that lastEventId. This should be used to fetch the next page(s). Use the "id" of the last retrieved event as value to fetch the next page |
startTime | Filters events newer than the provided RFC 3339 timestamp |
endTime | Filters events older than the provided RFC 3339 timestamp |
includeSearchResults | Also search result events of type "QUERY_RESULT" and "PAGING_RESULT" are included in the response |
includeSessions | Also session events of type "SESSION_CREATE" and "SESSION_DESTROY" are included in the response |
includeDebugDetails | Additional debug information is included in the response |
dumpAfterMsIfNotFinished |
|
Response
{
"events": array (Event[])
}
(Response) Data Models
Event
Property | Description |
id: string | unique identifier for an event |
type: string (Type) | type of the event (see Type section) |
sessionId: string | identifier for the user session, which expires by default after 30 minutes when the user is inactive |
queryEventId: string | unique identifier which references the query (only for events of type "PAGING" and "RESULT_ACTION") |
application: string | the application to which the event belongs (configured via Application Definitions) |
searchUser: string | the user who has searched |
referer: string | URL from which the search was done |
clientServiceId: string | the service ID of the used client service |
startTime: string | the time at which the event occurred (as RFC 3339 timestamp with UTC time zone) |
duration: string | the duration of the event, in seconds (e.g. "1.021340s") |
applicationId: string | the application’s ID |
queryContextOptions: object | JSON object containing all properties sent in the api.v2 requests via query_context.properties |
queryDetails: object (QueryEventDetails) | details of the query (see QueryEventDetails section); only for events of "type": "QUERY" and "PAGING" |
resultActionDetails: object (ResultActionEventDetails) | Details of the result action (see ResultActionEventDetails section); only for events of "type": "RESULT_ACTION" |
globalActionDetails: object (GlobalActionEventDetails) | Details of the global action (see GlobalActionEventDetails section); only for events of "type": "GLOBAL_ACTION" |
resultDetails: object | Details of the search result (see ResultEventDetails section); only for events of "type": "QUERY_RESULT" or "PAGING_RESULT" |
Type (enum)
"QUERY", "PAGING", "RESULT_ACTION", "GLOBAL_ACTION", "QUERY_RESULT", "PAGING_RESULT"
QueryEventDetails
Property | Description |
previousQueryEventId: string | unique identifier which references the previous query, if there was any (only for events of type "QUERY") |
results: string | number of actual results returned by this query (only for events of type "QUERY") |
totalCount: string | number of total results for this query (only for events of type "QUERY") |
noResults: boolean | "true" if no results have been returned (only for events of type "QUERY") |
terminationCause: string | meta information for "results", e.g. "COUNT_LIMIT" or "NO_MORE_RESULTS" (only for events of type "QUERY") |
query: string | the query string |
isConstrained: boolean | "true" if the query contains constraints |
orderBy: string | the order criteria |
orderDirection: string | the order direction, "ASCENDING" or "DESCENDING" |
requestName: string | the request name; usually "default" when using the default search client (only for events of type "QUERY") |
isPaging: boolean | true for events of type "PAGING" |
tabId: string | the id of the search tab |
usedFilters: object[] (Filter) | the selected filters during search |
availableFilters: object[] (Filter) | the available filters during search |
queryTriggerType: string | the action type which triggered the query (available values: "USER_QUERY", "REFINEMENT", "AUTOMATIC" |
queryTriggerAction: string | the concrete action which triggered the query |
Filter
id: string | the filter id |
name: string | the translated name of the filter |
filteredValues: string[] | the filtered values |
ResultActionEventDetails
Property | Description |
resultId: string | unique identifier which references the result on which the action was applied |
resultPosition: string | position of the result on which the action was applied (0 is the first result) |
previewDuration: string | how long the preview was opened in seconds, e.g. "7.907s" (only for events with action "PREVIEWCLOSED") |
previewScrollPositionPercentage: number | if not scrolled, this property is not provided, otherwise the value is between 1 and 100 (only for events with action "PREVIEWCLOSED") |
fqCategory: string | "<category>:<categoryInstance>" of the result on which the action was applied |
key: string | mes:key of the result on which the action was applied |
page: number | page of the result on which the action was applied (0 is the first page) |
action: string | the action (usually "PREVIEW", "PREVIEWCLOSED", "OPENHREF" or "VOTE") |
votingWeight: number | -100 or 100 for down- or upvoating (only for events with action "VOTE") |
votingComment: string | comment of a vote (only for events with action "VOTE") |
url: string | URL of the action. Only available for OPENHREF actions |
customProperty1: string | configured custom personalization properties from the Client Service configuration |
options: object | JSON object containing all properties sent in the api.v2.personalization requests via options_json |
ResultEventDetails
page: number | page of the result (0 is the first page) |
resultPosition: string | position of the result (0 is the first result) |
fqCategory: string | "<category>:<categoryInstance>" of the result |
key: string | mes:key of the result |
url: string | url metadatum of the result |
customProperty1: string | configured custom personalization properties from the Client Service configuration |
GlobalActionEventDetails
Property | Description |
action: string | the action (currently always "OPENHREF") |
url: string | URL of the action. Only available for OPENHREF actions |
Examples
Request first page
Request:
/api/mindbreeze.plugins.querylog.v1.QueryLogService/ListEvents
Response:
"events": [{
"id": "CgwI5uHn9gUQ+KPPhAEQtavSmqgu",
"type": "QUERY",
"application": "search.mindbreeze.com",
"referer": "https://search.mindbreeze.com/apps/support/",
"startTime": "2020-06-05T07:14:46.278123Z",
"duration": "0.101114s",
"queryDetails": {
"previousQueryEventId": "CgwI4eHn9gUQwLTd6gEQtavSmqgu",
"results": "5",
"totalCount": "1380",
"terminationCause": "COUNT_LIMIT",
"query": "mindbreeze",
"orderBy": "mes:relevance",
"requestName": "default",
"tabId": "Everything"
}
}, {
"id": "CgwI9uHn9gUQyIOamwEQtavSmqgu",
"type": "RESULT_ACTION",
"queryEventId": "CgwI5uHn9gUQ+KPPhAEQtavSmqgu",
"application": "search.mindbreeze.com",
"referer": "https://search.mindbreeze.com/apps/support/",
"startTime": "2020-06-05T07:15:02.325485Z",
"duration": "0.000484s",
"resultActionDetails": {
"previewDuration": "12.269s",
"previewScrollPositionPercentage": 100,
"fqCategory": "Web:trainingvideos",
"key": "https://www.youtube.com/watch?v=yzTyTz1SpXo",
"action": "PREVIEWCLOSED"
}
}
}
Depending on the type of the event, either “queryDetails” or “resultActionDetails” field is available.
Request Next Page
To request the next page, use the last ID from the previous response for the next request’s “lastEventId” URL parameter:
GET /api/mindbreeze.plugins.querylog.v1.QueryLogService/ListEvents?lastEventId= CgwI9uHn9gUQyIOamwEQtavSmqgu
Hint: Don’t forget to decode UTF characters from the JSON response (see RFC 4627, section “2.5 Strings”) and URL encode your parameters.