Home
Home
German Version
Support
Impressum
25.2 Release ►

Start Chat with Collection

    Main Navigation

    • Preparation
      • Connectors
      • Create an InSpire VM on Hyper-V
      • Initial Startup for G7 appliances
      • Setup InSpire G7 primary and Standby Appliances
    • Datasources
      • Configuration - Atlassian Confluence Connector
      • Configuration - Best Bets Connector
      • Configuration - Box Connector
      • Configuration - COYO Connector
      • Configuration - Data Integration Connector
      • Configuration - Documentum Connector
      • Configuration - Dropbox Connector
      • Configuration - Egnyte Connector
      • Configuration - GitHub Connector
      • Configuration - Google Drive Connector
      • Configuration - GSA Adapter Service
      • Configuration - HL7 Connector
      • Configuration - IBM Connections Connector
      • Configuration - IBM Lotus Connector
      • Configuration - Jira Connector
      • Configuration - JVM Launcher Service
      • Configuration - LDAP Connector
      • Configuration - Microsoft Azure Principal Resolution Service
      • Configuration - Microsoft Dynamics CRM Connector
      • Configuration - Microsoft Exchange Connector
      • Configuration - Microsoft File Connector (Legacy)
      • Configuration - Microsoft File Connector
      • Configuration - Microsoft Graph Connector
      • Configuration - Microsoft Loop Connector
      • Configuration - Microsoft Project Connector
      • Configuration - Microsoft SharePoint Connector
      • Configuration - Microsoft SharePoint Online Connector
      • Configuration - Microsoft Stream Connector
      • Configuration - Microsoft Teams Connector
      • Configuration - Salesforce Connector
      • Configuration - SCIM Principal Resolution Service
      • Configuration - SemanticWeb Connector
      • Configuration - ServiceNow Connector
      • Configuration - Web Connector
      • Configuration - Yammer Connector
      • Data Integration Guide with SQL Database by Example
      • Indexing user-specific properties (Documentum)
      • Installation & Configuration - Atlassian Confluence Sitemap Generator Add-On
      • Installation & Configuration - Caching Principal Resolution Service
      • Installation & Configuration - Mindbreeze InSpire Insight Apps in Microsoft SharePoint On-Prem
      • Mindbreeze InSpire Insight Apps in Microsoft SharePoint Online
      • Mindbreeze Web Parts for Microsoft SharePoint
      • User Defined Properties (SharePoint 2013 Connector)
      • Whitepaper - Mindbreeze InSpire Insight Apps in Salesforce
      • Whitepaper - Web Connector - Setting Up Advanced Javascript Usecases
    • Configuration
      • CAS_Authentication
      • Configuration - Alerts
      • Configuration - Alternative Search Suggestions and Automatic Search Expansion
      • Configuration - Back-End Credentials
      • Configuration - Chinese Tokenization Plugin (Jieba)
      • Configuration - CJK Tokenizer Plugin
      • Configuration - Collected Results
      • Configuration - CSV Metadata Mapping Item Transformation Service
      • Configuration - Entity Recognition
      • Configuration - Exporting Results
      • Configuration - External Query Service
      • Configuration - Filter Plugins
      • Configuration - GSA Late Binding Authentication
      • Configuration - Identity Conversion Service - Replacement Conversion
      • Configuration - InceptionImageFilter
      • Configuration - Index-Servlets
      • Configuration - InSpire AI Chat and Insight Services for Retrieval Augmented Generation
      • Configuration - Item Property Generator
      • Configuration - Japanese Language Tokenizer
      • Configuration - Kerberos Authentication
      • Configuration - Management Center Menu
      • Configuration - Metadata Enrichment
      • Configuration - Metadata Reference Builder Plugin
      • Configuration - Mindbreeze Proxy Environment (Remote Connector)
      • Configuration - Personalized Relevance
      • Configuration - Plugin Installation
      • Configuration - Principal Validation Plugin
      • Configuration - Profile
      • Configuration - Reporting Query Logs
      • Configuration - Reporting Query Performance Tests
      • Configuration - Request Header Session Authentication
      • Configuration - Shared Configuration (Windows)
      • Configuration - Vocabularies for Synonyms and Suggest
      • Configuration of Thumbnail Images
      • Cookie-Authentication
      • Documentation - Mindbreeze InSpire
      • I18n Item Transformation
      • Installation & Configuration - Outlook Add-In
      • Installation - GSA Base Configuration Package
      • JWT Authentication
      • Language detection - LanguageDetector Plugin
      • Mindbreeze Personalization
      • Mindbreeze Property Expression Language
      • Mindbreeze Query Expression Transformation
      • SAML-based Authentication
      • Trusted Peer Authentication for Mindbreeze InSpire
      • Using the InSpire Snapshot for Development in a CI_CD Scenario
      • Whitepaper - AI Chat
      • Whitepaper - Create a Google Compute Cloud Virtual Machine InSpire Appliance
      • Whitepaper - Create a Microsoft Azure Virtual Machine InSpire Appliance
      • Whitepaper - Create AWS 10M InSpire Appliance
      • Whitepaper - Create AWS 1M InSpire Appliance
      • Whitepaper - Create AWS 2M InSpire Appliance
      • Whitepaper - Create Oracle Cloud 10M InSpire Application
      • Whitepaper - Create Oracle Cloud 1M InSpire Application
      • Whitepaper - MMC_ Services
      • Whitepaper - Natural Language Question Answering (NLQA)
      • Whitepaper - SSO with Microsoft AAD or AD FS
      • Whitepaper - Text Classification Insight Services
    • Operations
      • Adjusting the InSpire Host OpenSSH Settings - Set LoginGraceTime to 0 (Mitigation for CVE-2024-6387)
      • app.telemetry Statistics Regarding Search Queries
      • CIS Level 2 Hardening - Setting SELinux to Enforcing mode
      • Configuration - app.telemetry dashboards for usage analysis
      • Configuration - Usage Analysis
      • Deletion of Hard Disks
      • Handbook - Backup & Restore
      • Handbook - Command Line Tools
      • Handbook - Distributed Operation (G7)
      • Handbook - Filemanager
      • Handbook - Indexing and Search Logs
      • Handbook - Updates and Downgrades
      • Index Operating Concepts
      • Inspire Diagnostics and Resource Monitoring
      • Provision of app.telemetry Information on G7 Appliances via SNMPv3
      • Restoring to As-Delivered Condition
      • Whitepaper - Administration of Insight Services for Retrieval Augmented Generation
    • User Manual
      • Browser Extension
      • Cheat Sheet
      • iOS App
      • Keyboard Operation
    • SDK
      • api.chat.v1beta.generate Interface Description
      • api.v2.alertstrigger Interface Description
      • api.v2.export Interface Description
      • api.v2.personalization Interface Description
      • api.v2.search Interface Description
      • api.v2.suggest Interface Description
      • api.v3.admin.SnapshotService Interface Description
      • Debugging (Eclipse)
      • Developing an API V2 search request response transformer
      • Developing Item Transformation and Post Filter Plugins with the Mindbreeze SDK
      • Development of a Query Expression Transformer
      • Development of Insight Apps
      • Embedding the Insight App Designer
      • Java API Interface Description
      • OpenAPI Interface Description
    • Release Notes
      • Release Notes 20.1 Release - Mindbreeze InSpire
      • Release Notes 20.2 Release - Mindbreeze InSpire
      • Release Notes 20.3 Release - Mindbreeze InSpire
      • Release Notes 20.4 Release - Mindbreeze InSpire
      • Release Notes 20.5 Release - Mindbreeze InSpire
      • Release Notes 21.1 Release - Mindbreeze InSpire
      • Release Notes 21.2 Release - Mindbreeze InSpire
      • Release Notes 21.3 Release - Mindbreeze InSpire
      • Release Notes 22.1 Release - Mindbreeze InSpire
      • Release Notes 22.2 Release - Mindbreeze InSpire
      • Release Notes 22.3 Release - Mindbreeze InSpire
      • Release Notes 23.1 Release - Mindbreeze InSpire
      • Release Notes 23.2 Release - Mindbreeze InSpire
      • Release Notes 23.3 Release - Mindbreeze InSpire
      • Release Notes 23.4 Release - Mindbreeze InSpire
      • Release Notes 23.5 Release - Mindbreeze InSpire
      • Release Notes 23.6 Release - Mindbreeze InSpire
      • Release Notes 23.7 Release - Mindbreeze InSpire
      • Release Notes 24.1 Release - Mindbreeze InSpire
      • Release Notes 24.2 Release - Mindbreeze InSpire
      • Release Notes 24.3 Release - Mindbreeze InSpire
      • Release Notes 24.4 Release - Mindbreeze InSpire
      • Release Notes 24.5 Release - Mindbreeze InSpire
      • Release Notes 24.6 Release - Mindbreeze InSpire
      • Release Notes 24.7 Release - Mindbreeze InSpire
      • Release Notes 24.8 Release - Mindbreeze InSpire
      • Release Notes 25.1 Release - Mindbreeze InSpire
      • Release Notes 25.2 Release - Mindbreeze InSpire
    • Security
      • Known Vulnerablities
    • Product Information
      • Product Information - Mindbreeze InSpire - Standby
      • Product Information - Mindbreeze InSpire
    Home

    Path

    Sure, you can handle it. But should you?
    Let our experts manage the tech maintenance while you focus on your business.
    See Consulting Packages

    Interface Description
    api.v2.personalization

    IntroductionPermanent link for this heading

    This document deals with the Mindbreeze Web API for analyzing user behavior. The API is responsible for recording user actions in the app.telemetry.

    Please note that this API is designed to analyze user actions in the search results, such as opening or previewing documents. Information on how to perform searches with the Mindbreeze Web API can be found in the api.v2.search Interface Description.

    Personalization requests are sent as HTTP POST requests to a client service. The path for personalization requests is: <Client Service URL>/api/v2/personalization.

    A JSON document that describes the personalization requests is sent with the body of the HTTP request.

    You can find more information on personalization in the following documentation:

    Usage Analysis

    Reading the data logged with api.v2.personalization in app.telemetry

    Personalization

    Setting up personalization in the default Mindbreeze InSpire search client

    Fields in Personalization RequestsPermanent link for this heading

    query_resultPermanent link for this heading

    This JSON object describes the user actions related to the search result. Which members can be set for this JSON object is described in the following subsections.

    query_result.actionPermanent link for this heading

    The operation performed by the user. Displayed in capital letters in the app.telemetry in the “Operation” column.

    query_result.action_trigger_eventPermanent link for this heading

    Is used to pass the event that triggered the action. Example: „MOUSE_LEFT_CLICK “.
    Type: String

    query_result.options_jsonPermanent link for this heading

    Can be used to display additional information of an action in the app.telemetry.
    Type: Object as a string.

    query_result.titlePermanent link for this heading

    The title of the document (title Property).
    Type: String

    query_result.urlPermanent link for this heading

    The URL of the document (url Property).
    Type: String

    query_result.commentPermanent link for this heading

    Can be used to log user comments on a document. Is displayed in the app.telemetry in the column “Comment”.

    query_answer.weightPermanent link for this heading

    Can be used to communicate positive or negative user feedback (upvote or downvote). (Floating point number) Usually the values are between -1.0 (= downvote) and 1.0 (= upvote). This is displayed in the app.telemetry in the "Weight" column.

    query_result.duration_in_msPermanent link for this heading

    The duration of the user action in milliseconds (for example, if the user had a preview of the document open for a certain time and then closed it). Displayed in the app.telemetry in the column “Duration (ms)”.

    query_result.fqcategoryPermanent link for this heading

    The fqcategory (Full Qualified Category) of the document that was involved in the user action. Appears in the app.telemetry in the “FQCategory” column.

    query_result.keyPermanent link for this heading

    The key (datasource/mes:key) of the document involved in the user action. Is displayed in the app.telemetry in the column “Key”.

    query_result.positionPermanent link for this heading

    The result position of the document that was involved in the user action. Note that the first document has the position 0, so for example the tenth document has the position 9. Is displayed in the app.telemetry in the column “Result Position”.

    query_result.query_contextPermanent link for this heading

    This JSON object describes the context of the search query. The following subsections describe the members of this JSON object.

    Note: You can also send the query context with the search query.

    query_result.query_context.application_idPermanent link for this heading

    To uniquely identify an Insight App.
    Default value: "Default Application"
    Type: String

    query_result.query_context.query_trigger_actionPermanent link for this heading

    Indicates how the search was triggered.
    Example: "submit"
    Type: String

    query_result.query_context.query_idPermanent link for this heading

    The ID of the search query (as an unsigned number). It is recommended to set a UTC timestamp (milliseconds since January 1, 1970, 00:00:00.000 GMT) of the current time of the search query (e.g. in JavaScript using new Date().getTime()). Is displayed in the app.telemetry in the column “Query ID”.

    query_result.query_context.prev_query_idPermanent link for this heading

    This is the query_id that was set in the previous query. Displayed in the app.telemetry in the column ”Previous Query ID”.

    query_result.query_context. refinement_idPermanent link for this heading

    The ID of the search query in which filters (= facets) were changed (as unsigned numbers). It is recommended to set a UTC timestamp (milliseconds since January 1, 1970, 00:00:00.000 GMT) of the current time of the search query (e.g. in JavaScript using new Date().getTime()). Displayed in the app.telemetry in the column "Refinement ID".

    query_result.query_context. prev_refinement_idPermanent link for this heading

    This is the refinement_id that was set in the previous query. Displayed in the app.telemetry in the column "Previous Refinement ID".

    query_result.query_context.propertiesPermanent link for this heading

    An array of JSON objects with key-value pairs to log custom properties in app.telemetry. Displayed in app.telemetry in the columns "Custom Property 1" to "Custom Property 10". Thus, a maximum of 10 custom properties can be added.

    The following example shows how to set the resultcount and language properties in the "Custom Property 1" and "Custom Property 2" columns in app.telemetry:

    "properties": [

        {

            "key": "resultcount",

            "value": "534"

        },

        {

            "key": "language",

            "value": "de-AT"

        }

    ]

    scroll_position_in_percentagePermanent link for this heading

    The scroll position in the browser. Can be used, for example, during the close action of a preview window to log how far a user has scrolled down in the preview window. Values between 0 and 100 are valid. Displayed in the app.telemetry in the “Scroll position (%)” column.

    query_answerPermanent link for this heading

    This JSON object describes the user actions associated with a response. The members that can be set for this JSON object are described in the following subsections.

    query_answer.actionPermanent link for this heading

    The operation that the user has performed. Displayed in capital letters in the app.telemetry in the "Operation" column..

    query_answer.action_trigger_eventPermanent link for this heading

    Used to pass the event that triggered the action. Example: “MOUSE_LEFT_CLICK“.
    Type: String

    query_answer.options_jsonPermanent link for this heading

    Can be used to display additional information of an action in the app.telemetry.
    Type: Object as String

    query_answer.titlePermanent link for this heading

    The title of the document belonging to the answer (title Property).
    Type: String

    query_answer.urlPermanent link for this heading

    The URL of the document belonging to the response (url Property).
    Type: String

    query_answer.commentPermanent link for this heading

    Can be used to log user comments on the respective response. Displayed in the app.telemetry in the "Comment" column.

    query_answer.duration_in_msPermanent link for this heading

    The duration of the user action in milliseconds (e.g. if the user had a preview of the document open for a certain time and then closes it). Displayed in the app.telemetry in the "Duration (ms)" column.

    query_answer.fqcategoryPermanent link for this heading

    The fqcategory (Full Qualified Category) of the document belonging to the response that was involved in the user action. Displayed in the app.telemetry in the "FQCategory" column.

    query_answer.weightPermanent link for this heading

    Can be used to communicate positive or negative user feedback (upvote or downvote). (Floating point number) Usually values are between -1.0 (downvote) and 1.0 (upvote). Displayed in the app.telemetry in the "Weight" column.

    query_answer.answerPermanent link for this heading

    This JSON object describes the response itself. The following subsections discuss the members of this JSON object.

    query_answer.answer.textPermanent link for this heading

    The text of the answer. Displayed in the app.telemetry in the "Answer Text" column.

    query_answer.answer.property_namePermanent link for this heading

    The name of the property from the document from which the answer was generated. Displayed in the app.telemetry in the “Answer Property” column..

    query_answer.answer.text_start_posPermanent link for this heading

    The position of the answer in the associated document. (Integer) Displayed in the app.telemetry in the Answer Start Position column.

    query_answer.similarity_scorePermanent link for this heading

    Floating point value that reflects the quality of the response. It is displayed in the app.telemetry in the column "Similarity Score".

    query_answer.keyPermanent link for this heading

    The key (datasource/mes:key) of the document associated with the response that was involved in the user action. Displayed in the app.telemetry in the "Key" column.

    query_answer.positionPermanent link for this heading

    The result-position of the response that was involved in the user action. Note that the first response has position 0, which would make the tenth response position 9, for example. Displayed in the app.telemetry in the "Result Position" column.

    query_answer.query_contextPermanent link for this heading

    This JSON object describes the context of the search query. The following subsections discuss the members of this JSON object.

    Note: You can also send the query context with the search query.

    query_answer.query_context.application_idPermanent link for this heading

    To uniquely identify an Insight App.
    Default: "Default Application"
    Type: String

    query_answer.query_context.query_trigger_actionPermanent link for this heading

    Specifies how the search was triggered.
    Example: "submit"
    Type: String

    query_answer.query_context.query_idPermanent link for this heading

    The ID of the search query (as an unsigned number). It is recommended to set a UTC timestamp (milliseconds since January 1, 1970, 00:00:00.000 GMT) of the current time of the query (e.g. in JavaScript using new Date().getTime()). Displayed in the app.telemetry in the "Query ID" column.

    query_answer.query_context.prev_query_idPermanent link for this heading

    This is the query_id that was set in the previous query. Displayed in the app.telemetry in the "Previous Query ID" column..

    query_answer.query_context.refinement_idPermanent link for this heading

    The ID of the search query where filters (= facets) were changed (as an unsigned number). It is recommended to set a UTC timestamp (milliseconds since January 1, 1970, 00:00:00.000 GMT) of the current time of the search query (e.g. in JavaScript using new Date().getTime()). This is displayed in the app.telemetry in the column "Refinement ID".

    query_answer.query_context.prev_refinement_idPermanent link for this heading

    This is the refinement_id that was set in the previous query. It is displayed in the app.telemetry in the "Previous Refinement ID" column..

    query_answer.query_context.propertiesPermanent link for this heading

    An array of JSON objects with key-value pairs to log custom properties in app.telemetry. It is displayed in the app.telemetry in the columns "Custom Property 1" to "Custom Property 10". Therefore, a maximum of 10 custom properties can be added.

    The following example shows how to set the resultcount and language properties in the "Custom Property 1" and "Custom Property 2" columns in app.telemetry:

    "properties": [

        {

            "key": "resultcount",

            "value": "534"

        },

        {

            "key": "language",

            "value": "de-AT"

        }

    ]

    query_answer.scroll_position_in_percentagePermanent link for this heading

    The scroll position in the browser. Can be used, for example, in the close-action of a preview window to keep track of how far a user has scrolled down in the preview window. Values between 0 and 100 are valid. It is displayed in the app.telemetry in the column "Scroll position (%)".

    user_contextPermanent link for this heading

    This JSON object describes the context of the user. The following subsections describe the members of this JSON object.

    Note: You can also send the query context with the search query using api.v2.search (for example, for language and time zone).

    user_context.refererPermanent link for this heading

    This is the URL where the user is currently located. Displayed in the app.telemetry in the following columns:

    • "Referer": the entire URL
    • "Referer Scheme": the scheme of the URL (http/https)
    • "Referer Host": the host name of the URL.
    • "Referer Port": the port of the URL (-1 if no port has been defined)
    • "Referer Path: the path to the URL.

    Example query_result Permanent link for this heading

    The following example illustrates the request format described above.

    HeaderPermanent link for this heading

    Content-Type: application/json

    BodyPermanent link for this heading

    {

        "query_result": {

            "query_context": {

                "query_id": "1552292350743",

                "properties": [

                    {

                        "key": "resultcount",

                        "value": "534"

                    },

                    {

                        "key": "language",

                        "value": "de-AT"

                    }

                ],

                "prev_query_id": "1552292349847"

            },

            "action": "preview",

            "position": 2,

            "weight": 0.5,

            "fqcategory": "Microsoft Exchange:Default",

            "key": "AQMkADU3YjMxNzg0LWE2OTQtNGQ3ZC1iZTFjLWJhMTc0Mzk1NGY4YwAuAAADooiUNxWDyEmjTSU5uGq 5gEAShd4IrQ/NU6YapRuM8OUPQAAAyIAAAA=@AQMkADU3YjMxNzg0LWE2OTQtNGQ3ZC1iZTFjLWJhMTc0Mzk1NGY4YwBGAAADooiUNxWDyEmjTSU5uGq 5gcAShd4IrQ/NU6YapRuM8OUPQAAAyIAAAAkKagZlMRnQ76P/8/misL4AAAAFm8giQAAAA==",

            "comment": ""

        },

        "user_context": {

            "referer": "https://inspire.mydomain.com/apps/client/"

        }

    }

    Example query_answerPermanent link for this heading

    The following example illustrates the request format described above.

    HeaderPermanent link for this heading

    Content-Type: application/json

    BodyPermanent link for this heading

    {

        "query_answer": {

            "action": "vote",

            "weight": 1,

            "url": "smb://companyfileshare/Configuration - Google Drive Connector.pdf",

            "action_trigger_event": "MOUSE_LEFT_BUTTON",

            "query_context": {

                "query_id": "1688131765487",

                "app_tab_id": "Everything",

                "prev_query_id": "1688131765383",

                "query_trigger_type": "AUTOMATIC",

                "application_id": "Default Application",

                "query_trigger_action": "queryURLParameter"

            },

            "result_id": "aHR0cHM6Ly9pbnNwaXJlLm1pbmRicmVlemUuY29tOjg0NDMvand0L3JlYWxtL21hc3Rlci9hcGkvdjEvcXVlcnkvMjMzMDE6NTgy",

            "position": 0,

            "fqcategory": "Microsoft File:/companyfileshare/configuration",

            "key": "smb://companyfileshare/Configuration - Google Drive Connector.pdf",

            "title": "Configuration - Google Drive Connector.pdf",

            "comment": "",

            "answer": {

                "text": "“Exclude Filename Pattern“ If the filename of a document matches this \r\nregular expression, the document is ignored.",

                "property_name": "content",

                "context_before": "Example: application/vnd\\.google\\-\r\napps.* ignores all Google Docs documents.\r\n",

                "context_after": " \r\nFor example: .*\\.zip ignores all ZIP archives.",

                "text_start_pos": 16703

            },

            "similarity_score": 0.3604826331138611

        },

        "user_context": {

            "referer": "https://inspire.mindbreeze.com/apps/client/?query=How%20to%20exclude%20Documents%3F",

            "locale": "de-DE",

            "service_id": "https://inspire.mindbreeze.com/apps/scripts/../../api/v2/",

            "utc_time_zone_differential_in_seconds": 7200,

            "service_url": "https://inspire.mindbreeze.com/apps/scripts/../../api/v2/personalization"

        }

    }

    Download PDF

    • api.v2.personalization Interface Description

    Content

    • Introduction
    • Fields in Personalization Requests
    • Example query_result
    • Example query_answer

    Download PDF

    • api.v2.personalization Interface Description