Creating notifications

The Notifications tab allows you to create notifications. Saved searches are the building blocks for creating notifications.

This topic contains the following information:

Related topics

Where to find more information

Search-tab

Managing-dashboards

If a problem occurs

Where to find troubleshooting information

Troubleshooting-common-issues

Known-and-corrected-issues

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.

Notification creation process overview

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:

To create 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.

The [liveData] macro is a standalone macro and it cannot be used inline. Click on this message for 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.

The [liveData] macro is a standalone macro and it cannot be used inline. Click on this message for details.

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.

The [liveData] macro is a standalone macro and it cannot be used inline. Click on this message for details.

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 type

Notification 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 "BPPM" 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.

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:

BMC ProactiveNet (or Infrastructure Management) server

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

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

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

Note: If you want to use BMC 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 BMC ProactiveNet 9.6

.

BMC ProactiveNet (or Infrastructure Management) cells

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

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

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

Note: If you want to use BMC 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 BMC ProactiveNet 9.6.

BMC TrueSight Presentation Server

The notification destination name is displayed in the format TSPS:extConfigNameAndCellName, where extConfigNameAndCellName refers to the name of the external configuration displayed under the Administration > External Configurations page. The external configuration name is followed by the cell name specified in the external configuration. For more information, see Integrating-with-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:

  • You can also pass static parameters while executing the script.
  • You can use macros in the script that are available as environment variables. For more information, see Macros for creating notifications.

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:

Sending email notifications

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

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 Macros for creating notifications.

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.

The [liveData] macro is a standalone macro and it cannot be used inline. Click on this message for details.

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.

The [liveData] macro is a standalone macro and it cannot be used inline. Click on this message for details.

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 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.