Setting up notifications to create alerts or reports

Notifications allows you to monitor a variety of alerting scenarios based on saved searches (saved search queries). You can have saved searches run automatically on regular schedules so that they send alert messages to the specified destination, when their results meet certain conditions.

You can configure a variety of conditions to continuously monitor logs by getting real-time events (along with a report) delivered to your email address or to send events to the notification destinations selected.

The following information can help you understand the notification creation process:

Icons and associated functions on the Notifications tab

The Notifications tab allows you to manage the notifications that you configured. To access this tab, navigate to Administration > Notifications. From here, you can perform the following actions:

ActionIconDescription
Execute NotificationExecute the selected notification immediately.
Add Notification

Add a new notification.

For detailed instructions on adding a notification, see Setting up notifications to create alerts or reports.

Edit Notification

Edit the selected notification.

The details for editing a notification are the same as those available while 

Delete NotificationDelete the selected notification.
View Notification Alerts

View the last 25 alerts executed for the selected notification.

The Notifications tab provides the following information:

Field

Description

Name

Name of the notification configured.

TypeThe type of notification, either an alert or report.

Next Run

The date and time when the next run is scheduled for execution.

Destination(s)
The destination (external configuration) where the notification is scheduled to be sent.

Active

Indicates if the notification is active or not.

Click Activate  to activate the notification.

Click Inactivate  to inactivate the notification.

Notification creation process

While creating a notification, you need to provide information regarding when, how, and where the notification must be sent.

This information can be categorized into the following inputs:

InputDescription
Notification naming details

Basic information by which you can identify and manage the notification.

Notification type

Determines the type of notification that you want to create – an alert or a report.

The notification type also determines the notification destination options and the number of conditions that you can configure.

Scheduling detailsDetermines the frequency for triggering a notification.
Notification destination(s)

Based on the notification type, the notification destination determines where the notification must be sent.

You can select multiple options available while configuring an alert.


Before you begin

Ensure that the following requirements are met:

  • Ensure that the saved searches that you want to use while creating the notification are already present.
  • Ensure that the external configurations or script that you want to use as the notification destination is already created.

Creating a notification

On the Administration > Notifications tab, click Add Notification, provide the following information, and click Create.

Step 1: Specify notification naming details

Under the Notification Details section, provide the following information:

  • Name: Provide a name to identify this notification.

    Note

    Notification names must be unique across users. If you try to create a notification with a name that already exists, you get an error.

  • Description: (Optional) Provide some additional information for this notification to act as a future reference.

    By default, this field is automatically populated with the saved search description.

Step 2: Specify the notification type

When you create a notification, by default the notification type is set to Alert.

You can create two types of notifications – an alert and a report. Alerts can be used for logging events on external systems, sending email notifications, and specifying script paths based on which notifications are sent. Reports can be used for sending an email notification and optionally attaching a PDF report containing details about the search string.

The following links provide additional information about the inputs applicable to the notification type selected.

Step 3: Specify the scheduling details

Provide the following inputs to define details regarding the frequency of the notification and the duration for which the notification must be run.

FieldDescription
Scheduling

(Optional) Specify the time schedule when the notification must be sent.

By default, the schedule is set to every 1 minute.

You can specify the schedule frequency on an hourly, daily, weekly, monthly, or yearly basis and also specify options for the frequency. This means that suppose you select Yearly, you can specify the month, day, and time at which the notification must recur.

Example: When you select Yearly, the options can be set as, "Every January, 5th, at 08 : 15 hours". This selection indicates that you want the notification to be sent on January 5, at 8.15 AM, every year.

Notes:

  • The monthly frequency scheduled assumes January to be the starting point. When you create a notification, the next run happens as per the monthly schedule specified in the notification, but considering January as the starting point. Also, on the Notifications page, the next run information (under the Next Run column) is displayed based on the current date and the upcoming schedule considering January as the starting point.
    Example: Suppose you schedule the notification for the second day of every quarter (which means on the second day of January, April, July, and October). And suppose you created the notification on March 15, this means the next run is assumed to be on 2nd April (considering January as the starting point).
  • By default, the product can execute approximately 100 notifications every minute with the notification thread pool size set to 10.
    Suppose you have 200 notifications scheduled to execute every minute, then it is recommended that you increase the notification thread pool size to 20. This is necessary to avoid delaying the notification triggers or missing them altogether.
    To increase the notification thread pool size, change the value of the property, notification.threadpool.size in the searchserviceCustomConfig.properties file. For more information about the file path, see Modifying the configuration files.
    This property governs the number of active notifications thread. By default, this property is set to 10.
