Advanced options for working with custom alert actions

Learn how to use additional features of custom alert actions.

Invoke a custom alert action from a search

You can invoke an alert action by name using the sendalert command as part of a search. For testing purposes, you might want to invoke an alert action directly from search. You can pipe your search to sendalert and pass in parameters.

Here is the sendalert syntax.

sendalert <action-name> [options]

• <action-name> refers to an alert action in either alert_actions.conf or savedsearches.conf.

• [options] allows you to pass in key-value arguments starting with param. Each param. argument is merged with the corresponding token from alert_actions.conf.

For more information about using this command, see sendalert in the Search Reference.

Pass search result values to alert action tokens

You can pass search result values to different alert action tokens when you use sendalert.

There are several available custom alert action tokens.

Token	Description
$result.<fieldname>$	Any field value from the first row of the search results
$job.<property>$	Any search job property
$server.<property>$	Properties returned by the server info endpoint
$app$	Name of the app containing the search
$cron_schedule$	Cron schedule for the alert
$description$	Search description
$name$	Name of the search or alert
$next_scheduled_time$	The next time the scheduled search runs
$owner$	Owner of the search
$results_link$	Link to the search results
$search$	Actual search string
$trigger_date$	Date when alert was triggered
$trigger_timeHMS$	Formatted time when the alert was triggered
$trigger_time$	Trigger time in unix epoch
$alert.severity$	Alert severity level
$alert.expires$	Alert expiration time

Custom alert action tokens work similarly to tokens for email notifications. To learn more, see Use tokens in email notifications.

Example

As an example, you might want to search for login failure events. You can pass the search results and some informational text to the param.message key. Then, you can use the $result.<field_name>$ token to hold the corresponding field's value from your search results.

Here is what your query would look like.

index=_internal component=UiAuth action=login status=failure | sendalert chat param.room="Security Team Room" param.message="Login failed for user: $result.user$"

In this case, user is the result field name.

After receiving search results showing an admin role, the value passed to the alert script might look like this.

param.message = "Login failed for user: admin"

---

Access alert action script logs

Developers can access logs of the alert action script using the Alert Actions manager page. Any information that your script prints to STDERR will be treated as a log message. Message prefixes, such as DEBUG, INFO, WARN, or ERROR, are treated as the log level.

To review logs for an alert action, select Settings>Alert actions. This takes you to the Alert Actions manager page. Select View log events for your alert action.

Custom alert action logging is similar to modular input logging. For more information, see Set up logging.