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.
Alerts
Installation and Configuration
Copyright ©
Mindbreeze GmbH, A-4020 Linz, 2024.
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.
Introduction
Mindbreeze InSpire users have the option of configuring alerts, so that they are informed via mail about changes to a search. By default, a change is recognized as such, if at least one new hit has been found for the respective search since the last alert.
With the help of alerts, users can always be informed about the latest status of the respective search. For example, you can be informed via mail about the latest blog articles or internal company news.
Requirements
Before starting the configuration, the following requirements must be fulfilled:
- Existing database (is per default provided by Mindbreeze)
- Functional mail server
Once these requirements have been fulfilled, the configuration can begin.
Basic configuration
Open the menu item “Configuration” in the Mindbreeze Management Center. Go to the tab “Client Services” and activate “Advanced Settings”. Either create a new client service or open an existing client service.
Make sure that the setting “Requires Authentication” is activated with “Yes”. This setting is necessary in order to be able to use alerts.
To configure alerts, certain settings must be configured in the sections “Alerting Service Settings” and “Resource Persistence Settings”. These sections are described in more detail in the following chapters.
List of settings
Activate “Advanced Settings” to see the following settings.
Note: Mandatory settings are marked with an asterisk (*).
Alerting Service Settings
The section “Alerting Service Settings” contains optional settings for special use cases. Two such use cases are described in more detail in the chapter Configuration for special use cases.
Setting | Description | Example/Default setting |
Disable Alerts for Principal Pattern | Dynamically deactivates alerts for certain users. This is done depending on the user's current principals (determined via the Alerting Principal Resolution plugins). For this setting, a regular expression must be defined in Java, regardless of capitalisation. If a principal matches this regular expression, the alert is deactivated for the user. | Example: notificationdisabled |
Principal Resolution Timeout | Determines how many seconds to wait for the response from a Caching Principal Resolution Service. If a timeout or another error occurs, no alert is sent. | Default setting: 30 |
Use Principal Email Address | If this setting is activated, the recipient's mail address is selected for the alert using the configured Caching Principal Resolution Services. The setting “Principal Email Address Prefix” can be used to specify which principal is selected as the email address. | Default setting: Deactivated |
Principal Email Address Prefix | Defines which principal is used as the email address if the setting “Use Principal Email Address” is activated. The prefix of the desired principal must be specified here. | Default setting: email= Example: The user max.mustermann also has the principal “email=max.mustermann@example.com” via a Principal Resolution Service. If “email=” is configured here as a prefix, “max.mustermann@example.com” is selected as the recipient's email address for the alert. |
Use Email Address from Identity | If this setting is activated, the user's email address is used by the Trusted Peer login user attribute when the user is created. | Default setting: Deactivated |
Email Address Identity Property | Defines the name of the user attribute that is used for the email address. | Default setting: |
Alert Collection
The section “Alert Collection” contains settings that can be used to precisely define alerts. In addition to activating the alerts, you can also define the interval, the mail server and the sender's email address.
Setting | Description | Example/Default setting |
Enable* | Activates the alerts. | Default setting: Activated |
Allow Email subscriptions | If this setting is activated, other email addresses can be entered for each notification. If this setting is deactivated, the user's email address is used. We do not recommend activating this setting for reasons of data protection. | Default setting: Deactivated |
Collection Name* | Defines the name of the collection. This is required, among other things, for the display in the Mindbreeze Client. If the name of two or more collections is identical, the collections are differentiated based on the time. If the names are different, the time of the collection is not used for the differentiation. | Example: Every Monday at 8:00 am |
Collection Path* | Defines the path to the collection. The following format must be considered when defining the path: emailalert/unique_name | Example: emailalert/daily |
Notification Schedule* | Defines when the alert is to be sent. The interval is specified by an extended cron expression. Documentation and further examples of cron expressions can be found Documentation - Mindbreeze InSpire - Extended cron expressions. | Example:
|
Path to Query Templates | Defines the path that leads to the “Query Script” and “Output Format Script” templates. Note: If no path is specified, the default templates are used automatically. | Example: /data/resources/alerts |
Query Script | Specifies the file name of the query script. The query script defines the search criteria, for example with a more precise search query or a certain number of hits. The query script is empty by default and does not need to be set, as the standard scripts are used automatically. Editing the query script is possible and can be used, for example, to change the definition of when a change should be recognized as such and an alert should be sent. Attention: If you would like to edit the query script, please contact Mindbreeze Support for assistance. | Example: weekly_query.js |
Output Format Script | Specifies the file name of the output format script. The script defines the appearance of the mail that the user will receive. The output format script does not need to be set as the default script is used automatically. Attention: If you want to edit the Output Format Script, please contact Mindbreeze Support for assistance. | Example: weekly_format.js |
Mailserver* | Defines the mail server from which the emails are to be sent. If the same email address is to be used for all notifications, the use of “localhost” is recommended. This automatically adopts the email address that was stored in the setting “SMTP Server” in the section “Global settings”. You will find the section “Global settings” in the main menu item “Setup” in the submenu item “InSpire”. | Example:
|
Sender of alert emails | Defines the email address from where the emails are to be sent. | Example: sender@mailserver.com |
* = These settings must be configured for the alert to work properly. All other settings must be configured depending on the application. | ||
Resource Persistence Settings
The section “Resource Persistence Settings” contains settings for handling the user database. In addition to the activation of persisted resources, you can also define the URL of the database and the user and password for the database.
Description | Example/Default setting | |
Enable* | Alerts are activated with this setting. This enables access to persisted resources, which is necessary, so that alerts can access database entries. | Default setting: Activated |
User Administrator Users | Defines the user administrators who manage all users by deleting or editing users. For example, user administrators can edit the email address of users. Each user is specified per line with the user name. The user name can also be an email address, for example. For more information, see the chapter Management of users. | Example: david.porter@mindbreeze.com |
JDBC URL* | Defines the URL of the database. | Example: jdbc:postgresql://localhost:5432/persistedresources |
Max Number Of Database Connections | Defines the maximum number of database connections. A value of at least 2 must be specified. If the value is less than 2, this setting does not work. | Default setting: 10 |
User* | Defines the user for the database. Note: The user is configured correctly in the standard configuration. If a new client service is to be created, the user must be configured again by the administrator. This also applies to the setting “Password”. | Example: davidporter |
Password* | Defines the password for the database. Note: The password is configured correctly in the standard configuration. If a new client service is to be created, the password must be configured again by the administrator. This also applies to the setting “User”. | Example: Passwort123 |
Database Table Prefix* | Defines the table prefix in the database. The table prefix is required if several client services are operated where persisted resources are also available. If these client services are not to be shared, different prefixes can be specified here to differentiate between them. | Default setting: persistedresources |
Creation of an alert
Once the alert service has been configured, you can start creating an alert. Please note that a logged-in user is required to create alerts in the Mindbreeze Client.
It is also possible to create an alert without a logged-in user, in which case a new user is automatically created. You can find more information about this in the chapter Creating an alert with a non-existent user.
The creation of an alert is demonstrated with an example in the following chapter.
Example: Creation of an alert for search results for Large Language Models
The aim of this example is to create an alert that informs the user when there are changes to the search with the search term “Large Language Models”. The following steps must be carried out.
Open the Mindbreeze Client and enter the search term “Large Language Models”.
Open the alerts service by clicking on the bell symbol in the top right-hand corner.
Click on “Add new alert”. There you can configure the alert and give it a title and a description. Use “Frequency of notifications” to specify how often you would like to receive an alert by email. Define a “Group Tag” or, if available, select a group if this alert is to be handled together with other alerts. This would be the case, for example, if you want to be informed about two search terms that cannot be handled with one search query. If no group is specified, the alert is automatically added to the “General” group.
For this example, the notification is given the title “Large Language Models Alert”, the description is “Alert for Large Language Models” and the frequency of notifications is set to “Every Friday”. A group tag is not required.
Before adding the alert, you can specify the search term more precisely below or set filters if necessary.
For this example, an additional filter is set so that only search results from the year 2024 are displayed.
Finally, click on “Add notification” to create the alert. This is now displayed in “My alerts”.
Creating an alert with a non-existent user
It is also possible to create an alert without an existing user. The additional fields “E-Mail” and “Username” must be specified to add the alert.
By adding the alert, a user is created automatically with the specified email address and username. The automatically created user can be found in the submenu item “User”.
For more information on managing users, see the chapter Management of users.
Note: If the setting “Allow Email subscriptions” is activated, every user can specify any email address for an alert without a user being created automatically. For more information, see the chapter Alert Collection.
Management of alerts
If the notifications are activated and set correctly, you will see a new submenu item called “Alerts” under the main menu item “Insight Apps” in the Mindbreeze Management Centre. There you will find a list of all existing alerts.
Editing alerts
In Management Center
With the administrator role, you are authorized to view details of the alerts and edit the description of each alert. You can edit an alert by clicking on the pencil icon in the line of the respective alert. A window will then open where you can view the details of the alert and edit the “Description”. To save the changes, click on “Save”.
In the Insight Apps Client
Alerts can also be edited in the Insight Apps client. To do this, click on the bell icon in the top right-hand corner of the client. A window opens where all alerts are listed.
You can edit a notification by clicking on the pencil symbol in the line of the respective alert. Another window opens where you can edit the “Title”, “Frequency of notifications” and “Group Tag”. Further down, you can also change the search, filters and other aspects. To save the changes, click on “Update notification”.
Deleting alerts
You can delete an alert by clicking on the bin symbol in the line of the respective notification.
Attention: Clicking the bin symbol deletes the notification immediately and cannot be restored.
Management of users
If the alerts are activated and set correctly, you will see a new submenu item called “Users” under the menu item “Insight Apps” in the Mindbreeze Management Center. There you will find a list of all existing users.
As an administrator, you are authorized to create new users and to edit and delete existing users.
Creating new users
A new user is created by clicking on “Add user” and entering a “Username” and an “E-Mail” in the window that appears. The new user is created with “Add user”.
Editing existing users
You can edit a user by clicking on the pencil symbol in the line of the respective user. A window will then open where you can edit the “User”, “Username” and “E-Mail”. To save the changes, click on “Update user”.
Deleting users
You can delete a user by clicking on the bin symbol in the line of the respective user.
Attention: Clicking the bin icon deletes the user immediately and cannot be restored.
Monitoring
With app.telemetry you can check whether the created alerts are working and what the causes are if the alerts are sent incorrectly or not at all. It also allows you to analyze the alerts in detail.
Open app.telemetry by clicking on the main menu item “Reporting” and then on the submenu item “Telemetry Details”. Then open the section “Client Service”.
In the section “Client Service”, click on “View Telemetry Data” to open the section “Software Telemetry”.
You will see various entries in the section “Software telemetry”. Additional columns must be added so that you can analyze the alerts you have created in detail. To do this, click on ”Columns” in the bar below the entries and search for “Notification” in the following window.
This will now show you all the columns that could contain data about your alerts. If you want to have a general overview of all data, add all columns by clicking on “Add all”. To add only certain columns, click on the plus symbol next to the respective column. Confirm this change by clicking “OK”. The new columns have been added to the end of the table. You can change the position of the columns as required using drag & drop.
You can now analyze the alerts you have created to check how they work and also trace the causes of errors and problems.
Configuration of special use cases
Automatic deactivation of alerts for certain principals (Dedicated Alerting Principal Resolution Service)
By default, alerts use the search and therefore the configured Caching Principal Resolution Services of the data sources can be used as well.
For special use cases, additional Caching Principal Resolution Services can be configured in the client service in the section "Alerting Principal Resolution Plugins". Additionally a custom Plugin Property "MES_SERVICE_CONTEXT" with the value "mindbreeze.service.NotificationService" must be added. These services are called first before the search is performed on the individual data sources.
In addition, the section “Alerting Service Settings” contains further settings for the dedicated Alerting Principal Resolution Service:
- Principal Resolution Timeout
- Disable Alerts for Principal Pattern
- Use Principal Email Address
- Principal Email Address Prefix
For more information on the respective settings, see the chapter Alerting Service Settings.
For more information on Caching Principal Resolution Services, see Installation and Configuration - Caching Principal Resolution Service.
Automatic adaptation of the email address based on the identity
When a user sets up an alert for the first time, the user can specify an email address as the receiver. Under certain conditions, the email address can be set or corrected automatically. For this, a user login via Trusted Peer must be used in the client service. It must be assured, that the email address is available as user attribute.
For more information about Trusted Peer Authentification, see Trusted Peer Authentication for Mindbreeze InSpire - Sending User Properties.
In addition, the section „Alerting Service Settings“ contains settings for the automatic adaptation of the email address based on the identity:
- Use Email Address from Identity Disable Alerts for Principal Pattern
- Email Address Identity Property Principal Email Address Prefix
For more information on the respective settings, see the chapter Alerting Service Settings.