Search Duration

(Optional) Select one of the time ranges to determine the duration for which the notification must be run.

When you select a saved search, the search duration changes to the time context of the saved search. You can override this by manually selecting the search duration.

Default: Last execution to current execution

Notes: The following capabilities are only applicable while configuring an alert:

  • Exclude duplicate events (determined by the Exclude duplicate events feature).
  • Search for application names from TrueSight Operations Management (determined by the Application Name feature).

For more information, see Report configuration details. 


Step 4: Specify the notification destination

The notification destination determines the following details:

  • Where notification is sent – determined by the notification destination options that you select.
  • How the notification is sent – determined by the template used in the notification destination.

For more information, see Notification destination details.

Alert configuration details

You can trigger an alert based on a combination of conditions. To specify conditions, you need to already have saved searches created. Based on these saved searches, you can configure an alert. The search string and the time context of the saved search act as the base for creating the alert. When you configure a notification alert, the saved searches included in the notification are run. If the number of results obtained for that saved search meets the condition added in the notification, an alert is triggered.

You can select multiple saved searches and specify conditions regarding the number of results for each of these saved searches. You can also specify whether all (AND) or either (OR) of the conditions must be met before an alert is triggered.

The following table describes the inputs that you need to specify for configuring an alert.

FieldDescription
When to send a notification?
Saved Search

Select the saved search for which you want to create a notification. Consider reading the notes related to selecting a saved search.

Based on the saved search that you select first, the search duration is automatically populated. You can manually change this selection.

Tip: While selecting the saved search name, you can specify any portion of the saved search name. You can even specify the content pack name via which the saved search was imported. If a saved search is imported via a content pack, the content pack name is displayed next to the saved search name in square brackets.

Number of Results

Specify a condition to trigger a notification: if the number of results is to be less than (select <), equal to (select =), or more than (select >) the selected threshold (specify a number).

Example: If you set the number of results to greater than 100 (> 100). If the results for the search string exceed 100, a notification is automatically sent.

Actions

Click Add Saved Search  to add the saved search and associated condition. You can add multiple saved searches with associated conditions. Based on these conditions an alert is triggered. You can also define whether all the conditions or either of the conditions must be used to trigger the alert. This can be done by selecting the AND or OR operation.

To delete a saved search with its associated condition, click Remove Saved Search .

How often to send a notification?
Scheduling

Determines the frequency of sending the alert.

For more information, see Scheduling details.

Search Duration

Determines the duration that must be used while running the saved search.

For more information, Schedulingdetails

Do you want to use an external system as the notification destination?
Exclude duplicate events

This feature is applicable only if you want to use one of the supported external systems (for example, ProactiveNet) as the notification destination.

Determines whether you want to exclude duplicate events returned from a supported external system. For example, ProactiveNet. This is applicable when you are already monitoring data coming from the external system in TrueSight IT Data Analytics.

Perform one of the following actions:

  • To include all events that the external system returns, clear this check box.
  • To avoid duplicate events that were already notified, keep the check box selected.

Notes:

  • This field is not applicable while configuring a script alert, email alert, and report.
  • If you select this check box, each time the notification is run, it appends the saved search query with && ((CLASS <> "ITDA_Event")). Also, if you set an email notification or cross-launch to TrueSight IT Data Analytics, then the saved search query is appended with && ((CLASS <> "ITDA_Event")).
Application Name

This feature is applicable only if you want to use TrueSight Operations Management as the notification destination.

You can search for an application (by name) configured on TrueSight Operations Management with which you want to associate the event that will be logged. This means each time a notification alert is sent to TrueSight Operations Management and an event is logged, that event is automatically associated with the application specified.

Where to send a notification?
Notification Destination(s)

Report configuration details

You can configure a report to send an email notification and optionally attach a PDF report containing details about the search string. An email is sent containing the search string, the result count, and a link that takes you to the specific search context. Furthermore, you can select whether or not to attach a report and include log entries in the report.

Note

By default, the report provides details about search results displayed on the Search tab within one minute. To change this time limit, you can add the property, indexing.psJobGetMoreTimeoutInmsec by navigating to the searchserviceCustomConfig.properties file. This property defines the time limit (in milliseconds) after which the search (including notifications and views) times out. For more information, see Modifying the configuration files.

The following table describes the inputs that you need to specify for configuring a report.

InputsDescription
When to send a notification?
Saved search

Select the saved search that must be used for configuring the report. Consider reading the notes related to selecting a saved search.

After you create the notification, the selected saved search is run for the duration included in the saved search results and the results of the saved search are sent as a PDF report.

Unlike an alert, while configuring a report, you can only specify one saved search at a time.

Tip: While selecting the saved search name, you can specify any portion of the saved search name. You can even specify the content pack name via which the saved search was imported. If a saved search is imported via a content pack, the content pack name is displayed next to the saved search name in square brackets.

How often to send a notification?
Scheduling

Determines the frequency of sending the report.

For more information, see Scheduling details.

Search Duration

Determines the duration that must be used while running the saved search.

For more information, see Scheduling details.

Where to send a notification?
Email Destination

Determines the SMTP server that must be used for sending emails.

The notification destination name is displayed in the format Email:extConfigName, where extConfigName refers to the name that you used while creating the external configuration for integrating with an SMTP server. For more information, see Setting up emails.

Depending on the SMTP server with which you want to connect for sending email notifications, select the appropriate check box.

For more information, see Notification destination details.

Notes: The following capabilities are not applicable while configuring a report:

  • Exclude duplicate events (determined by the Exclude duplicate events feature).
  • Search for application names from TrueSight Operations Management (determined by the Application Name feature).

Notification destination details

The notification destination determines the following details:

  • Where notification is sent – determined by the notification destination options that you select.
  • How the notification is sent – determined by the details (including template) specified after selecting the notification destination.

While creating a notification, you need to perform the following steps:

Step 1: Select the notification destination option

The notification options selected determines where the notification is sent. This selection depends on the notification type selected – alert or report.

The following table provides information about the notification destination options available for the notification types.

Notification typeNotification destination options
Alert

The following options are available while configuring an alert:

  • Supported external systems: You can select the external systems into which you want to log events.
    For more information about the external systems supported, see Integrating.
    The notification destination name usually starts with "TSIM" or "TSPS".
  • SMTP server: You can select the SMTP server that must be used for sending the email alert.
    The options available for configuring an email alert are same as those available for configuring a report.
    The notification destination name usually starts with "Email".
  • Script: You can select the option to run a script and provide the script path that must be used for sending the notification.
    The notification destination name is Script: Run a script.
    Note: In the script path, you cannot direct the script output to a file directly. But you can point to some other file containing a script that in turn will redirect the initial script output to the correct file.
Report

While configuring a report, you can select the SMTP server that must be used for sending the email alert.

The notification destination name usually starts with "Email".

The various notification destinations are explained as follows:

 ProactiveNet (or Infrastructure Management) server

The notification destination name is displayed in the format TSIM: hostName_cellName, where hostName and cellName refer to the host name and cell name of the ProactiveNet server that you used while creating the external configuration for integrating with ProactiveNet.

The same notification destination can be used for logging events into TrueSight Infrastructure Management.

For more information about creating an integration, see Integrating with Infrastructure Management and ProactiveNet.

Note: If you want to use ProactiveNet as your notification destination, then to be able to log events correctly into the cells selected, you need to ensure that the BAROC files are loaded on the selected cell.

For more information, see Sending events to ProactiveNet 9.6 .

 ProactiveNet (or Infrastructure Management) cells

The notification destination name is displayed in the format TSIM-Cell:extConfigName, where extConfigName refers to the name that you used while creating the external configuration for integrating with the ProactiveNet cell.

The same notification destination can be used for logging events into TrueSight Infrastructure Management cells.

For more information about creating an integration, see Integrating with Infrastructure Management and ProactiveNet cells.

Note: If you want to use ProactiveNet or TrueSight Infrastructure Management as your notification destination, then to be able to log events correctly into the cells selected, you need to ensure that the BAROC files are loaded on the selected cell.

For more information, see Sending events to ProactiveNet 9.6 .

 TrueSight Presentation Server

 Email notification

The notification destination name is displayed in the format Email:extConfigName, where extConfigName refers to the name that you used while creating the external configuration for integrating with an SMTP server. For more information, see Setting up emails.

Depending on the SMTP server with which you want to connect for sending email notifications, select the appropriate check box.

 Script

Provide the script path that must be used for sending the notification.

The script must contain the instructions for sending the notification. Each time the condition for sending a notification is met (for example, Number of results > 100), the script is run.

Notes:

  • If you have installed multiple Search components in your environment, you need to ensure that the script is present on each of the hosts (where the Search component is installed) and the location path is the same across all hosts.
  • Before providing the script path, ensure that you take sufficient measures to prevent unauthorized access to the script. For example, ensure that the script file cannot be read by unauthorized users.
  • By default, the script timeout is set to 60 seconds. This is controlled by the notification.scripts.timeout property located in the searchserviceConfig.properties file. For more information, see Modifying the configuration files.

Tips:

Step 2: Specify the notification destination details

After you select the notification destination option, you need to provide some details that determine how the notification must be sent.

These details vary depending on whether you want to configure an alert or report. The details required to configure an alert refer to two kinds of notification destinations – supported external systems and script. The details required to configure an email alert or report are the same. If you specify a script notification destination, then you need to specify the script path. For more information about the script notification destination, see Notification destination options.

The following sections describe the details required for logging an event on an external system and for sending email notifications.

Logging events on external systems

After you select the notification destination for logging events, provide the following details:

FieldDescription
Template selection

Select a template that you want to use for logging an event. This template carries details regarding the logged event such as, the saved search name, number of search results, start and end time of the search query, and so on.

You can use the default template or create your own new template for logging an event. While creating a new template, you can use default macros in the event message. For more information, see Creating templates with custom notifications messages.

Event severity

Specify the severity level of the event that you want to log into the selected notification destination (for example, ProactiveNet) for this notification.

You can select one of the following options:

  • (Default) CRITICAL
  • MAJOR
  • MINOR
  • INFO
  • WARNING

Sending email notifications

After selecting the email notification destination, specify the inputs listed in the following table.

FieldDescription
Template selection

Select a template that you want to use for sending an email notification. This template carries details regarding the notification message that must be sent, such as the saved search name, number of search results, start and end time of the search query, and so on.

Send Email toProvide a comma-separated list of email addresses to which the notification must be sent.
Attach Report(Optional) Select this check box if you want to attach a PDF report.
Include Log Entries

(Optional) Select this check box if you want to include log entries in the PDF report (maximum first 1,000 entries).

This field is available only after you select the Attach Report check box.

Summarization Field

(Optional) Select the field by which you want to summarize the chart that will be a part of the report.

This field is available only after you select the Attach Report check box.

Chart Type

(Optional) Select one of the following chart types for summarizing the search results, and include it in the report:

  • (Default) Bar
  • Pie

Click Preview to view the PDF report.

Creating templates with custom notifications messages

While configuring an alert or report, you can choose to use the default template or create a new template with custom messages to send notifications. This section does not apply to a script alert.

Depending on the notification destination selected, the following kinds of templates can be created:

  • Template for logging events on a supported external system
  • Template for sending email notifications

To create a template, select a notification destination, click Create on the left panel, and provide the following details depending on whether you are creating a template for logging an event or sending an email.

While creating a template for logging an event on an external system configured, provide the following details and click Save:

  • Name: An appropriate name to identify the template.
    You can search by template name on the left panel.
  • Message: Details of the event that must be displayed on the external system where the event will be logged.
    This can contain details such as the saved search name, search string, start and end time when the saved search was run, and so on. You can use default macros while adding such details in the message. These macros are substituted with appropriate values at run time. For more information, see Setting up notifications to create alerts or reports.

To edit a template, after selecting the notification destination, click a template on the left panel, and click Edit. Make your changes and click Save.

To delete a template, after selecting the notification destination, click a template on the left panel, and click Delete.

While creating a template for sending an email, provide the following details and click Save:

  • Name: An appropriate name to identify the template.
    You can search by template name on the left panel.
  • Subject: Subject for the email.
  • Message: Contents that must appear in the email body.
    This can contain details such as the saved search name, search string, start and end time when the saved search was run, and so on. You can use default macros while adding such details in the message. These macros are substituted with appropriate values at run time. For more information, see the following links:

To edit a template, after selecting the notification destination, click a template on the left panel, and click Edit. Make your changes and click Save.

To delete a template, after selecting the notification destination, click a template on the left panel, and click Delete.

Macros for creating notifications

Macros denote objects that can be used to substitute common details specified while creating a notification. For example, saved search name, search string, count of results, and so on. The macros are substituted with appropriate values at run time when the notification is triggered.

You can use macros in the following ways:

  • While creating templates, in the Message field while creating templates.
  • While creating script notifications, in the script itself.
    In the script, macros are passed as environment variables.

If you specified multiple conditions (or multiple saved searches) in the notification, then some macros can take multiple values. For example, the ${QUERYNAME} macro can take multiple values. Macros with multiple values can be accessed as an array. For example, to access the first value of the macro ${QUERYNAME}, you need to specify ${QUERYNAME[0]}. Similarly, to access the second value of this macro, you need to specify ${QUERYNAME[1]}.

To see an example of how macros can be used in the message while sending email notifications, see Example of the template message for sending emails.

The following table provides a list of default macros that can be used in the Message field while creating a template.

Macro SyntaxMacro description
${NAME}Name of the notification that was used for logging the event or sending the email notification.
${QUERYNAME}

Name of the saved search used in the notification.

If you specified multiple conditions (or multiple saved searches) while creating the notification, then the value can be a comma-separated list.

${QUERYSTR}

Search string used corresponding to the saved search name.

If you specified multiple conditions (or multiple saved searches) while creating the notification, then the value can be a comma-separated list.

${COUNT}

Number of search results returned by the search query.

If you specified multiple conditions (or multiple saved searches) while creating the notification, then the value can be a comma-separated list.

${STARTTIME}

Indicates the start point for the search duration.

${ENDTIME}

Indicates the end point for the search duration.

${URL}

The URL for logging on to TrueSight IT Data Analytics.

${HOST}

Name of the target hosts from which the data is collected.

Note: If the search query used in the notification is not specific to a particular host, then instead of the actual host name, the macro displays the value as "multiple hosts".

${APPNAME}

Indicates the name of the application configured in TrueSight Operations Management, that you specified at the time of configuring an alert or report.

Note: To use this macro, you must have already integrated TrueSight IT Data Analytics with TrueSight Operations Management. For more information, see Integrating with TrueSight Presentation Server.

${APPID}

Indicates the ID associated with the application configured in TrueSight Operations Management, that you specified at the time of configuring an alert or report.

Note: To use this macro, you must have already integrated TrueSight IT Data Analytics with TrueSight Operations Management. For more information, see Integrating with TrueSight Presentation Server.


Example of the template message for sending emails

The following table provides an example of a template message and the actual message used for sending an email notification.

Template messageActual message (email body)

Saved search ${QUERYNAME} has result count: ${COUNT} for duration: [${STARTTIME}] to [${ENDTIME}]

<div>Dear User,</div><br/><div>

This email is for information only. Please do not respond to it.</div><br/><div>

The configured notification, ${NAME} containing query, [${QUERYSTR}], with name ${QUERYNAME}, has been triggered. </div><br/><div>

Result Count: ${COUNT}, Launch URL: ${URL}</div><br/><div>

You can login and change the notification. Click <b> Administration > Notifications</b> to navigate to the notifications page.</div>

Saved search ITDA_Log_Monitoring has result count: 3567 for duration: 01/30/2015 11:30:30 GMT to 02/06/2015 11:30:30 GMT

Dear User,

This email is for information only. Please do not respond to it.

The configured notification ITDA_Log_Monitoring_Notification, containing query, COLLECTOR_NAME="ITDA_logs", with name ITDA_Log_Monitoring, has been triggered.

Result Count: 3567, Launch URL: Show in BMC TrueSight IT Data Analytics

You can login and change the notification. Click Administration > Notifications to navigate to the notifications page.

Notes about using a saved search in a notification

The following notes are important to keep in mind while selecting a saved search to create a notification:

  • Saved searches with custom time range are not displayed in this list. This is because such saved searches are run for a fixed duration and therefore are not relevant for adding notifications.
  • Saved searches imported via a content pack are subject to changes with a content pack update. If you want to avoid any future changes made to the saved search (that is used in the notification), you can first clone the saved search by navigating to the Saved Searches tab and then create the notification based on the cloned copy. For more information about the changes that can occur with a content pack update, see Creating and managing Content Packs.
  • If you create a notification based on a public saved search and if that saved search is deleted, a private copy of the saved search is automatically created so that objects configured based on the deleted saved search continue to function. The private copy details are automatically updated in the notification and listed on the Saved Searches page. Also, the user who created the notification becomes the owner of the private copy. A public saved search can have the following sources. The private copy name differs based on the type of source.
    • Imported via a content pack: Based on this source, the private copy is named as "Copy of <SavedSearchName> from <ContentPackName>".
    • Created by another user: Based on this source, the private copy is named as "Copy of <SavedSearchName>".
    Note that if the owner of a public saved search turned the saved search into a private one (by clearing the Make Public check box), then a private copy of that saved search is created. The users using the original public saved search in the notification become owners of the private copy. The private copy details are automatically updated in the notification.
  • If you create a notification based on one saved search only, then deletion of the saved search can result in deletion of the notification. But if the notification contains multiple saved searches, and if one of the saved searches is deleted, the deleted saved search is automatically removed from the notification.
Was this page helpful? Yes No Submitting... Thank you

Comments